Command line

Build, run, check and format code with the valk command.

On this page

The valk command compiles, runs, checks and formats code. Every command takes a directory, such as src, or one or more .valk files.

Build an executable#

Terminal

valk build src -o app              # write ./app (app.exe on Windows)
valk build src -o app --release    # optimized
valk build hello.valk -o hello     # a single file works too

Unchanged files are not compiled again on the next build. --clean ignores that cache.

Build and run#

Terminal

valk build src -o app --run         # build, then start it
valk run src -- alice bob           # build and run; program arguments go after --
valk build src -o app --run --watch # rebuild and restart when a file changes

The program reads its arguments in main, see Functions.

Run tests#

Terminal

valk build src --test --run
valk build src tests --test --run                  # tests kept in their own directory
valk build src tests --test --filter "login" --run # only tests whose name contains "login"

See Testing for writing tests.

Check without building#

Terminal

valk build src --lint

--lint reports errors and warnings for every source file of the package, without needing a main and without writing an executable. Add --all-errors to list every error instead of only the first.

Format code#

Terminal

valk fmt src           # format in place, list the files that changed
valk fmt src --check   # list unformatted files and exit 1, write nothing (for CI)

Look up documentation#

Terminal

valk doc Array.sort             # one declaration of the standard library
valk doc http.Server            # a type and its members
valk doc . Client.request       # a declaration of the package in this directory
valk doc . --markdown -o api.md # docs for a whole project

The text comes from the /// comments above declarations, see Documentation comments.

Common build options#

Option	Effect
`-o path`	Output path
`--run`, `-r`	Run after building
`--watch`, `-w`	Rebuild when a file changes
`--test`, `-t`	Build the tests instead of `main`
`--release`	All optimizations, no symbol table
`--debug`, `-d`	Debug info, stack trace on panic (Debugging)
`--target name`	Build for another platform: `linux-x64`, `linux-arm64`, `macos-x64`, `macos-arm64`, `win-x64` (Cross compiling)
`--cpu name`	Use the CPU features of `native` or a named CPU such as `x86-64-v3`
`--def A=1,B=2`	Set compile-time definitions
`--no-warn`, `-nw`	Hide warnings
`--clean`, `-c`	Ignore the build cache
`-v`, `-vv`, `-vvv`	Show compile details

valk build -h lists every option.

Project commands#

A project can name its own build and run steps under make in valk.json:

JSON

{
    "make": {
        "app": { "dir": "src", "args": "-o ./app" },
        "test": ["valk build src tests --test -o ./test-bin", "./test-bin"]
    }
}

Terminal

valk ls          # list the project's commands
valk make app    # run one
valk make        # run the first one

An entry with dir is compiled with args; a line or a list of lines is run as shell commands.

Editor and shell support#

valk lsp run starts the language server; the VS Code extension runs it for you.
valk completion bash prints tab completion for bash; zsh and fish also work.
valk version prints the compiler version. Use vman to install or switch versions, see Projects & packages.

View page source ↗