README
¶
zb
zb (pronounced "zee bee" or "zeeb") 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:
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
sudo mkdir /zb && sudo chown $(id -u):$(id -g) /zb- Clone this repository to your computer and
cdinto it. go build ./cmd/zb- Start the build server (only on startup):
./zb serve --sandbox=0 & - 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.
- Install MinGW-w64.
If you're using the Chocolatey package manager,
you can run
choco install mingw. - Create a
C:\zbdirectory. - Clone this repository to your computer and
cdinto it. go build .\cmd\zb- Start the build server in one terminal:
.\zb.exe serve - 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
tablemodule - Additional functions, such as
pathandderivation. 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
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
internal
|
|
|
aterm
Package aterm implements the subset of the ASCII ATerm format used by Nix.
|
Package aterm implements the subset of the ASCII ATerm format used by Nix. |
|
backend
Package backend provides a zbstore implementation backed by local compute resources.
|
Package backend provides a zbstore implementation backed by local compute resources. |
|
bufseek
Package bufseek provides a buffered io.Reader that also implements io.Seeker.
|
Package bufseek provides a buffered io.Reader that also implements io.Seeker. |
|
deque
Package deque provides a double-ended queue type.
|
Package deque provides a double-ended queue type. |
|
detect
Package detect provides types that perform string detection and replacement on byte streams.
|
Package detect provides types that perform string detection and replacement on byte streams. |
|
jsonrpc
Package jsonrpc provides a stream-based implementation of the JSON-RPC 2.0 specification, inspired by the Language Server Protocol (LSP) framing format.
|
Package jsonrpc provides a stream-based implementation of the JSON-RPC 2.0 specification, inspired by the Language Server Protocol (LSP) framing format. |
|
jsonstring
Package jsonstring provides a function for encoding a JSON string literal.
|
Package jsonstring provides a function for encoding a JSON string literal. |
|
lua
Package lua provides low-level bindings for [Lua 5.4].
|
Package lua provides low-level bindings for [Lua 5.4]. |
|
osutil
Package osutil provides convenience functions for working with the local filesystem.
|
Package osutil provides convenience functions for working with the local filesystem. |
|
storepath
Package storepath provides shared internal logic for store paths.
|
Package storepath provides shared internal logic for store paths. |
|
storetest
Package storetest provides utilities for interacting with the zb store in tests.
|
Package storetest provides utilities for interacting with the zb store in tests. |
|
system
Package system implements parsing of "system" values.
|
Package system implements parsing of "system" values. |
|
xiter
Package xiter provides various functions useful with iterators of any type.
|
Package xiter provides various functions useful with iterators of any type. |
|
xmaps
Package xmaps provides more generic functions in the spirit of the maps package.
|
Package xmaps provides more generic functions in the spirit of the maps package. |
|
xslices
Package xslices provides more generic functions in the spirit of the slices package.
|
Package xslices provides more generic functions in the spirit of the slices package. |
|
Package sets provides set types.
|
Package sets provides set types. |
|
Package zbstore provides the data types for the zb store API.
|
Package zbstore provides the data types for the zb store API. |
Click to show internal directories.
Click to hide internal directories.