Tools
Command line
This page lists every subcommand of burn. The shorter toolchain commands map onto them:
burni is burn run/burn repl/burn eval, burnc is burn build/burn check, burn-lsp is burn lsp and
burnfmt behaves like burn fmt. See the toolchain.
| Command | Description |
|---|---|
burn <file.bn> [args...] |
type-check and run on bvm |
burn <file.bvm|file.bvmc|file.bar> [args...] |
run a bvm module or archive |
burn run <file.bn> [args...] |
the same |
burn init <name> [--lib] [--target native|js|bvm|bar] [--workspace] |
create a project (details) |
burn run, burn build, burn check |
without a file, work on the project in the current folder |
burn run --native <file.bn> [args...] |
compile to machine code and run it |
burn run --bin <name>, burn run --example <name> |
run a program of the project's src/bin/ or examples/ |
burn build <file.bn> |
build a native executable next to the source file |
burn build <file.bn> -o <path> |
choose the output path |
burn build <file.bn> --target bar |
write a runnable .bar archive with the program and its bytecode libraries |
burn build <file.bn> --target js |
write a .js file that runs with Node.js |
burn build <file.bn> --target bvm |
write a .bvmc bytecode module (imported bytecode libraries are linked in) |
burn build <file.bar|file.bvmc> |
build a native executable that runs the bytecode |
burn build <file.bn> --emit-asm out.s |
also keep the generated assembly (bvm assembly with --target bvm) |
burn build <file.bn> --no-strip |
keep symbols in the executable |
burn build <file.bn> --no-std |
build without the standard library, like std = false in burn.toml |
burn test [filter...] |
run the tests in the project's tests/ folder |
burn check <files...> |
report errors and warnings without running |
burn fix [--dry-run] <files...> |
apply the compiler's certain fixes, then report what is left (details) |
burn doc [files...] [-o dir] |
generate an HTML reference from Burndoc comments (details) |
burn fmt <files...> |
print formatted code; -w rewrites files, --check fails when files are not formatted |
burn repl |
interactive session |
burn eval '<code>' |
run a snippet |
burn lsp |
language server over stdio (details) |
burn sources |
write the sources of the standard library and the built-ins for reading and print the folder |
burn dump --bytecode <file.bn> |
print the bvm assembly of a program, linked with its bytecode libraries |
burn dump --asm <file.bn>, burn dump --js <file.bn> |
print the assembly (x86-64 or arm64, for BURN_PLATFORM) or the JavaScript of a program |
burn dump --tokens <files...> |
print the tokens and lexer errors of each file, one token per line with byte offsets |
burn dump --ast <files...> |
print the syntax tree and parse errors of each file, one node per line with byte spans |
burn dump --diagnostics <files...> |
print the lexer and parser errors of each file as burn check shows them, without colours |
burn dump --toml <files...> |
print a TOML file (such as burn.toml or burn.lock) as the compiler reads it, or its first error |
burn dump --project <paths...> |
print the project and workspace found from each path, and where each of its packages resolves |
burn dump --modules <files...> |
print every module a program loads, its imports and the import errors |
burn dump --decls <files...> |
print every type, function and global the checker declares for a program, before it checks any body |
burn dump --checked <files...> |
print the checked program of each file (types, functions, globals, strings and source locations), or the errors the checker reports |
burn dump --owned <files...> |
like --checked, after the ownership pass has added the reference counting (Retain, Release and the temporaries they need) |
burn dump --index <files...> |
print what the language server knows about each file: the hover text and the definition of every name, the locals with their scopes, and the type of every expression |
burn dump --bvm <files...> |
print the bvm module of each file in bvm assembly, as burn <file.bvm> runs it, or the errors |
burn version, burn help |
information |
The older flags still work: -r, -e, -exe <file> and -d.
Environment variables
| Variable | Effect |
|---|---|
BURN_CC / CC |
linker driver used by burn build (default cc) |
BURN_PLATFORM |
build native executables for another platform: linux-x86_64, macos-x86_64, linux-aarch64 or macos-aarch64 (cross-compiling) |
BURN_RUNTIME_DIR |
the folder with the runtime native executables link against (default share/burn/lib) |
NO_COLOR |
disable colored diagnostics |
BURN_JIT |
0 turns bvm's JIT off, so everything is interpreted |
BURN_JIT_THRESHOLD |
how many calls or loop turns make a function hot enough for the JIT (default 1000) |
BURN_SYMBOLS |
1 names every function in the assembly of native builds, for debuggers and profilers |
BURN_HOME |
where packages are found (default ~/.burn, packages in packages/) |
BURN_GC_THRESHOLD |
bytes allocated between two searches for unreachable cycles (default 32 MB) |
BURN_GC_STATS |
print a line after every cycle search |
BURN_RC_CHECK |
debugging aid: freed objects are kept and poisoned, and any later use of one stops the program with an internal error |
BURN_MAX_HEAP_MB |
stop a program with an out of memory error when it keeps more data alive than this (default: 3/4 of the computer's memory, 0 turns the limit off) |
BURN_LSP_MEMORY_MB |
the most memory burn lsp may use on Linux; past it the server stops instead of slowing the computer down (default 4096, 0 turns the limit off) |
Exit codes
A program exits with the code passed to exit, 1 after a runtime error, and 0 otherwise. burn check,
burn build and burn run exit with 1 when the program has compile errors.
Toolchain commands
| Command | Description |
|---|---|
burni [file.bn [args...]] |
run a program, or start the REPL without arguments |
burni -e '<code>' |
run a snippet |
burnc <file.bn> [options] |
the same options as burn build |
burnc --check <files...> |
the same as burn check |
burnfmt [-w] [--check] [files...] |
the formatter written in Burn |
burn-lsp |
the language server |