diff --git a/build-args.md b/build-args.md new file mode 100644 index 0000000..5b45545 --- /dev/null +++ b/build-args.md @@ -0,0 +1,109 @@ +# 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](lua/index.md) expression. +Here are some examples: + +```shell +# 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' +``` + +```{eval-rst} +.. index:: URL +``` + +## URL Syntax + +URL arguments to `zb build` can use any of the following {rfc}`schemes <3986#section-3.1>`: + +- `file` (default if absent) +- `http` +- `https` +- `gs` ([Google Cloud Storage](https://docs.cloud.google.com/storage/docs/gsutil#syntax)) + +```{eval-rst} +.. index:: URL; fragment +``` + +The {rfc}`fragment <3986#section-3.5>` 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 {lua:func}`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 {lua:func}`await` +on the result of calling {lua:func}`import` with the path to the file as its argument. +Otherwise, the key path is a slash-separated sequence of [table indexes][Variables] on the module +(e.g. a key path of `foo/bar/baz` is equivalent to `foo.bar.baz` in Lua). + +[Variables]: https://www.lua.org/manual/5.4/manual.html#3.2 + +(output-eval)= +## 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](lua/deps.md), +`zb build` will build any {term}`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. + +```{eval-rst} +.. index:: __outputs metatable field +``` + +```{include} outputs-metafield.md +``` + +:::{seealso} + +{lua:func}`outputs` +: Built-in function to obtain a value's outputs in user-defined code. + +{lua:func}`defaultOutput` +: Built-in function to obtain a value's default output in user-defined code. + +{lua:func}`derivation` +: Built-in function to create strings that cause zb to run a {term}`builder program`. + +::: + +[`pairs`]: https://www.lua.org/manual/5.4/manual.html#pdf-pairs +[`tostring`]: https://www.lua.org/manual/5.4/manual.html#pdf-tostring +[Metatables and Metamethods]: https://www.lua.org/manual/5.4/manual.html#2.4 diff --git a/conf.py b/conf.py index 90ae95e..79d7015 100644 --- a/conf.py +++ b/conf.py @@ -36,7 +36,7 @@ ] templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md', 'outputs-metafield.md'] primary_domain = 'lua' # -- Options for HTML output ------------------------------------------------- diff --git a/index.md b/index.md index f248f5a..231cafb 100644 --- a/index.md +++ b/index.md @@ -76,6 +76,7 @@ zb simplifies reproducible builds. Installation getting-started +build-args admin/index comparison ``` diff --git a/lua/extensions.md b/lua/extensions.md index d267ac7..ba3f064 100644 --- a/lua/extensions.md +++ b/lua/extensions.md @@ -136,6 +136,56 @@ The environment that the builder runs in is documented in the [Derivation Specif [Derivation Specification]: ../derivations.md +::::{function} outputs(x, system) + +```{version-added} 0.2 +``` + +Get a value's outputs +using the same logic that `zb build` uses to determine [what to build](project:#output-eval). + +```{include} ../outputs-metafield.md +``` + +:param x: + The value to get outputs for. + +:param string system: + A {term}`system triple` to get outputs for. + +:returns: + A table of output strings. + The keys will be strings that correspond to zb's name for each output. + The default output is normalized to the empty string key. + +:rtype: table + +:::: + +::::{function} defaultOutput(x, system) + +```{version-added} 0.2 +``` + +Get a value's default output +using the same logic that `zb build` uses to determine [what to build](project:#output-eval). + +```{include} ../outputs-metafield.md +``` + +:param x: + The value to get the default output for. + +:param string system: + A {term}`system triple` to get the default output for. + +:returns: + The default output converted to a string. + +:rtype: string + +:::: + :::{function} fetchurl{url, hash, [name], [executable]} `fetchurl` returns a derivation that downloads a URL. diff --git a/outputs-metafield.md b/outputs-metafield.md new file mode 100644 index 0000000..9bb2271 --- /dev/null +++ b/outputs-metafield.md @@ -0,0 +1,12 @@ +If a value has a `__outputs` field in its [metatable](https://www.lua.org/manual/5.4/manual.html#2.4), +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 {term}`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.