# Builder Protocol

The builder protocol is used by tvix-glue to trigger builds.

One goal of the protocol is to not be too tied to the Nix implementation itself,
allowing it to be used for other builds/workloads in the future.

This means the builder protocol is versatile enough to express the environment a
Nix build expects, while not being aware of "what any of this means".

For example, it is not aware of how certain environment variables are set in a
nix build, but allows specifying environent variables that should be set.

It's also not aware of what nix store paths are. Instead, it allows:

 - specifying a list of paths expected to be produced during the build
 - specifying a list of castore root nodes to be present in a specified
   `inputs_dir`.
 - specifying which paths are write-able during build.

In case all specified paths are produced, and the command specified in
`command_args` succeeds, the build is considered to be successful.

This happens to be sufficient to *also* express how Nix builds works.

Check `build/protos/build.proto` for a detailed description of the individual
fields, and the tests in `glue/src/tvix_build.rs` for some examples.

The following sections describe some aspects of Nix builds, and how this is
(planned to be) implemented with the Tvix Build protocol.

## Reference scanning
At the end of a build, Nix does scan a store path for references to other store
paths (*out of the set of all store paths present during the build*).
It does do this by (only) looking for a list of nixbase32-encoded hashes in
filenames (?), symlink targets and blob contents.

While we could do this entirely outside the builder protocol, it'd mean a build
client would be required to download the produced outputs locally, and do the
refscan there. This is undesireable, as the builder already has all produced
outputs locally, and it'd make more sense for it do do it.

Instead, we want to describe reference scanning in a generic fashion.

One proposed way to do this is to add an additional field `refscan_needles` to
the `BuildRequest` message.
If this is an non-empty list, all paths in `outputs` are scanned for these.

The `Build` response message would then be extended with an `outputs_needles`
field, containing the same number of elements as the existing `outputs` field.
In there, we'd have a list of numbers, indexing into `refscan_needles`
originally specified.

For Nix, `refscan_needles` would be populated with the nixbase32 hash parts of
every input store path and output store path. The latter is necessary to scan
for references between multi-output derivations.

This is sufficient to construct the referred store paths in each build output on
the build client.