The least C: zeno build --minimal
zeno build writes C that keeps every promise Zeno makes. An index is
checked, a sum is checked for overflow, an error says the line it
happened on, and the whole of Zeno's runtime is written in front of the
program in case it is needed. For a program of one line that is about
4,500 lines of C.
zeno build --minimal writes the other kind of C: the least that runs
the program, close to what a person would write by hand.
zeno build --minimal primes.zeno # writes primes.c, and builds ./primes from it
Nothing about zeno build without the option has changed. The C it
writes is byte for byte what it was.
What it looks like
examples/primes.zeno counts the primes below 10,000:
function is_prime(n) {
if n < 2 {
return false
}
var d = 2
while d * d <= n {
if n % d == 0 {
return false
}
d += 1
}
return true
}
zeno build writes this for it, after 4,500 lines of runtime:
static bool z_is_prime(int64_t z_n) {
if (z_n < 2) {
return false;
}
int64_t z_d = 2;
while (zeno_mul(z_d, z_d, 15, 11) <= z_n) {
if (zeno_mod(z_n, z_d, 16, 12) == 0) {
return false;
}
z_d = zeno_add(z_d, 1, 19, 9);
}
return true;
}
and zeno build --minimal writes this, in a file of 100 lines:
static bool z_is_prime(int64_t z_n) {
if (z_n < 2) {
return false;
}
int64_t z_d = 2;
while ((z_d * z_d) <= z_n) {
if (zeno_mod(z_n, z_d) == 0) {
return false;
}
z_d += 1;
}
return true;
}
zeno_mod is still there, eight lines above it in the same file. That
one is not a check. -7 % 3 is 2 in Zeno and -1 in C, and a correct
program may rely on it.
The last lines of the program,
print(f"primes below {limit}: {count_primes(limit)}")
print(f"one in every {average_gap(limit):.2f} numbers")
are
printf("primes below %lld: %lld\n", (long long)t1, (long long)z_count_primes(z_limit));
printf("one in every %.2f numbers\n", z_average_gap(z_limit));
What is left out
Six things are done to the C. Decisions chapter 30 has the reason for each.
- No check. The table below.
- No place in the source. No function is told the line and column it was called from.
- Only what the program uses. Every function, type, variable,
#defineand#includeof the runtime that the program does not reach is left out, and so is a function of the program that nothing calls. printisprintf, orputsfor words alone. (Not in a build for a board,--board: on a chipprintfis copied into the program, some 20 KB of it, soprintstays with the runtime there. Decision 52.4.)- Statements the short way.
x += 1, notx = (x + 1), and the top of the program is the body ofmain. -Os. The C compiler is asked for a small program.
What you give up
A mistake in the program does what it would do in C. The checked build stops and says what went wrong and where; this one does not.
zeno build |
zeno build --minimal |
|
|---|---|---|
xs[i] with i out of range |
IndexError |
reads or writes whatever memory is there |
ages["Eve"] with no such key |
KeyError |
reads an item that is not there |
overflow of + - *, of -n, abs(n), **, sum |
OverflowError |
no defined result |
n // 0, n % 0 |
ZeroDivisionError |
what the processor does: on a computer the system stops the program |
x / 0.0 |
ZeroDivisionError |
infinity, or NaN |
math.sqrt(-1.0), math.log(0.0), math.asin(2.0) |
ValueError |
NaN or infinity |
u8(300) |
ValueError |
300 goes on as it is |
n << 70, n << -1 |
ValueError |
no defined result |
xs.pop() or min(xs) of an empty list, a slice from past the end |
an error | no defined result |
int(x) of infinity or NaN |
ValueError |
the biggest int, the smallest, or 0 |
a variable that became none again after it was checked |
an error | used as if it held a value |
free(p) twice |
stops, and says so | no defined result |
"No defined result" means what it means in C: a wrong number, a crash far from the line that caused it, or nothing you notice until later. The C compiler is also allowed to build on the mistake not happening.
And an error that nothing catches no longer says where it was raised:
error: uncaught ValueError: cannot turn "ten" into an int
What you keep
- What the program prints. A correct program prints the same in a minimal build as in any other, to the last digit of a float.
- The errors a correct program can meet.
int("ten")still raisesValueError, a file that is not there still raisesFileError,raise,tryandexceptwork as they did, and running out of memory still stops the program and says so. These come from outside the program, and the program was written to deal with them. - What
%,//and**mean in Zeno, for numbers below zero too. - How memory is freed. The collector,
--ownedand--no-collectoreach work as they did.
So: write the program and test it with zeno run and zeno build,
which check everything. Build with --minimal when it is correct and
you want the C.
With the other options
--minimal goes with every build that writes C:
zeno build --minimal main.zeno # with the collector, if the program needs one
zeno build --minimal --owned main.zeno # one owner for each list and object, no collector
zeno build --minimal --no-collector main.zeno # the same, and memory from a pool of a fixed size
zeno build --minimal --firmware main.zeno # errors as values, no setjmp
zeno build --minimal --memory main.zeno # the program reports its memory as it ends
zeno build --minimal --fast main.zeno # -O3 in place of -Os
A program that never makes a list, an object or a piece of text has no
memory management in it under any of these. One that does has what its
kind of build needs: with the collector that is about 500 lines of C,
and with --owned or --no-collector 100 to 200. For the smallest C,
use one of those two (docs/memory-modes.md says what they ask of the
program).
--llvm, --web and --target do not take it. --release adds
nothing to it.
How much smaller
python3 tools/minimal.py --sizes builds every example both ways and
prints this table. Each cell is the checked build, then the minimal
one. "Code" is the bytes of machine code and constants (text, as the
size command counts it), the checked build compiled with -O2 and
the minimal one with -Os, which is how zeno build compiles each.
"Held" is the memory the program has from start to end (.data +
.bss). "Asked for" is the most bytes of lists, objects and text it
had at one time (what --memory reports).
| program | build | lines of C | code | held | asked for |
|---|---|---|---|---|---|
| hello | collector | 4,498 → 23 | 1,922 → 1,401 | 648 → 624 | 0 → 0 |
| blink | --no-collector |
4,128 → 95 | 1,874 → 1,765 | 728 → 728 | runs for ever |
| signal | --no-collector |
4,213 → 180 | 3,415 → 2,746 | 840 → 816 | 0 → 0 |
| primes | collector | 4,543 → 100 | 13,117 → 2,086 | 1,928 → 648 | 192 → 0 |
| primes | --no-collector |
4,176 → 100 | 7,745 → 2,086 | 34,832 → 648 | 46 → 0 |
| thermostat | collector | 4,619 → 832 | 15,591 → 8,742 | 2,016 → 1,912 | 1,360 → 240 |
| thermostat | --no-collector |
4,260 → 350 | 10,764 → 4,241 | 34,896 → 33,796 | 289 → 224 |
| ring | collector | 4,628 → 915 | 13,340 → 9,356 | 1,936 → 1,912 | 352 → 176 |
| ring | --owned |
4,415 → 519 | 9,074 → 5,891 | 2,936 → 2,920 | 170 → 147 |
| ring | --no-collector |
4,283 → 447 | 8,410 → 5,105 | 34,848 → 34,800 | 170 → 147 |
| scheduler | --no-collector |
4,372 → 575 | 11,319 → 7,720 | 34,840 → 34,840 | 527 → 527 |
| shapes | collector | 4,631 → 1,097 | 19,859 → 13,156 | 1,984 → 1,960 | 848 → 560 |
| words | collector | 4,700 → 1,155 | 16,902 → 13,305 | 2,000 → 2,008 | 2,432 → 2,400 |
| words | --no-collector |
4,378 → 789 | 13,865 → 9,781 | 34,952 → 34,960 | 529 → 529 |
(Linux, x86-64, gcc 13, 2026-11-19. The 34 KB a --no-collector build
holds is its pool, 32 KB unless the program is built with another
size: docs/pool.md.)
Three things to read from it:
- The C is where the difference is. 23 lines for hello, about 100 for a program of numbers, 350 to 1,150 for a program with lists, objects and text.
- The program shrinks less: for most examples a quarter to a third of
its code. The C compiler never put an unused function into the
program of any build, so what a minimal build saves there is the
checks themselves, their messages, and what
-Osfinds. The file on disk moves in steps of 4 KB and often does not move. - Memory changes where
printmade text, and where a program turns out not to need the pool at all (primes).
One number goes the other way. On Linux, a program whose print is
now printf has about 250 KB more of the C library in memory while it
runs, because printf is a large function that nothing ran before.
That is the library's memory and not the program's, and a board does
not page, but it is there in what the system reports.
How it is checked
python3 tools/minimal.py builds 363 programs (every example, the
corner programs in tools/targets/, every sample of the book) both
ways, for the collector, --owned, --no-collector and --firmware,
and holds the minimal build to the checked one: the same text printed,
the same end, the same message when an error stops it. A program that
one of the checks stops is left out, since it has no defined result
here. The C of each minimal build is also read with the C compiler's
warnings on, and anything left in it that the program does not use is
a failure.
The files
src/minimal.rs: cuts C into its items, finds what the program reaches, and puts the file together (assemble).src/emit_c.rs:Options { minimal };Emitter::at,slot_at,dividedandprint_directwrite the unchecked forms;printf_ofsays whatprintfcan show by itself;tidyshortens a statement.src/runtime.c: what a minimal build leaves out is between#ifndef ZENO_MINIMALand#endif /* ZENO_MINIMAL */. The note at the top of the file says how the marks are written.src/main.rs: the option, what it does not go with, and-Os.tools/minimal.py: the check, and--sizes.
Things to try
- Build
examples/hello.zenowith and without--minimaland count the lines of the twohello.cfiles. - Write
let xs = [1, 2, 3]andprint(xs[5]). Run it withzeno run, then build it both ways and run each. Do it twice. - Build
examples/ring/main.zenowith--minimal, then with--minimal --no-collector. Which functions are in the first file and not in the second? - Find
zeno_float_textin a minimal build of a program that prints a float. Why doesprint(0.1 + 0.2)not use%g? - Write a function that nothing calls and build with
--minimal. Is it in the C? Now call it. - Run
python3 tools/minimal.py --sizes --only examples/primesand read the row beside the table above.
This page is docs/minimal.md in the language repository.