31 Building and testing — packages, configuration, tests, cross-checks

31.1 The manifest and the project#

Put pkg.low at the project root and the entry point in src/main.low.

package name "greeter" .
package version "0.1.0" .
package license "MIT" .

The manifest is a few flat declarations. The keys are a closed set and version is checked against semantic versioning. This file exists so that tools and people can know a project’s identity from it alone without reading all the source, so here too what is written is checked. If it cannot be trusted when read, it may as well not exist.

$ lowentc run
hello from a package
main() = 0
$ lowentc build
built …/out/greeter
$ ./out/greeter main
hello from a package

lowentc run finds the manifest and runs the entry point on the VM, and lowentc build emits C and builds an executable in out/. Builds are cached by the content hash of the emitted C, so unchanged code is not compiled again. The manifest is found by walking upwards from the first file’s folder.

 pkg.low ──▶ entry src/main.low
                  │
                  ▼
             the same checks as --check ──▶ rejected: stop here (neither run nor built)
                  │
        ┌─────────┴──────────┐
        ▼                    ▼
   lowentc run          lowentc build
   run on the VM        emit C ──▶ same hash: cache ──▶ out/greeter
                               └─▶ first time: cc ───▶ out/greeter

Both commands pass the same checks as --check before running or building. A program the language rejects neither runs nor becomes an executable. run has done so since 2026-09-16, build since 2026-09-26 — before that, build skipped the checks and built even a program with a mistake like return true . (found by measuring while this chapter was revised).

31.2 Dependencies are pinned by hash#

lowentc add <name> <place> writes a dependency into the manifest with a hash pin. --lock-write records in a lock file what is being built against now, and --lock <file> refuses to build if the bytes differ from that hash. Even with the same version number, changed bytes are a different dependency.

Checking authenticity is a separate layer. lowentc key new, sign and verify make and check ed25519 detached signatures. verify splits its answer into four layers — integrity (do hash and pin match), authenticity (signed with a trusted key), transport and access — because green in one layer does not mean green in another. The only environment variable read to find settings is HOME, and the precedence of settings (command line > project > user > global) is written in the help. This is to reduce places where behaviour is changed secretly outside the source. A few other switches whose names start with LOW exist, all off by default and meant for testing and migration — the fault injector LOW_HOST_FAULT (chapter 28), the rollback door LOWENT_ALLOW_GLUED_FIELD that briefly re-admits the removed glued-dot field access, and the step limit LOWENT_ORACLE_BUDGET of the oracle tools. There is no everyday reason to set them, and setting one shows on the command line.

