Document build arguments

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

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 -------------------------------------------------

index.md

@@ -76,6 +76,7 @@ zb simplifies reproducible builds.
 
 Installation <install>
 getting-started
+build-args
 admin/index
 comparison
 ```

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.

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.