The dusk CLI

The dusk binary drives the compiler. It has eight commands: lex, scan, parse, check, build, run, demo, and version. Running dusk with no command, or with help, -h, or --help, prints the usage text; an unknown command prints the same text and exits with a failure status.

dusk 0.3.3 - compiler for the dusk language

usage:
  dusk demo            build + run the Phase 0 LLVM spine
  dusk lex <file>      dump the token stream
  dusk scan <file>     dump paradigms + imports (pre scan)
  dusk parse <file>    lex + parse, dump the AST
  dusk check <file>    lex + parse + resolve + typecheck
  dusk build <file>    compile to a native binary
  dusk run <file>      compile and run
  dusk version         print version

To install the toolchain in the first place, see getting started. The package tool dawn has its own page at dawn.

Inspection commands

The first three commands expose the front end one stage at a time. Each takes a single source file, prints its result to stdout, reports diagnostics on stderr, and exits with a failure status when there are errors.

lex

dusk lex <file> dumps the token stream. Each line shows the token’s byte span in the source followed by the token kind.

scan

dusk scan <file> runs the pre scan, which reads only the file’s directives, and prints the effective paradigm set and the import list.

dusk scan examples/app.dusk

paradigms: [Procedural]
imports:
  std.io
  std.string
  std.functional.maybe
  std.functional.either
  std.memory.arena

See source files for the @paradigm and @import directives themselves.

parse

dusk parse <file> lexes and parses the file and dumps the resulting AST in the compiler’s debug format, then reports any lex or parse errors.

check

dusk check <file> runs the whole front end: lex, parse, name resolution, and type checking, including the file’s imports. It produces no artifacts. On success it prints ok: followed by the path; otherwise it prints the diagnostics and exits with a failure status.

dusk check examples/app.dusk

ok: examples/app.dusk

build

dusk build <file> runs the front end and then compiles the module to a native binary, printing the binary’s path.

dusk build examples/app.dusk

[dusk] target/dusk-out/app

Code generation goes through textual LLVM IR and links against the toolchain’s small C runtime, so clang and LLVM 22.x must be on your path. The textual IR targets one LLVM major version.

Build artifacts

Artifacts land in target/dusk-out, relative to the directory you run the command from. For a source file app.dusk you get two files named after the source file’s stem:

• target/dusk-out/app.ll, the emitted textual LLVM IR
• target/dusk-out/app, the linked native binary

dusk run and dusk demo use the same directory.

run

dusk run <file> compiles the file exactly like build and then executes the binary. Any arguments after the file are forwarded to the program, so a main declared with argc and argv sees them. The exit status of dusk run is the program’s own exit code.

echo.dusk

@paradigm procedural

// main may take argc and the argv string slice; dusk run forwards
// trailing arguments here.
func main(argc: int32, argv: string[]) -> int32 {
    for arg in argv {
        println(arg)
    }
    return 0
}

dusk run echo.dusk hello world

target/dusk-out/echo
hello
world

As in C, argv element zero is the program path and the forwarded arguments follow, so argv.len matches argc.

demo

dusk demo builds and runs the Phase 0 spine: a hardcoded IR program that is linked and executed without any dusk source involved. It prints the paths of the emitted IR and the linked binary, runs the program, and reports its exit code. Use it as a smoke test that clang, LLVM, and the C runtime are wired up correctly.

version

dusk version prints the toolchain version, for example dusk 0.3.3. The flags --version and -V do the same.

Toolchain asset resolution

The compiler ships two asset directories beside itself: lib, which holds the standard library written in dusk, and runtime, which holds the C runtime sources. Each is resolved by trying three locations in order; the first one that exists on disk wins.

1. DUSK_HOME. If the DUSK_HOME environment variable is set, the compiler looks for the directory under it, as in $DUSK_HOME/lib. Set this to point a binary at a different toolchain tree, such as a source checkout.
2. The share directory beside the binary. An installed toolchain finds its assets two levels up from the running binary, under share/dusk-lang, as in /usr/share/dusk-lang beside /usr/bin/dusk.
3. The crate root. The path of the compiler’s source checkout is baked in at compile time, which keeps cargo test and a source checkout working with no environment at all. When neither earlier candidate exists, this baked path is returned even if it is absent, so the resulting error names a real location.

A cargo install dusk-lang build finds its assets inside the cargo registry checkout through the baked crate root; a packaged install uses the share directory; DUSK_HOME overrides both.