Tools

#The toolchain

burn is one native executable written in Burn, with the compiler and bvm, the Burn virtual machine, inside. Started as burn, burni, burnc or burn-lsp (links to it), it is the command line in that role; started as bvm (another link), it is the virtual machine on its own. burnfmt runs the formatter written in Burn.

#burni: the interpreter

burni type-checks a program, compiles it to a bvm module in memory and runs it. There is no build step: a program starts in a few milliseconds, and code that runs often is compiled to machine code while it runs (the JIT). burni also runs .bvm and .bvmc files.

burni app.bn                 # run a program
burni app.bn one two         # arguments are available through args()
burni                        # start the REPL
burni -e 'print(6 * 7)'      # run a snippet
burni --version

The REPL keeps variables, functions and types between inputs, prints the value of expression statements and understands :help, :reset, :source and :quit.

#burnc: the compiler

burnc compiles a program to a standalone native executable, to bvm bytecode, which runs anywhere bvm runs, or to JavaScript for Node.js.

burnc app.bn                          # ./app
burnc app.bn -o bin/app               # choose the output path
burnc app.bn --emit-asm app.s         # also write the generated assembly
burnc app.bn --target bvm             # app.bvmc, bytecode for bvm
burnc app.bn --target bar             # app.bar, the program and its bytecode libraries in one archive
burnc app.bn --target js              # app.js, a program for Node.js
burnc app.bar -o app                  # a native executable that runs a bytecode archive
burnc app.bn --no-strip               # keep symbols for debuggers and profilers
burnc app.bn --no-std                 # without the standard library
burnc --check a.bn b.bn               # type-check only

Native executables are built for Linux and macOS on x86-64 and on arm64, including Macs with Apple silicon (M1 and later). They need a C toolchain (cc, or the program named by BURN_CC; on macOS the Xcode command line tools), which assembles and links them with the runtime in share/burn/lib. See cross-compiling to build for another platform. Run bytecode with burn app.bvmc or bvm app.bvmc; an archive also runs on its own (./app.bar) when bvm is on PATH, and a JavaScript build with node app.js. See how the compiler works.

#burnfmt: the formatter

burnfmt formats Burn source code. It is written in Burn (lib/tools/fmt.bn) and runs on bvm. See burnfmt.

burnfmt file.bn              # print the formatted file
burnfmt -w src/*.bn          # rewrite files in place
burnfmt --check src/*.bn     # list unformatted files, exit code 1 if any
cat file.bn | burnfmt        # format standard input

#burn-lsp: the language server

burn-lsp is the language server over stdio, the same as burn lsp. Point any LSP client at it; see editor support.

#bvm: the Burn virtual machine

bvm runs, assembles, disassembles and verifies bvm modules. Burn programs run on it, and other languages can target it too. See the Burn Virtual Machine.

bvm app.bvmc                 # run bytecode (or a .bvm assembly file)
bvm asm app.bvm -o app.bvmc  # assemble
bvm dis app.bvmc             # disassemble
bvm check app.bvm            # verify without running
bvm link a.bvm b.bvmc -o c.bvmc   # link modules
bvm pack app.bvmc lib.bvmc -o app.bar   # bundle an archive; ./app.bar runs it
bvm list app.bar             # show an archive's contents
bvm runtime                  # list the runtime functions

#burn: everything in one

burn includes all of the above as subcommands: burn run, burn build, burn check, burn test, burn fmt, burn fix, burn doc, burn repl, burn eval, burn lsp and burn dump. See the command line reference.

#Which one should I use?