Narra

Reference

Commands

Commands

Every narrac command and flag, with its exit codes, and the environment variables that narrac and the programs it builds read. narrac --help prints the same list of commands.

In a command line, PATH is a .nra file or a package folder (a folder with narra.toml). The root of a workspace stands for every member. A flag with a value takes it as the next word or as -name=value. The flags of build, run and test accept one or two dashes, so -release and --release are the same. Exit code 2 always means the command line is wrong.

Commands

Command What it does
narrac build build the executables of a package or file
narrac run build and run a program
narrac test run the test blocks
narrac check report errors without building
narrac explain explain a diagnostic code
narrac apply-fix print a file with the fix of an error applied
narrac fmt format .nra files
narrac query answer a question about a package
narrac emit print the C code of a debug build
narrac audit list the unsafe blocks and @trusted functions
narrac lsp run the language server
narrac targets list the systems -target accepts
narrac --version print the version
narrac --help print the usage

Running narrac with no argument prints the usage on the standard error and exits with code 2. The usage lists the commands above. Other commands exist for working on the compiler itself. They print internal dumps, have no stability promise and are not part of this page.

narrac build

narrac build [flags] PATH builds the executables of a package or a file. For a package, it builds every [[binary]], or the one that -bin names. For a file, the executable is named after the file.

Flag What it does
-release build with optimizations
-sanitize build with AddressSanitizer; not for Windows-X86_64 (E1601)
-target NAME build for another system; the names are the first column of narrac targets
-bin NAME build one binary of the package
-o PATH name the executable; needs one binary
-emit-c FILE also write the C code to FILE
-dependents on a workspace member, also build the members that depend on it
-dependencies on a workspace member, also build the members it depends on

Exit codes: 0 when every executable was built, 1 for errors in the program or a failed C compiler, 2 for a wrong command line.

narrac run

narrac run [flags] PATH [ARGS...] builds the program in a temporary folder and runs it. The words after PATH are the program's arguments. The program's standard output is written when it ends, then its standard error.

Flag What it does
-release build with optimizations
-sanitize build with AddressSanitizer
-bin NAME run this binary; without it, the package must have exactly one
-stdin FILE give the program FILE as its standard input; without it, the input is closed

Exit codes: the program's own exit code, 1 when the build failed, 2 for a wrong command line.

narrac test

narrac test [flags] PATH builds the test blocks of a file or of every module of a package, and runs each in a process of its own. A test that crashes or runs longer than NARRA_TEST_TIMEOUT seconds fails.

Flag What it does
-filter TEXT run the tests whose name contains TEXT
-time print how long each test took
-release build with optimizations
-sanitize build with AddressSanitizer
-stdin FILE give the tests FILE as their standard input
-dependents on a workspace member, also test the members that depend on it
-dependencies on a workspace member, also test the members it depends on

Exit codes: 0 when every test passed, 1 when a test failed, no test matches -filter, or the build failed, 2 for a wrong command line.

narrac check

narrac check [flags] PATH checks a file or package and reports its errors. It prints nothing when there are none. It builds no executable.

Flag What it does
--json print one JSON object per error on the standard output, with code, severity, message, file, range and fixes
--target NAME check as if building for that system
--all-targets check for every system; not with --target
-dependents on a workspace member, also check the members that depend on it
-dependencies on a workspace member, also check the members it depends on

The text form is one file:line:column: message line for each error on the standard error.

Exit codes: 0 when there are no errors, 1 for errors or an unreadable path, 2 for a wrong command line or an unknown target.

narrac explain

narrac explain CODE prints the message and explanation of a diagnostic code such as E0003.

Flag What it does
--list print every code; only with --json
--json print the list as JSON

narrac explain --list --json prints the whole table of codes. Errors shows the same table as a page.

Exit codes: 0 when it printed an answer, 1 for an unknown code, 2 for a wrong command line, which includes --list without --json.

narrac apply-fix

narrac apply-fix [flags] PATH prints the file of the first error that has a fix, with the first fix of that error applied. It does not change the file. For a package it prints the file that the fix changes.

Flag What it does
--diagnostic N pick the error by its place in narrac check --json, counted from 0
--fix M pick the fix of that error, counted from 0

Exit codes: 0 when it printed a file, 1 for no diagnostics, no such diagnostic, no such fix or an unreadable file, 2 for a wrong command line.

