Releasing Zeno: one zeno for each kind of machine
Every page so far ran Zeno with cargo run --, which builds the
compiler from its source first. That is right for somebody working on
Zeno, and wrong for somebody who only wants to use it: they should not
need Rust at all. A release is the answer: a zeno that is already
built, for the machine they have, to download and run.
This page is about how a release is made. The decisions are chapter 12
of decisions.md.
What a release is
A release is a version number, the source as it was at that moment, and one file to download for each kind of machine:
| Machine | File |
|---|---|
| Linux, x86-64: most PCs and servers | zeno-0.1.0-linux-x86_64.tar.gz |
| Linux, ARM64: a Raspberry Pi 3, 4 or 5 with a 64-bit system, ARM servers | zeno-0.1.0-linux-arm64.tar.gz |
| Linux, 32-bit ARMv7: a Raspberry Pi 2 or later with a 32-bit system | zeno-0.1.0-linux-armv7.tar.gz |
| Linux, 32-bit ARMv6: a Raspberry Pi 1 or Zero | zeno-0.1.0-linux-armv6.tar.gz |
| Linux, 32-bit x86 | zeno-0.1.0-linux-x86.tar.gz |
| macOS, Apple silicon | zeno-0.1.0-macos-arm64.tar.gz |
| macOS, Intel | zeno-0.1.0-macos-x86_64.tar.gz |
| Windows, x86-64 | zeno-0.1.0-windows-x86_64.zip |
| Windows, 32-bit x86 | zeno-0.1.0-windows-x86.zip |
| Windows, ARM64 | zeno-0.1.0-windows-arm64.zip |
Each file unpacks to a folder with zeno in it (zeno.exe on
Windows), this README, the docs, the examples and the editors
folder. zeno is one file that needs nothing else installed: put it
anywhere on the PATH and it works.
From 0.2.0 on the folder also has zeno.wasm, which is
Zeno built for a browser. zeno build --web writes it into the page
it makes (web.md), and looks for it beside zeno, so the
two are moved together. Nothing else needs it.
Beside them is SHA256SUMS.txt, with one line for each file. It is
how to know that a download arrived whole:
sha256sum --check --ignore-missing SHA256SUMS.txt
Making one
Two lines make a release:
git tag v0.1.0
git push origin v0.1.0
The tag is the letter v and the version in Cargo.toml. Pushing it
starts .github/workflows/release.yml
on GitHub's machines, which does the rest:
- It checks that the tag and
Cargo.tomlname the same version, so azenothat says0.1.0cannot be released asv0.2.0. - On Linux it runs the whole test suite (
cargo test). If a test fails, nothing is released. On macOS and Windows it runs the suite too, to see what it says there, and puts the count on the summary page of the run. - It builds
zenoten times, once for each row of the table. - It runs
tools/release-check.shon each build (see below). - It packs each build with the docs and the examples.
- When all ten are done, it makes the release from
docs/releases/0.1.0.md, which is the text people read on the release page, and puts the ten files andSHA256SUMS.txton it.
If any of the ten fails, there is no release: a release with a hole in the table is worse than one a day later.
The same workflow can be started by hand, from the Actions page of the
repository ("Run workflow"). Then it does steps 2 to 5 and releases
nothing. That is the way to find out whether main could be released,
without releasing it.
There is a box to tick there, "publish". With it the workflow does
step 6 as well, and makes the tag itself, named after the version in
Cargo.toml. That is a release from a web page, with no git at
hand: tick the box, press the button, and wait about six minutes.
Where each one is built
GitHub lends three kinds of machine: Linux on x86-64, macOS on Apple silicon, and Windows on x86-64. Ten builds come out of those three because Rust can build for a processor it is not running on:
- The Linux machine builds all five Linux rows. They are linked against
musl, a small C library that is put into the program itself. A
Linux program usually borrows the C library of the system it runs on,
and then it only runs on systems with one at least as new. With musl
the one
zenoruns on every Linux, old or new, whatever is installed. - The macOS machine builds both macOS rows.
- The Windows machine builds all three Windows rows. Those carry their
C library too, so
zeno.exeasks for no.dllto be installed.
How each is linked is in .cargo/config.toml.
Building Zeno for the machine you are on uses none of it.
Checking a build before it goes out
A build that has never been run is a guess. So each build is run before
it is packed, by tools/release-check.sh:
tools/release-check.sh target/release/zeno
zeno 0.1.0
27 examples run, and print the same through both engines
5 tests: 5 passed, 0 failed.
every example is laid out as `zeno format` lays it out
`zeno new` makes a program that runs and whose tests pass
ok
A build for another processor cannot run on the machine that built it. For the ARM builds for Linux the script is given an emulator, a program that acts as the other processor:
tools/release-check.sh target/aarch64-unknown-linux-musl/release/zeno qemu-aarch64
The Intel build for macOS runs on the Apple silicon machine, because macOS translates it. The 32-bit builds run as they are, because a 64-bit x86 processor runs 32-bit programs.
One build is not run: Windows for ARM64. GitHub's Windows machine cannot run it and there is no emulator there to give it to. It is built by the same compiler from the same source as the other two Windows builds, which are run, and the release page says that it was not.
What a released zeno needs
For zeno run, check, test, format, new and lsp: nothing.
zeno build writes C and hands it to the machine's C compiler, so it
needs one: cc, or whatever CC names. zeno build --llvm needs
clang. zeno fetch needs git. The release does not bring them,
because they are different on every machine and most machines that
build programs have them.
On Windows the C compiler is MinGW's gcc, which zeno build finds by itself (15.5),
and zeno build --llvm uses the clang that comes with Visual Studio.
The program is hello.exe, run with .\hello.
Line ends
Windows ends a line with two characters and everything else with one.
Zeno reads a program with either. zeno format writes one, on every
machine, so a file has one layout wherever it was formatted. The
repository says the same thing to git in .gitattributes, so the
examples are the same bytes on Windows as on Linux.
What the first release found
Until this release Zeno had only ever run on one kind of machine: Linux on x86-64. Running the tests somewhere else for the first time found three things, all about compiled programs.
A last digit. examples/sensor.zeno turns Celsius into Fahrenheit
with c * 1.8 + 32. For 23.5 zeno run prints 74.30000000000001,
and so did the compiled program, on x86-64. On a Mac with Apple
silicon the compiled program printed 74.3.
Neither is wrong as arithmetic. A float cannot hold 42.3 exactly, so
the multiplication is rounded, and then the addition is rounded again.
ARM64 has one instruction that multiplies and adds and rounds once,
at the end. It is a little faster and a little closer to the true
answer, and a C compiler is allowed to use it without being asked.
But then the same program gives two answers, and which one depends on
the processor. Zeno's promise is that a compiled program prints what
zeno run prints, so the C that Zeno writes now begins by telling the
compiler to keep the two steps apart (decision 12.5). The same lines
mend 32-bit x86, where gcc had the same effect for a different reason.
A line end. On Windows a compiled program printed "\r\n" where
zeno run printed "\n", because that is what C does there unless
it is told not to. It is told not to now (decision 12.6).
Both were found by a test that had always passed, and both were mended before the release. A test only tests the machines it is run on.
What Windows found
Of the tests of Zeno itself, 337 of 454 passed the first time they were run on Windows. Now all of them do. What was in the way, in the order it was found (decisions 12.8 and 12.9):
Waiting. zeno build --llvm did not work at all. The runtime
waited with nanosleep and read the clock with clock_gettime, and
Microsoft's C library has neither. On Windows it now uses Sleep and
the performance counter:
#ifdef _WIN32
static void zeno_board_sleep(double seconds) {
fflush(stdout);
Sleep((unsigned long)(seconds * 1000.0 + 0.5));
}
#else
... nanosleep ...
#endif
Behind that were three smaller things of the same kind: setjmp
takes a second argument there, the linker does not know -lm, and a
program is called hello.exe.
A path. Windows writes drivers\uart.zeno and takes
drivers/uart.zeno too. Zeno now writes every path it makes with
/, so a message is the same on every system, and so that the file
an editor has open is the file an import finds.
A word in Tamil. program.arguments() in a compiled program
gave ????? for தமிழ், because Windows hands main its words in
an older encoding. The runtime now asks for them the way Windows
keeps them.
Line ends, again. zeno fetch got a package with \r\n in
every file, because that is how git is set on Windows. It is told to
leave them.
A trial on one machine
Each of those was tried on a real Windows machine before it was kept,
with .github/workflows/trial.yml. On the Actions page choose
"trial", press "Run workflow" and pick the machine. It builds Zeno,
runs tools/release-check.sh, compiles three examples both ways and
runs every test, and writes what it found at the top of the run's
page. It releases nothing, and costs a quarter of what a run of the
release workflow does, or less.
Things to try
- Build a release
zenofor your own machine withcargo build --releaseand runtools/release-check.sh target/release/zeno. - Change the
printinexamples/hello.zenoand run the check again. Which line stops it, and what does it say? - Run
zeno runon a file saved with Windows line ends (most editors can save one). Then runzeno format --checkon it, andzeno format, and look at the file again. - Add the Rust target for another processor (
rustup target add aarch64-unknown-linux-musl), build for it withcargo build --release --target aarch64-unknown-linux-musl, and askfilewhat the result is. What happens if you try to run it? - Read
.github/workflows/release.ymland find the line that stops a release when the tag andCargo.tomldisagree. print(23.5 * 1.8 + 32)prints74.30000000000001. Work out by hand what the answer "should" be, and then explain to yourself why Zeno prints the longer number on purpose. Build the program withzeno buildand look in the.cfile for the lines that begin#pragma.
This page is docs/release.md in the language repository.