diff --git a/doc/manual/source/advanced-topics/distributed-builds.md b/doc/manual/source/advanced-topics/distributed-builds.md index 66e371888..464b87d6e 100644 --- a/doc/manual/source/advanced-topics/distributed-builds.md +++ b/doc/manual/source/advanced-topics/distributed-builds.md @@ -20,7 +20,7 @@ For a local machine to forward a build to a remote machine, the remote machine m ## Testing -To test connecting to a remote Nix instance (in this case `mac`), run: +To test connecting to a remote [Nix instance] (in this case `mac`), run: ```console nix store info --store ssh://username@mac @@ -106,3 +106,5 @@ file included in `builders` via the syntax `@/path/to/file`. For example, causes the list of machines in `/etc/nix/machines` to be included. (This is the default.) + +[Nix instance]: @docroot@/glossary.md#gloss-nix-instance \ No newline at end of file diff --git a/doc/manual/source/glossary.md b/doc/manual/source/glossary.md index db6d18f0e..6a7501200 100644 --- a/doc/manual/source/glossary.md +++ b/doc/manual/source/glossary.md @@ -1,5 +1,13 @@ # Glossary +- [build system]{#gloss-build-system} + + Generic term for software that facilitates the building of software by automating the invocation of compilers, linkers, and other tools. + + Nix can be used as a generic build system. + It has no knowledge of any particular programming language or toolchain. + These details are specified in [derivation expressions](#gloss-derivation-expression). + - [content address]{#gloss-content-address} A @@ -19,6 +27,10 @@ Besides content addressing, the Nix store also uses [input addressing](#gloss-input-addressed-store-object). +- [content-addressed storage]{#gloss-content-addressed-store} + + The industry term for storage and retrieval systems using [content addressing](#gloss-content-address). A Nix store also has [input addressing](#gloss-input-addressed-store-object), and metadata. + - [store derivation]{#gloss-store-derivation} A single build task. @@ -88,6 +100,12 @@ [store]: #gloss-store +- [Nix instance]{#gloss-nix-instance} + + 1. An installation of Nix, which includes the presence of a [store], and the Nix package manager which operates on that store. + A local Nix installation and a [remote builder](@docroot@/advanced-topics/distributed-builds.md) are two examples of Nix instances. + 2. A running Nix process, such as the `nix` command. + - [binary cache]{#gloss-binary-cache} A *binary cache* is a Nix store which uses a different format: its @@ -220,7 +238,7 @@ directly or indirectly “reachable” from that store path; that is, it’s the closure of the path under the *references* relation. For a package, the closure of its derivation is equivalent to the - build-time dependencies, while the closure of its output path is + build-time dependencies, while the closure of its [output path] is equivalent to its runtime dependencies. For correct deployment it is necessary to deploy whole closures, since otherwise at runtime files could be missing. The command `nix-store --query --requisites ` prints out diff --git a/doc/manual/source/protocols/store-path.md b/doc/manual/source/protocols/store-path.md index 8ec6f8201..9abd83f4f 100644 --- a/doc/manual/source/protocols/store-path.md +++ b/doc/manual/source/protocols/store-path.md @@ -53,7 +53,7 @@ where method of content addressing store objects, if the hash algorithm is [SHA-256]. Just like in the "Text" case, we can have the store objects referenced by their paths. - Additionally, we can have an optional `:self` label to denote self reference. + Additionally, we can have an optional `:self` label to denote self-reference. - ```ebnf | "output:" id diff --git a/doc/manual/source/store/building.md b/doc/manual/source/store/building.md index feefa8e3f..dbfe6b5ca 100644 --- a/doc/manual/source/store/building.md +++ b/doc/manual/source/store/building.md @@ -54,7 +54,7 @@ The [`builder`](./derivation/index.md#builder) is executed as follows: it’s `out`.) - If an output path already exists, it is removed. Also, locks are - acquired to prevent multiple Nix instances from performing the same + acquired to prevent multiple [Nix instances][Nix instance] from performing the same build at the same time. - A log of the combined standard output and error is written to @@ -95,3 +95,6 @@ If the builder exited successfully, the following steps happen in order to turn Nix also scans for references to other outputs' paths in the same way, because outputs are allowed to refer to each other. If the outputs' references to each other form a cycle, this is an error, because the references of store objects much be acyclic. + + +[Nix instance]: @docroot@/glossary.md#gloss-nix-instance diff --git a/doc/manual/source/store/derivation/index.md b/doc/manual/source/store/derivation/index.md index 42cfa67f5..911c28485 100644 --- a/doc/manual/source/store/derivation/index.md +++ b/doc/manual/source/store/derivation/index.md @@ -1,7 +1,7 @@ # Store Derivation and Deriving Path -Besides functioning as a [content addressed store] the Nix store layer works as a [build system]. -Other system (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created. +Besides functioning as a [content-addressed store], the Nix store layer works as a [build system]. +Other systems (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created. This is where Nix distinguishes itself. *Derivations* represent individual build steps, and *deriving paths* are needed to refer to the *outputs* of those build steps before they are built. @@ -42,6 +42,8 @@ A derivation consists of: [args]: #args [env]: #env [system]: #system +[content-addressed store]: @docroot@/glossary.md#gloss-content-addressed-store +[build system]: @docroot@/glossary.md#gloss-build-system ### Referencing derivations {#derivation-path} @@ -78,7 +80,7 @@ type DerivingPath = ConstantPath | OutputPath; ``` Deriving paths are necessary because, in general and particularly for [content-addressing derivations][content-addressing derivation], the [store path] of an [output] is not known in advance. -We can use an output deriving path to refer to such an out, instead of the store path which we do not yet know. +We can use an output deriving path to refer to such an output, instead of the store path which we do not yet know. [deriving path]: #deriving-path [validity]: @docroot@/glossary.md#gloss-validity @@ -89,25 +91,26 @@ A derivation is constructed from the parts documented in the following subsectio ### Inputs {#inputs} -The inputs are a set of [deriving paths][deriving path], refering to all store objects needed in order to perform this build step. +The inputs are a set of [deriving paths][deriving path], referring to all store objects needed in order to perform this build step. The [process creation fields] will presumably include many [store paths][store path]: - The path to the executable normally starts with a store path - The arguments and environment variables likely contain many other store paths. -But rather than somehow scanning all the other fields for inputs, Nix requires that all inputs be explicitly collected in the inputs field. It is instead the responsibility of the creator of a derivation (e.g. the evaluator) to ensure that every store object referenced in another field (e.g. referenced by store path) is included in this inputs field. +But rather than somehow scanning all the other fields for inputs, Nix requires that all inputs be explicitly collected in the inputs field. It is instead the responsibility of the creator of a derivation (e.g. the evaluator) to ensure that every store object referenced in another field (e.g. referenced by store path) is included in this inputs field. ### System {#system} The system type on which the [`builder`](#attr-builder) executable is meant to be run. -A necessary condition for Nix to schedule a given derivation on some Nix instance is for the "system" of that derivation to match that instance's [`system` configuration option]. +A necessary condition for Nix to schedule a given derivation on some [Nix instance] is for the "system" of that derivation to match that instance's [`system` configuration option] or [`extra-platforms` configuration option]. By putting the `system` in each derivation, Nix allows *heterogenous* build plans, where not all steps can be run on the same machine or same sort of machine. Nix can schedule builds such that it automatically builds on other platforms by [forwarding build requests](@docroot@/advanced-topics/distributed-builds.md) to other Nix instances. [`system` configuration option]: @docroot@/command-ref/conf-file.md#conf-system +[`extra-platforms` configuration option]: @docroot@/command-ref/conf-file.md#conf-extra-platforms [content-addressing derivation]: @docroot@/glossary.md#gloss-content-addressing-derivation [realise]: @docroot@/glossary.md#gloss-realise @@ -240,14 +243,14 @@ That works because we've implicitly assumed that all derivations are created *st But what if derivations could also be created dynamically within Nix? In other words, what if derivations could be the outputs of other derivations? -:::{.note} -In the parlance of "Build Systems à la carte", we are generalizing the Nix store layer to be a "Monadic" instead of "Applicative" build system. -::: +> **Note** +> +> In the parlance of "Build Systems à la carte", we are generalizing the Nix store layer to be a "Monadic" instead of "Applicative" build system. How should we refer to such derivations? A deriving path works, the same as how we refer to other derivation outputs. But what about a dynamic derivations output? -(i.e. how do we refer to the output of an output of a derivation?) +(i.e. how do we refer to the output of a derivation, which is itself an output of a derivation?) For that we need to generalize the definition of deriving path, replacing the store path used to refer to the derivation with a nested deriving path: ```diff @@ -295,3 +298,5 @@ The result of this is that it is possible to have a chain of `^` at > |------------------------------------------------------------| |-----| > innermost constant store path (usual encoding) output name > ``` + +[Nix instance]: @docroot@/glossary.md#gloss-nix-instance diff --git a/doc/manual/source/store/derivation/outputs/content-address.md b/doc/manual/source/store/derivation/outputs/content-address.md index 21e940bc2..4539a5eba 100644 --- a/doc/manual/source/store/derivation/outputs/content-address.md +++ b/doc/manual/source/store/derivation/outputs/content-address.md @@ -12,7 +12,7 @@ Given the method, the output's name (computed from the derivation name and outpu ## Fixed-output content-addressing {#fixed} -In this case the content-address of the *fixed* in advanced by the derivation itself. +In this case the content address of the *fixed* in advanced by the derivation itself. In other words, when the derivation has finished [building](@docroot@/store/building.md), and the provisional output' content-address is computed as part of the process to turn it into a *bona fide* store object, the calculated content address must much that given in the derivation, or the build of that derivation will be deemed a failure. The output spec for an output with a fixed content addresses additionally contains: @@ -159,7 +159,7 @@ A *determinstic* content-addressing derivation should produce outputs with the s ### Floating versus Fixed -While the destinction between content- and input-addressing is one of *mechanism*, the distinction between fixed and floating content addression is more one of *policy*. +While the distinction between content- and input-addressing is one of *mechanism*, the distinction between fixed and floating content addressing is more one of *policy*. A fixed output that passes its content address check is just like a floating output. It is only in the potential for that check to fail that they are different. diff --git a/doc/manual/source/store/derivation/outputs/input-address.md b/doc/manual/source/store/derivation/outputs/input-address.md index 54d9437d9..e2e15a801 100644 --- a/doc/manual/source/store/derivation/outputs/input-address.md +++ b/doc/manual/source/store/derivation/outputs/input-address.md @@ -3,7 +3,7 @@ [input addressing]: #input-addressing "Input addressing" means the address the store object by the *way it was made* rather than *what it is*. -That is to say, an input-addressed output's store path is a function not of the output itself, but the derivation that produced it. +That is to say, an input-addressed output's store path is a function not of the output itself, but of the derivation that produced it. Even if two store paths have the same contents, if they are produced in different ways, and one is input-addressed, then they will have different store paths, and thus guaranteed to not be the same store object.