diff options
Diffstat (limited to 'doc/manual/src/architecture/store/store.md')
| -rw-r--r-- | doc/manual/src/architecture/store/store.md | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md new file mode 100644 index 000000000..08b6701d5 --- /dev/null +++ b/doc/manual/src/architecture/store/store.md @@ -0,0 +1,151 @@ +# Store + +A Nix store is a collection of *store objects* with references between them. +It supports operations to manipulate that collection. + +The following concept map is a graphical outline of this chapter. +Arrows indicate suggested reading order. + +``` + ,--------------[ store ]----------------, + | | | + v v v + [ store object ] [ closure ]--, [ operations ] + | | | | | | + v | | v v | + [ files and processes ] | | [ garbage collection ] | + / \ | | | + v v | v v +[ file system object ] [ store path ] | [ derivation ]--->[ building ] + | ^ | | | + v | v v | + [ digest ]----' [ reference scanning ]<------------' + / \ + v v +[ input addressing ] [ content addressing ] +``` + +## Store Object + +A store object can hold + +- arbitrary *data* +- *references* to other store objects. + +Store objects can be build inputs, build results, or build tasks. + +Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted. + +## Reference + +A store object reference is an [opaque][opaque-data-type], [unique identifier][unique-identifier]: +The only way to obtain references is by adding or building store objects. +A reference will always point to exactly one store object. + +## Operations + +A Nix store can *add*, *retrieve*, and *delete* store objects. + + [ data ] + | + V + [ store ] ---> add ----> [ store' ] + | + V + [ reference ] + +<!-- --> + + [ reference ] + | + V + [ store ] ---> get + | + V + [ store object ] + +<!-- --> + + [ reference ] + | + V + [ store ] --> delete --> [ store' ] + + +It can *perform builds*, that is, create new store objects by transforming build inputs into build outputs, using instructions from the build tasks. + + + [ reference ] + | + V + [ store ] --> build --(maybe)--> [ store' ] + | + V + [ reference ] + + +As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects. + + + [ store ] --> collect garbage --> [ store' ] + +## Files and Processes + +Nix maps between its store model and the [Unix paradigm][unix-paradigm] of [files and processes][file-descriptor], by encoding immutable store objects and opaque identifiers as file system primitives: files and directories, and paths. +That allows processes to resolve references contained in files and thus access the contents of store objects. + +Store objects are therefore implemented as the pair of + + - a [file system object](fso.md) for data + - a set of [store paths](path.md) for references. + +[unix-paradigm]: https://en.m.wikipedia.org/wiki/Everything_is_a_file +[file-descriptor]: https://en.m.wikipedia.org/wiki/File_descriptor + +The following diagram shows a radical simplification of how Nix interacts with the operating system: +It uses files as build inputs, and build outputs are files again. +On the operating system, files can be run as processes, which in turn operate on files. +A build function also amounts to an operating system process (not depicted). + +``` ++-----------------------------------------------------------------+ +| Nix | +| [ commmand line interface ]------, | +| | | | +| evaluates | | +| | manages | +| V | | +| [ configuration language ] | | +| | | | +| +-----------------------------|-------------------V-----------+ | +| | store evaluates to | | +| | | | | +| | referenced by V builds | | +| | [ build input ] ---> [ build plan ] ---> [ build result ] | | +| | ^ | | | +| +---------|----------------------------------------|----------+ | ++-----------|----------------------------------------|------------+ + | | + file system object store path + | | ++-----------|----------------------------------------|------------+ +| operating system +------------+ | | +| '------------ | | <-----------' | +| | file | | +| ,-- | | <-, | +| | +------------+ | | +| execute as | | read, write, execute | +| | +------------+ | | +| '-> | process | --' | +| +------------+ | ++-----------------------------------------------------------------+ +``` + +There exist different types of stores, which all follow this model. +Examples: +- store on the local file system +- remote store accessible via SSH +- binary cache store accessible via HTTP + +To make store objects accessible to processes, stores ultimately have to expose store objects through the file system. + |