Specifying What to Build

The arguments to zb build are either a list of paths/URLs, or, if the --expression flag is passed, a Lua expression. Here are some examples:

# Build what is returned from the Lua file at foo/bar.lua.
zb build foo/bar.lua
zb build --expression 'await(import("foo/bar.lua"))'

# Build what is stored in the global variable "myvar"
# in the Lua file at foo/bar.lua.
zb build 'foo/bar.lua#myvar'
zb build --expression 'import("foo/bar.lua").myvar'

# Build what is stored in the field "field"
# in the global table "myvar"
# in the Lua file at foo/bar.lua.
zb build 'foo/bar.lua#myvar/field'
zb build --expression 'import("foo/bar.lua").myvar.field'

# Download the file at https://www.example.com/foo.lua,
# evaluate it as Lua,
# and then build what is stored in the global variable "myvar".
zb build 'https://www.example.com/foo.lua#myvar'

# Download the zip file at https://www.example.com/archive.zip,
# unpack it,
# evaluate the Lua file inside it called "foo.lua",
# then build what is stored in the global variable "myvar".
zb build 'https://www.example.com/archive.zip#foo.lua:myvar'

URL Syntax

URL arguments to zb build can use any of the following schemes:

The fragment of a URL to zb build is split into two parts at the last colon (:) that appears in the fragment. Everything before the last colon is the archive member and everything after the last colon is the key path. If the fragment does not contain a colon, then the entire fragment is the key path. The presence of an archive member instructs zb to treat the file as an archive, extract it using the same mechanism as in extract(), then use the file inside the archive with the same name. If the key path is empty, then the result of evaluating a URL is the same as the result of calling await() on the result of calling import() with the path to the file as its argument. Otherwise, the key path is a slash-separated sequence of table indexes on the module (e.g. a key path of foo/bar/baz is equivalent to foo.bar.baz in Lua).

What Can Be Built

Once zb build has evaluated the Lua value from an expression or a URL, zb build converts the value to a string using tostring, unless the value is a table. Because strings carry dependency information, zb build will build any derivation outputs referenced in the string before printing the full string to standard output. If the Lua value is a table, the table will be walked using pairs. Pairs with keys that are not strings or numbers will be ignored. The last pair with the same string key is the one that will be used. Each value in the table is converted to its default output string. The default output of any non-table value is the result of calling tostring with the value as its argument. The default output of a table is the value of the key "", 1, "1", or "out", in descending order of preference, recursing on any table value.

If a value has a __outputs field in its metatable, then it will override zb’s built-in behavior. The value of the __outputs metatable field can be:

  • A function. The function will be called with the original table and the current system triple as its two arguments.

  • A value with an __outputs field in its metatable. The field will be processed recursively up to an implementation-defined limit.

  • Any non-nil value, which will be used instead of the original table.

See also

outputs()

Built-in function to obtain a value’s outputs in user-defined code.

defaultOutput()

Built-in function to obtain a value’s default output in user-defined code.

derivation()

Built-in function to create strings that cause zb to run a builder program.