Module derivation 

Nix derivations

This module allows you to construct, store, parse, … Nix derivations.

There’s two major types representing Derivations, UnverifiedDerivation and Derivation.

They can be constructed either from parsing ATerm (using Derivation::from_aterm_bytes or UnverifiedDerivation::from_aterm_bytes respectively), deserializing through serde, or using DerivationBuilder.

Contrary to UnverifiedDerivation, Derivation can only be constructed when it’s certain that the output path calculation is done correctly. So the name and a lookup function for the hash derivation modulos needs to be passed in whenever this type is constructed.

Hash Derivation Modulo

In order to ensure that the output paths of input addressed derivations are derived from the inputs of the derivation, a SHA256, calculated based on the type of the input derivation, is used. This digest is called the Hash Derivation Modulo (or HDM for short) and is used recursively to capture the entire input closure in a kind of merkle tree.

Generally HDM comes in three flavors: Fixed, Derivation Input and Derivation Output. These are described in more detail below.

Fixed

The Fixed HDM (also called the FOD digest) is used for Fixed Output Derivations and form the leafs of the derivation merkle tree.

Unlike the flavors of HDM described later, this one is not based on the ATerm representation of the derivation. It is instead calculated based on the OutputHash and StorePath of the derivation output.

The following code illustrates the format:

let rec = if is_recursive { "r:" } else { "" };
let algo = nix_hash.algo();
let digest = data_encoding::HEXLOWER.encode(nix_hash.digest_as_bytes());
// The output path of the derivation
let fod_output_path = "/nix/store/mp57d33657rf34lzvlbpfa1gjfv5gmpg-bar";
let hdm = format_sha256!("fixed:out:{rec}{algo}:{digest}:{fod_output_path}");

This is the hash returned by UnverifiedDerivation::fod_digest.

Derivation Input

The Derivation Input HDM is calculated for Input Addressed derivations and used by dependent derivations in their own HDM calculations to form a merkle tree.

This HDM is a SHA256 digest of a special version of the ATerm serialized output of the derivation. In this version of the ATerm serialization, where normally the StorePath of input derivations would be written, it has instead been replaced with the Derivation Input HDM or the Fixed HDM (depending on what type of derivation it is).

This is the hash used returned by UnverifiedDerivation::hash_derivation_modulo.

Derivation Output

When calculating the HDM we want to use in the creation of output paths we don’t have the output paths yet. So instead of SHA256 digesting the same ATerm format as used by Derivation Input, we additionally replace the output paths, as well as their corresponding environment variables, in the ATerm serialization with empty strings.

This is the hash used internally by DerivationBuilder::calculate_outputs.

Re-exports

pub use crate::nixhash::CAHash;

pub use crate::nixhash::NixHash;

Modules

builder 🔒

errors 🔒

Contains DerivationError, exported as crate::derivation::DerivationError

hdm_lookup 🔒

output 🔒

output_name 🔒

outputs

Outputs for a derivation.

parse_error 🔒

This contains error and result types that can happen while parsing Derivations from ATerm.

parser 🔒

This module constructs a UnverifiedDerivation by parsing its ATerm serialization.

serde_impl 🔒 serde

write 🔒

This module implements the serialisation of derivations into the ATerm format used by C++ Nix.

Structs

Derivation

A verified derivation with its StorePath.

DerivationBuilder

Builder for Derivation and UnverifiedDerivation.

OutputHash

Represents the information about the hash of a single-output FOD. We store it in a OutputHashMode and NixHash. The serde model uses a different format, as we want to emit the same JSON: There we use hashAlgo and hash:

OutputName

A derivation output name.

Outputs

Derivation outputs with filled out StorePath.

UnverifiedDerivation

A derivation with its output paths filled out but not verified.

UnverifiedOutputsBuilder

Builder for making unverified Outputs.

Enums

DerivationError

Errors that can occur during the validation of Derivation structs.

OutputHashMode

Whether the FOD describes the hash of the raw contents (only possible if it’s a single file), or a digest over the NAR representation of the contents.

OutputsBuilder

A builder for outputs.

ParseOutputNameError

The error type for when parsing an OutputName fails.

ParserError

The error type for derivation parsing errors

Traits

DerivationAsyncExt 🔒 async

HashDerivationModuloLookup

Lookup hash derivation modulo for a derivation.

Functions

lookup_fn

Implement HashDerivationModuloLookup using the provided closure.