Glossary

A derivation is Nix’s serializable description of a build. It can be stored in the store as a .drv file.

It consists of a number of fields that tell Nix exactly how to perform a build, resulting in files and/or directories at computed output paths in the store.

It is also used by Nix to describe development shells and by Hercules CI to describe effects. In these cases the definition of some fields is amended and no output is produced.

A Hercules CI Effect is a program that runs in the effects sandbox instead of the Nix sandbox. It can access the network, Nix store and locally configured secrets.

An effect is described by a special derivation.

See also hercules-ci-effects for a library of effect functions.

In Nix, evaluation is the process of turning Nix expressions into values according to the semantics of the language. This is analogous to "execution" in statement-based languages, although lazy evaluation makes such a comparison somewhat remote. During evaluation, Nix can produce derivation files and it can log.

In Hercules CI, "evaluation" is also used for the first unit of work of a job, which encompasses a bit more than just Nix evaluation; mostly checkout and upload of metadata and derivations.

A Nix expression is code in the Nix language. It can produce a value, throw an exception or fail in some other way.

Sometimes a file containing an expression is referred to as an expression too. The import p syntax is evaluated by parsing the file (if needed, because Nix evaluates expressions lazily).

A job is the largest coherent "unit of work" in Hercules CI, in the sense that it can be described using the combination of

A job produces one commit status, or, before agent 0.9, three statuses for evaluation, build and effects.

See Job Definition (prerelease).

A package is not a clearly defined concept in Nix, but rather a pattern in Nixpkgs.

While the Nix language is primarily concerned with the creation of derivations, these derivations are usually referenced from attribute sets containing attributes such as outPath and meta.license. These attribute sets can be referred to as packages. Whether a derivation without attributes like meta.license is a package is debatable, but usually derivations and packages in Nixpkgs are interchangeable. The callPackage function name implies that functions producing derivations are packages, but this is generally not as useful a definition.

A secret is a confidential value, typically related to some form of authentication. In Hercules CI specifically, secrets are little pieces of JSON configured on the agent to be used in effects.

Secrets require special treatment and should not be copied to the store, because the store is generally readable by too many processes, services and users, that can compromise their confidentiality too easily.

See also the secrets.json format reference (prerelease).

The Nix store is a location such as /nix/store containing derivation outputs, as well as content-addressed paths such as derivation files and sources.

An in-memory reference to an expression and the variables it references, to be evaluated when needed.

A Nix value is an expression that has been evaluated. The extent of evaluation depends on the context.

A value can consist of primitive types (strings, integers, etc) and composite types such as lists and attribute sets.

Some definitions may include functions, as they can not be evaluated any further without applying them first.

Thunks are normally not considered values.