Struct tvix_build::proto::BuildRequest

pub struct BuildRequest {
    pub inputs: Vec<Node>,
    pub command_args: Vec<String>,
    pub working_dir: String,
    pub scratch_paths: Vec<String>,
    pub inputs_dir: String,
    pub outputs: Vec<String>,
    pub environment_vars: Vec<EnvVar>,
    pub constraints: Option<BuildConstraints>,
    pub additional_files: Vec<AdditionalFile>,
    pub refscan_needles: Vec<String>,
}

A BuildRequest describes the request of something to be run on the builder. It is distinct from an actual [Build] that has already happened, or might be currently ongoing.

A BuildRequest can be seen as a more normalized version of a Derivation (parsed from A-Term), “writing out” some of the Nix-internal details about how e.g. environment variables in the build are set.

Nix has some impurities when building a Derivation, for example the –cores option ends up as an environment variable in the build, that’s not part of the ATerm.

As of now, we serialize this into the BuildRequest, so builders can stay dumb. This might change in the future.

There’s also a big difference when it comes to how inputs are modelled:

• Nix only uses store path (strings) to describe the inputs. As store paths can be input-addressed, a certain store path can contain different contents (as not all store paths are binary reproducible). This requires that for every input-addressed input, the builder has access to either the input’s deriver (and needs to build it) or else a trusted source for the built input. to upload input-addressed paths, requiring the trusted users concept.
• tvix-build records a list of tvix.castore.v1.Node as inputs. These map from the store path base name to their contents, relieving the builder from having to “trust” any input-addressed paths, contrary to Nix.

While this approach gives a better hermeticity, it has one downside: A BuildRequest can only be sent once the contents of all its inputs are known.

As of now, we’re okay to accept this, but it prevents uploading an entirely-non-IFD subgraph of BuildRequests eagerly.

FUTUREWORK: We might be introducing another way to refer to inputs, to support “send all BuildRequest for a nixpkgs eval to a remote builder and put the laptop to sleep” usecases later.

Fields

inputs: Vec<Node>

The list of all root nodes that should be visible in inputs_dir at the time of the build. As all references are content-addressed, no additional signatures are needed to substitute / make these available in the build environment. Inputs MUST be sorted by their names.

command_args: Vec<String>

The command (and its args) executed as the build script. In the case of a Nix derivation, this is usually [“/path/to/some-bash/bin/bash”, “-e”, “/path/to/some/builder.sh”].

working_dir: String

The working dir of the command, relative to the build root. “build”, in the case of Nix. This MUST be a clean relative path, without any “.”, “..”, or superfluous slashes.

scratch_paths: Vec<String>

A list of “scratch” paths, relative to the build root. These will be write-able during the build. [build, nix/store] in the case of Nix. These MUST be clean relative paths, without any “.”, “..”, or superfluous slashes, and sorted.

inputs_dir: String

The path where the castore input nodes will be located at, “nix/store” in case of Nix. Builds might also write into here (Nix builds do that). This MUST be a clean relative path, without any “.”, “..”, or superfluous slashes.

outputs: Vec<String>

The list of output paths the build is expected to produce, relative to the root. If the path is not produced, the build is considered to have failed. These MUST be clean relative paths, without any “.”, “..”, or superfluous slashes, and sorted.

environment_vars: Vec<EnvVar>

The list of environment variables and their values that should be set inside the build environment. This includes both environment vars set inside the derivation, as well as more “ephemeral” ones like NIX_BUILD_CORES, controlled by the --cores CLI option of nix-build. For now, we consume this as an option when turning a Derivation into a BuildRequest, similar to how Nix has a --cores option. We don’t want to bleed these very nix-specific sandbox impl details into (dumber) builders if we don’t have to. Environment variables are sorted by their keys.

constraints: Option<BuildConstraints>

A set of constraints that need to be satisfied on a build host before a Build can be started.

additional_files: Vec<AdditionalFile>

Additional (small) files and their contents that should be placed into the build environment, but outside inputs_dir. Used for passAsFile and structuredAttrs in Nix.

refscan_needles: Vec<String>

If this is an non-empty list, all paths in outputs are scanned for these. 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.

Trait Implementations

impl Clone for BuildRequest

fn clone(&self) -> BuildRequest

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BuildRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BuildRequest

fn default() -> Self

Returns the “default value” for a type.

impl From<BuildRequest> for BuildRequest

fn from(value: BuildRequest) -> Self

Converts to this type from the input type.

impl Message for BuildRequest

fn encoded_len(&self) -> usize

Returns the encoded length of the message without a length delimiter.

fn clear(&mut self)

Clears the message, resetting all fields to their default.

fn encode(&self, buf: &mut impl BufMut) -> Result<(), EncodeError>

where Self: Sized,

Encodes the message to a buffer.

fn encode_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message to a newly allocated buffer.

fn encode_length_delimited( &self, buf: &mut impl BufMut, ) -> Result<(), EncodeError>

where Self: Sized,

Encodes the message with a length-delimiter to a buffer.

fn encode_length_delimited_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message with a length-delimiter to a newly allocated buffer.

fn decode(buf: impl Buf) -> Result<Self, DecodeError>

where Self: Default,

Decodes an instance of the message from a buffer.

fn decode_length_delimited(buf: impl Buf) -> Result<Self, DecodeError>

where Self: Default,

Decodes a length-delimited instance of the message from the buffer.

fn merge(&mut self, buf: impl Buf) -> Result<(), DecodeError>

where Self: Sized,

Decodes an instance of the message from a buffer, and merges it into self.

fn merge_length_delimited(&mut self, buf: impl Buf) -> Result<(), DecodeError>

where Self: Sized,

Decodes a length-delimited instance of the message from buffer, and merges it into self.

impl PartialEq for BuildRequest

fn eq(&self, other: &BuildRequest) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<BuildRequest> for BuildRequest

type Error = ValidateBuildRequestError

The type returned in the event of a conversion error.

fn try_from(value: BuildRequest) -> Result<Self, Self::Error>

Performs the conversion.

impl StructuralPartialEq for BuildRequest