narrac fmt

narrac fmt [flags] [PATH...] rewrites .nra files in place in the standard layout. A folder means every .nra file inside it, at any depth. A workspace root means the files of every member. With no path it formats the current folder. The layout comes from the [fmt] table of narra.toml (see narra.toml).

Flag What it does
--check change nothing; print the path of each file that is not formatted
--stdin read one file from the standard input and write the result to the standard output; - is the same. No paths with it.

Exit codes: 0 when every file is formatted (or was rewritten), 1 for a file that --check found unformatted, a file with a syntax error, a missing file or an unreadable narra.toml, 2 for a wrong command line.

narrac query

narrac query [flags] QUESTION OPERAND answers a question about a package from the result of checking it. The questions are type-of FILE:LINE:COL, def NAME, refs NAME, callers FUNCTION, interface MODULE, recursion MODULE and hovers FILE. Chapter 18 explains each one.

Flag What it does
--package DIR the package to ask about; the current folder by default
--json print the answer as one JSON object

Exit codes: 0 when there is an answer, an empty one included, 1 for an unknown name, a place with no expression or a package with errors, 2 for a wrong command line.

narrac emit

narrac emit [flags] PATH prints the C code of a debug build on the standard output and builds nothing. For the C of an optimized build, use narrac build -release -emit-c FILE.

Flag What it does
--tests emit the test blocks, which a build leaves out, and no entry function
--bin NAME emit this binary

Exit codes: 0 when the C is complete, 1 for errors in the program or an unknown binary, 2 for a wrong command line, 3 when the C holds constructs the compiler cannot emit; each is named on the standard error as unsupported: ....

narrac audit

narrac audit [PATH] lists every unsafe block and every @trusted function of a package, one line each as file:line:column: text, sorted by place. It reads the parsed files and does not check the package. The package is the current folder by default.

Exit codes: 0 on success, 1 when the package cannot be loaded, 2 for a wrong command line.

narrac lsp

narrac lsp is a language server. It speaks the Language Server Protocol on the standard input and output. Chapter 18 shows how to set up an editor.

Flag What it does
--full check the whole package on every change, instead of the modules a change can affect
--trace write a line to the standard error for each check, saying what it checked

Exit codes: 0 after the editor asks it to shut down, 1 when the input ends before that, 2 for a wrong command line.

narrac targets

narrac targets prints the systems that -target and check --target accept, one per line, as a name and the triple of the C compiler. It takes no flags. Chapter 19 uses it. Exit code: 0.

narrac --version

narrac --version prints the version, dev for a build that is not a release. Exit code: 0.

narrac --help

narrac --help and narrac -h print the usage on the standard output. Exit code: 0. -h or --help after build, run or test prints the usage on the standard error and exits with code 2.

Environment variables

Variable Read by What it does
CC build, run, test the C compiler, one program name or path that is never split into words; cc when unset or empty
NARRA_HOST_TARGET every command that builds or checks names the host system as <os>-<arch>, such as Linux-X86_64, in place of the system narrac was built for
NARRA_CACHE commands that load packages with dependencies the folder where downloaded dependencies are kept; without it, $HOME/.cache/narra
HOME the same the base of the default cache folder
TMPDIR, TEMP, TMP run, test the folder for temporary builds, the first one that is set and not empty, else /tmp
PWD fmt, lsp where relative paths start when looking for narra.toml
NARRA_CHECK_LEAKS programs built by narrac, and narrac itself when set, a program that ends with memory still held reports it and exits with code 102; in narrac test, the test that leaked fails
NARRA_CHECK_COPIES programs built by narrac, and narrac itself when set, a program that ends after copies on write that no copy(...) explains reports them and exits with code 103
NARRA_UPDATE_GOLDEN tests when 1, Test.golden rewrites its expected file instead of comparing
NARRA_TEST_TIMEOUT tests seconds a test may run, from 1 to 99999; 10 when unset or invalid
NO_COLOR, FORCE_COLOR, TERM programs that call Terminal.useColor chapter 13 has the rules

NARRA_CHECK_LEAKS and NARRA_CHECK_COPIES are read when the program runs, so set them on the command that runs it, such as NARRA_CHECK_LEAKS=1 narrac run .. They apply to debug builds.