CLI reference
The marrow binary is the compiler front-end, the driver that invokes qbe and your system C toolchain, and the package manager. Run marrow help for the short version of this page.
marrow <COMMAND> [OPTIONS]marrow [OPTIONS] <input.mw> [output.ssa] (same as `marrow build`)Giving a .mw file with no command still works exactly as before: it is marrow build <input.mw>.
marrow help, marrow -h and marrow --help start with the Marrow banner and the version of the compiler. The banner is colored on a terminal and plain ASCII when the output is piped (--color and NO_COLOR are respected), and it never appears in error messages or JSON output.
Commands
Section titled “Commands”Building
Section titled “Building”| Command | Description |
|---|---|
build [input.mw] |
Compile a program. With no file, the project’s main is built. |
run [input.mw] [-- ARGS...] |
Build, then run the program. What follows -- is passed to it. |
check [input.mw] |
Type-check only. No code is generated, so neither qbe nor a C compiler is needed. |
Projects and packages
Section titled “Projects and packages”| Command | Description |
|---|---|
new <name> [--lib] |
Create a project in a new directory. |
init [--lib] |
Create a project in the current directory. |
add <name>[@version] [--git URL [--tag T | --rev R | --branch B]] [--path DIR] |
Add a dependency to marrow.toml and install it. |
remove <name> |
Remove a dependency. |
install |
Fetch the dependencies listed in marrow.toml. |
update |
Fetch newer versions of the dependencies and rewrite marrow.lock. |
tree |
Show the dependency tree. |
why <name> |
Show every chain of dependencies that leads to a package. |
outdated |
Show the dependencies that have a newer version. |
search [text] |
Search the package registry. |
vendor |
Copy the dependencies into vendor/, so that builds work offline. |
publish [--tag T] [--repo URL] |
Check the project and write its registry entry. |
test [filter] |
Run the tests. |
fmt [--check] [PATH...] |
Format source files. With --check, only report the files that would change. See Formatter, docs and editor support. |
doc [-o DIR] [PATH...] |
Write Markdown documentation from /// comments (default folder: build/doc). |
clean |
Remove the build/ folder. |
cache [list|path|clean] |
Show or empty the package cache. |
| Command | Description |
|---|---|
doctor |
Check that the tools needed to build programs (qbe, a C compiler) are installed. |
lsp |
Run the language server on standard input and output. |
completions <shell> |
Print a completion script for bash, zsh, fish or powershell. |
version |
Print the compiler version. |
help |
Print the usage text. |
Options
Section titled “Options”| Option | Description |
|---|---|
--check |
Type-check the program and stop (the same as the check command). |
--nostdlib |
Link without libc: the program uses Marrow’s own _start and system-call stub (see Cross-compilation). The whole standard library works in this mode. |
--target <arch>-<os> |
Compile for another target. arch is x86_64, aarch64 or riscv64; os is linux, macos or windows. Defaults to the host. |
-v, --verbose |
Print the qbe and C compiler commands that are run. |
--color <when> |
Colorize diagnostics: auto (default), always or never. |
--message-format <format> |
human (default) or json: with json, each diagnostic is one JSON line on standard error. |
-A, -W, -D <lint> |
Set a lint to allow, warn or deny. all stands for every lint. |
-V, --version |
Print Marrow version: v<version> and exit. |
-h, --help |
Print the usage text and exit. |
Running marrow with no input and no command prints the usage text to stderr and exits with code 2.
What a build does, in order
Section titled “What a build does, in order”- Existence check. If the input file doesn’t exist, prints an error and exits with code
2. - Parse and resolve imports. Lexes and parses the entry file, follows every
@import(...)(expanding{target}to the target’s platform name, e.g.linux_x86_64) and builds the program. See Modules & decorators. - Type checking. Reports errors with source excerpts, labels, notes and suggested fixes. Any error stops the build with exit code
1. Withcheckthe compiler stops successfully here. - Code generation. Walks the program and writes QBE IL to the
.ssafile. - QBE. Runs
qbe -t <target> <output>.ssa -o <output>.s.qbemust be on yourPATH. - Runtime assembly. The generated assembly is extended with Marrow’s runtime: the
__marrow_syscallstub, the context-switch routine used by tasks, and, with--nostdlibon Linux, the_startentry point. - Cross targets stop here. When
--targetnames something other than the host,marrowleaves the.sfile and prints where it is; assembling and linking is up to you (see Cross-compilation). - Assemble and link with
cc(gccon Windows):- Library (
@no_mainsomewhere in the program):cc -cto a.ofile, then prints how to link it. - Program: links an executable (
-nostdlib -staticfor freestanding Linux builds,-lws2_32on Windows).
- Library (
Builds are incremental: when nothing that the program depends on has changed since the last build, marrow says the program is up to date and skips qbe and the linker.
Build progress
Section titled “Build progress”In a terminal, a build shows a progress bar and a line for every package that has been compiled:
Compiled greet v1.2.0 (14 functions) Compiled std (1203 functions) Linking Finished app v0.1.0 in 1.4 s build/app (1 warning)The bar covers type checking, code generation, assembly and linking. When the output is not a terminal (a pipe, a CI log), the display is off and the usual Compilation successful! line is printed. MARROW_PROGRESS changes that:
| Value | Effect |
|---|---|
auto |
The bar and colors in a terminal, plain output otherwise. This is the default. |
plain |
The per-package lines and stages, with no bar and no colors. |
always |
The bar even when the output is not a terminal. |
never |
No progress display at all. |
Set MARROW_ASCII to draw the bar with # and - instead of block characters.
Projects, packages and tests
Section titled “Projects, packages and tests”marrow new and marrow init create a project with a marrow.toml. Dependencies, the lock file, the registry, vendoring and publishing are described in Projects and packages. marrow test and @test are described in Testing.
Shell completions
Section titled “Shell completions”marrow completions bash > ~/.local/share/bash-completion/completions/marrowmarrow completions zsh > ~/.zfunc/_marrowmarrow completions fish > ~/.config/fish/completions/marrow.fishmarrow completions powershell | Out-String | Invoke-ExpressionEnvironment
Section titled “Environment”| Variable | Effect |
|---|---|
MARROW_QBE |
Path of the qbe binary (default: next to marrow, then PATH). |
MARROW_CC |
C compiler used to assemble and link (default: cc, gcc or clang). |
MARROW_HOME |
Where packages are cached (default: ~/.marrow). |
MARROW_PROGRESS |
Build progress display: auto, plain, always or never. |
MARROW_ASCII |
Draw the progress bar with ASCII characters. |
MARROW_REGISTRY |
URL of the package registry repository. |
MARROW_REGISTRY_BRANCH |
Branch of the registry (default: registry). |
MARROW_FETCH |
How sources are downloaded: auto (archives over HTTPS, then git), http or git. |
MARROW_TOKEN |
GitHub token used to download private repositories. |
HTTPS_PROXY, NO_PROXY |
Proxy used for downloads. SSL_CERT_FILE names extra trusted certificates. |
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
Success (or version / help). |
1 |
A compile-time error (parse, import or type error, code generation), a qbe failure, a linker failure or a failed test. |
2 |
A usage error: missing argument, unknown command, option or target, input file not found, or failure to write the output. |
Requirements
Section titled “Requirements”checkneeds nothing butmarrowitself.- A full build needs the
qbebinary and a C compiler (ccon Linux/macOS,gccon Windows) onPATHfor the final assemble + link step.marrow doctortells you what is missing. Without a supported compiler you still get the.ssaand.sfiles. - Cross builds need
qbeplus whatever assembler and linker targets that platform (for exampleclangandld.lld).
Examples
Section titled “Examples”# Check a program without building anythingmarrow check app.mw
# A program with no libc at all (Linux)marrow --nostdlib app.mw
# Assembly for 64-bit ARM Linuxmarrow --nostdlib --target aarch64-linux app.mwclang --target=aarch64-linux-gnu -nostdlib -static -fuse-ld=lld app.s -o app
# A library: std/std.mw is decorated @no_main, so this produces an object filemarrow std/std.mw# -> std/std.o
# A project with a dependencymarrow new app && cd appmarrow add jsonmarrow runThis is how the project’s CI works: every program in tests/run/ is built with --nostdlib, run, and compared with its expected output, on Linux, macOS and Windows runners and (for aarch64 and riscv64) under qemu-user.