README.md

zb

zb is an experiment in hermetic, reproducible build systems. It has not stabilized and should not be used for production purposes.

zb is based on the ideas in The purely functional software deployment model by Eelco Dolstra and Build systems à la carte, as well as the author's experience in working with build systems. The build model is mostly the same as in Nix, but build targets are configured in Lua instead of a domain-specific language.

For more motivation on the development of zb, see the early blog posts:

• zb: A Build System Prototype
• zb: An Early-Stage Build System

Examples

The hello world example:

return derivation {
  name    = "hello";
  infile  = path "hello.txt";
  builder = "/bin/sh";
  system  = "x86_64-linux";
  args    = {"-c", "while read line; do echo \"$line\"; done < $infile > $out"};
}

Other examples:

• Multi-step builds
• stage0-posix/x86_64-linux.lua, which uses the stage0-posix project to build a minimal userspace (including a rudimentary C compiler).
• bootstrap.lua, which follows the live-bootstrap project steps to build a more complete userspace.

Getting Started

Prerequisites:

• Knowledge of using the command-line for your OS (e.g. Terminal.app, Command Prompt, etc.)
• Go 1.23.2 or later.

Linux or macOS

1. sudo mkdir /zb && sudo chown $(id -u):$(id -g) /zb
2. Clone this repository to your computer and cd into it.
3. go build ./cmd/zb
4. Start the build server (only on startup): ./zb serve --sandbox=0 &
5. Run a build: ./zb build --file demo/hello.lua

You can use ./zb --help to get more information on commands.

Windows

Must be running Windows 10 or later, since zb depends on Windows support for Unix sockets.

1. Install MinGW-w64. If you're using the Chocolatey package manager, you can run choco install mingw.
2. Create a C:\zb directory.
3. Clone this repository to your computer and cd into it.
4. go build .\cmd\zb
5. Start the build server in one terminal: .\zb.exe serve
6. Run a build in another terminal: .\zb.exe build --file demo/hello_windows.lua

Next Steps

zb uses a slightly modified version of Lua 5.4. The primary difference is that strings (like those returned from the path function or the .out field of a derivation) can carry dependency information, like in the Nix expression language. This is largely hidden from the user. From there, the following libraries are available:

• Basic functions
• The table module
• Additional functions, such as path and derivation. These are intentionally similar to the Nix built-in functions.

Objectives

• Prove that Lua is a viable alternative to a domain-specific build language. (Done!)
• Exclusively use content-addressed outputs. (Done!) This enables shallow builds, as described in Build systems à la carte.
• Establish a source bootstrap that is equivalent to the nixpkgs standard environment. (Partially implemented by following the live-bootstrap steps. See #30 for ongoing work.)

License

MIT