Getting started

Dusk is a small systems language that compiles to native code. This page gets the toolchain onto your machine and takes you from an empty file to a running program.

If you want to try the language before installing anything, the playground runs Dusk in the browser.

Requirements

• clang and LLVM 22.x on your PATH. The compiler emits textual LLVM IR that targets one LLVM major version, so the version matters.

That is the whole list. Dusk builds Dusk now, so there is no other toolchain to install, no Rust and no Cargo. If you want the original Rust compiler for reference, it is archived and covered at the end of this page.

Install

Dusk moves quickly and minor releases still change the language. Installing today means tracking a moving target, which the -git package makes explicit.

On Arch Linux, install from the AUR. This builds the latest main and installs dusk and dawn beside the standard library and C runtime, so a packaged install needs no DUSK_HOME:

paru -S dusk-lang-git
# or: yay -S dusk-lang-git

dusk is the compiler and dawn is the package tool. Verify the install:

dusk version

This prints dusk 1.11.0 (or whichever version you installed).

On any machine, bootstrap from a release artifact instead. Each release tag ships a linux x86_64 dusk binary, the compiler’s own textual IR as dusk.ll.xz, and a sha256sums. From a clone of the repository, tools/bootstrap.sh dusk stands up a compiler from the binary, while tools/bootstrap.sh dusk.ll.xz trusts only text plus clang, linking the IR against the C runtime into a throwaway seed that rebuilds the compiler from source. Both land a fresh compiler at target/dusk-out/dusk. See the roadmap for detail.

Hello, world

Create a file named hello.dusk:

hello.dusk

@paradigm procedural

@import std.io.print_line

func main(argc: int32, argv: string[]) -> int32 {
    print_line("hello, world")
    return 0
}

Run it:

dusk run hello.dusk

hello, world

A few things to notice:

• @paradigm procedural declares the paradigm this program uses. A file can declare one or more @paradigm directives (procedural, functional, or oop); they stack, and the file gets the union of everything they unlock. A file with no directive defaults to procedural. hello.dusk names it explicitly because it uses procedural features. See Paradigms.
• @import std.io.print_line pulls one symbol from the standard library’s io module. The stdlib is itself written in Dusk; see the stdlib overview.
• main returns int32, which becomes the process exit code. dusk run forwards any trailing arguments to the program, so a main declared with argc and argv sees them.

The dusk CLI

The dusk binary has fourteen commands. Three of them compile:

Command	What it does
dusk run <file>	Compile and run
dusk build <file>	Compile to a native binary
dusk ir <file>	Print the generated LLVM IR to stdout, with no clang step

dusk build --lib <file> is the same build pointed at a different target: it compiles the module into a static archive plus a generated C header instead of an executable, so a C program can call your Dusk code. See C libraries.

Eight more stop the pipeline at one stage and dump that stage’s output, which is how you inspect a single pass:

Command	What it does
dusk check <file>	Lex, parse, resolve names, and type check without emitting code
dusk lex <file>	Dump the token stream
dusk scan <file>	Dump paradigms and imports (pre-scan)
dusk parse <file>	Lex and parse, dump the AST
dusk load <file>	Resolve imports, dump the merged AST
dusk desugar <file>	Desugar on top of that, dump the result
dusk mono <file>	Type check, then dump the monomorphized AST
dusk esc <file>	Dump the escape summary oracle

The last three are dusk doc, which renders a module’s doc comments as markdown or, with --json, as a machine model, dusk demo, which builds and runs a hardcoded IR spine as a toolchain smoke test, and dusk version, which prints the version. Two of the compile and check commands also take a flag: dusk check --json reports diagnostics as JSON, and dusk ir --target=wasm32 cross-emits for wasm32-wasip1, the shape the playground is built from.

For day-to-day work you mostly need run, build, and check. Full details are on the CLI page.

For programs that import packages over git, use dawn instead. dawn run <file> fetches the imports and then compiles and runs. See Dawn.

DUSK_HOME

The compiler finds its standard library and C runtime beside itself: in the share/dusk-lang directory for a packaged install, or in the build tree for a bootstrapped compiler, so neither needs any configuration. The DUSK_HOME environment variable overrides that search when you want a binary to use a different toolchain tree, such as a source checkout:

DUSK_HOME=/path/to/dusk-checkout dusk run hello.dusk

The archived Rust compiler

Dusk began as a compiler written in Rust. That compiler bootstrapped the language: it built the first Dusk-in-Dusk compiler, which then rebuilt itself to a byte identical result and took over. Once that handoff was complete the Rust source was removed from the main repository, and it lives on read only at dusk-rust, frozen at v1.3.0. That tag implements the language surface through 1.2.0, so it predates everything the roadmap records from 1.3 onward.

You do not need it to install, build, or use Dusk. Reach for it only to read the reference implementation the language grew out of, or to reproduce an old build. It needs Rust stable and Cargo, and it builds the ordinary way:

git clone https://github.com/choice404/dusk-rust
cd dusk-rust
cargo build --release   # target/release/dusk, the 1.3.0 compiler

There is no published package, so cargo install dusk-lang does not work and never will again. The current compiler is the Dusk one this page installs, and it is the only one that carries the 1.3 and later surface.

Where to go next

• Language tour: the core of the language in one pass.
• Paradigms: how per-file paradigm gating works.
• Memory: manual allocation, managed pointers, and the generational heap.
• Errors: errors are values you handle.
• Unicode and runes: runes and Unicode text, alongside the collected heap and TCP networking as newer additions.
• Examples: runnable programs, from hello world to a multi-module app.
• Editor support: the dusk language server, for Neovim, VS Code, and any LSP client, with diagnostics that are the compiler’s own.
• Reference: the precise rules.