This is how verify reports its four layers separately (measured on an unsigned file).

 [3 integrity]     BLAKE3 a19e7c93…      are these bytes the pinned ones
 [2 authenticity]  unsigned — LOCAL       who published it --- a trusted key's signature
 [1 transport]     TLS (curl's job)       who the server is --- not what the bytes are
 [4 access]        tokens in tool config  may you get in --- separate from integrity

Each layer is looked at on its own even when another is green. A successful TLS connection means the server is the right one, not that the bytes received are.

31.3 A different program per build — build option and config#

module knobs .
rem run: tick_rate
rem run: cpus

build option smp bool default true .
build option hz choice 100 250 1000 default 250 .
build option maxcpu int default 64 .

fn tick_rate output u64 .
do
  if config smp . do
    return config hz .
  end
  return 100 .
end

fn cpus output u64 .
do
  return config maxcpu .
end

$ lowentc --run tick_rate knobs.low
tick_rate() = 250
$ lowentc --run cpus knobs.low
cpus() = 64

build option <name> <kind> … declares a knob. There are three kinds: bool, int and choice. config <name> reads its value as a translation-time constant. Without a configuration file, the declaration’s default is used.

The same source is built with a different configuration. A configuration file is a set of name value lines.

smp false
maxcpu 8

module knobs_small .
rem flags: --config small.config
rem run: tick_rate
rem run: cpus

build option smp bool default true .
build option hz choice 100 250 1000 default 250 .
build option maxcpu int default 64 .

fn tick_rate output u64 .
do
  if config smp . do
    return config hz .
  end
  return 100 .
end

fn cpus output u64 .
do
  return config maxcpu .
end

$ lowentc --config small.config --run tick_rate knobs_small.low
tick_rate() = 100
$ lowentc --config small.config --run cpus knobs_small.low
cpus() = 8

With smp switched off, tick_rate gives 100 and cpus gives 8. Once the value is fixed, switched-off branches do not remain in the output. The cost is zero.

 build option smp bool default true .       ← the source declares the knob
 small.config:  smp false                   ← the config file gives a value (default if absent)

 if config smp . do return config hz . end  ← the branch when smp is on
 return 100 .                               ← the branch when it is off

 translation  both branches are parsed and type-checked
 output       only the chosen branch stays (the off branch costs 0)

There is a decisive difference from C’s #ifdef. Switched-off branches are still parsed and type-checked. In C, code for combinations nobody switches on rots unread, and in kernel-scale projects “that option combination does not even build” happens. Here what folds away is code emission, not checking.

A knob declared but read by no code is rejected.

module unused_opt .
rem expect: E-OPT-UNUSED

build option trace bool default false .

fn answer output u64 .
do
  return 42 .
end

$ lowentc --check unused.low
unused.low:4:0 E-OPT-UNUSED: this build option is declared and NO code reads it (`config <name>`). It shows up in the configuration, the user turns it off — and nothing happens. A knob that does nothing is worse than no knob: it is a decision that LOOKS like it was made

Such a knob appears in the configuration, a user switches it off, and nothing happens. It looks like a decision but is not one. A configuration file giving a value not among the choices (E-CONFIG-TYPE) or naming a knob that does not exist (E-CONFIG-UNDEF) is rejected too.

31.4 Tests#

expect inside a test <name> do … end block is an assertion. --test runs every test.

module tests_clause .
rem test

fn clamp8 input v u64 . output u8 .
do
  return narrow_sat u8 v .
end

test clamp_keeps_small
do
  expect eq (clamp8 7) 7 .
end

test clamp_saturates
do
  expect eq (clamp8 1000) 255 .
end

$ lowentc --test tests_clause.low
  [PASS] clamp_keeps_small
  [PASS] clamp_saturates
== tests: 2 run, 2 passed, 0 FAILED ==

When a test fails, it looks like this.

module failing .
rem test-fail

fn clamp8 input v u64 . output u8 .
do
  return narrow_wrap u8 v .
end

test clamp_saturates
do
  expect eq (clamp8 1000) 255 .
end

$ lowentc --test failing.low
  [FAIL] clamp_saturates
         E-TEST-FAIL: an `expect` in this test is FALSE — the test failed (this is not a contract violation: it is the test telling you the code is wrong)
== tests: 1 run, 0 passed, 1 FAILED ==

E-TEST-FAIL is a different diagnostic from a contract violation. A contract violation is code breaking its own promise; a test failure is a test saying the code is wrong. What to fix differs. Here narrow_wrap must become narrow_sat. And the processor does not optimise expect away. A vanished test is a test that did not run.

Concurrent code uses test <name> schedule explore_interleavings . do … end to run every possible ordering of flows and see whether the answers agree (chapter 26). When there are many cases, limit <number> sets a ceiling.

An op head also has clauses for documentation and tests.

module clauses .
rem run: first_two [65,66]
rem test

enum parse_error do
  too_short .
end

fn first_two
  rem lowdoc is a description for people; tools extract it as documentation
  lowdoc "Add the first two bytes; refuses input shorter than two." .
  input data slice u8 .
  output result u64 parse_error .
  errors too_short lt (len data) 2 .
  rem tests names the ops that test this op; the tool checks that those names exist
  tests first_two_ok first_two_short .
do
  guard ge (len data) 2 . else return error too_short .
  return ok (add (widen u64 (index data 0)) (widen u64 (index data 1))) .
end

fn first_two_ok output bool . do
  let r result u64 parse_error be first_two "AB" .
  return is_ok r .
end

fn first_two_short output bool . do
  let r result u64 parse_error be first_two "A" .
  return is_error r .
end

rem the test block calls the testing ops; lowentc --test runs it
test first_two_cases do
  expect first_two_ok .
  expect first_two_short .
end

$ lowentc --run first_two clauses.low [65,66]
first_two([65,66]) = ok 131
  arg0 (written) = [65,66]
$ lowentc --test clauses.low
  [PASS] first_two_cases
== tests: 1 run, 1 passed, 0 FAILED ==

• lowdoc "…" . is a description for people. Unlike a comment (rem), it stays attached to the op as documentation that tools extract. For a long one, write several lines with lowdoc text DOC … DOC . (chapter 3).
• tests first_two_ok first_two_short . lists the names of the ops that test this op, not the names of test blocks. The tool checks that those names exist and refuses with E-CONTRACT-UNDEF if they do not. If a test is renamed or removed, the head tells you.
• errors too_short lt (len data) 2 . is a failure with a condition. The two testing ops check the success arm and the failure arm, and the test block ties them together with expect.

31.5 How the compiler is verified#

The proofs (Part X) are about a model. Whether the actual compiler follows that model must be confirmed separately. There is one principle — make the same thing in two ways, and treat a different answer as a defect.

Such checks show that defects exist but cannot show that they do not. Two implementations giving the same answer are not thereby both right. Absence is the job of proofs. What you can run yourself in the public repository is make check in impl/. It covers unit tests, checking the whole standard library, VM/native cross-checks over many ops, and the diagnostic codes of programs that must be rejected, all at once. This book’s verification script applies the same cross-check to every example — and while this book was written, that cross-check exposed several discrepancies in the compiler.

31.6 Asking where it is slow#

Native emission lowers ops by two paths. Ops whose types are settled lower naturally to C integers and arrays; the rest stay on a slow path running on tagged values. --why-slow names the ops left on the slow path and why.

$ lowentc --why-slow bounds.low
why-slow: 0 / 1 op(s) still on the tagged path

A model whose performance is not visible in signatures becomes knowledge outside the source. So the tool says it. --no-fast is a contrast switch lowering every op by the slow path, used to see whether both paths give the same answer.

31.7 Common mistakes#

module mistake_configtypo .
rem flags: --config typo.config
rem expect: E-CONFIG-UNDEF

rem ✘ the config file spells `maxcpu` as `maxcpus`

build option smp bool default true .
build option hz choice 100 250 1000 default 250 .
build option maxcpu int default 64 .

fn tick_rate output u64 .
do
  if config smp . do
    return config hz .
  end
  return 100 .
end

fn cpus output u64 .
do
  return config maxcpu .
end

$ lowentc --check --config typo.config mistake_configtypo.low
0:0 E-CONFIG-UNDEF: the config selects an option that is not declared. A setting nobody reads changes nothing — and it LOOKS like it does

module mistake_configvalue .
rem flags: --config badvalue.config
rem expect: E-CONFIG-TYPE

rem ✘ the config file gives `hz` the value 300, which is not one of its choices

build option smp bool default true .
build option hz choice 100 250 1000 default 250 .
build option maxcpu int default 64 .

fn tick_rate output u64 .
do
  if config smp . do
    return config hz .
  end
  return 100 .
end

fn cpus output u64 .
do
  return config maxcpu .
end

$ lowentc --check --config badvalue.config mistake_configvalue.low
8:0 E-CONFIG-TYPE: the config picks a value this `choice` option does not offer

module runcap .
rem run: say 5
rem run: say 0 5

rem `--run` FILLS capability positions when you leave them out (2026-09-20). The old placeholder `0` still works too
proc say input out cap io . input n u64 . output u64 . effects io .
  requires le n 100 .
do
  return write_out out 1 "hi\n" .
end

$ lowentc --run say runcap.low 5
hi
say(5) = 3
$ lowentc --run say runcap.low 0 5
hi
say(0, 5) = 3

module dead_branch .
rem flags: --config smp_off.config
rem expect: E-TYPE-RETURN

build option smp bool default true .

fn rate output u64 .
do
  if config smp . do
    rem this branch is switched off in this configuration --- it is checked all the same
    return true .
  end
  return 0 .
end

$ lowentc --check --config smp_off.config dead_branch.low
dead_branch.low:11:0 E-TYPE-RETURN: the returned value does not match the op's `output` — expected `u64`, found `bool`

31.8 This chapter’s syntax at a glance#