From f632816cbaefbba9cc27a8e0de6cffd39fa7a8dd Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 8 Jun 2022 11:09:27 +0200 Subject: [PATCH] add explanation and examples of file system objects --- doc/manual/src/architecture/store/fso.md | 64 ++++++++++++++++++++++ doc/manual/src/architecture/store/store.md | 4 +- 2 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 doc/manual/src/architecture/store/fso.md diff --git a/doc/manual/src/architecture/store/fso.md b/doc/manual/src/architecture/store/fso.md new file mode 100644 index 000000000..958b8f62a --- /dev/null +++ b/doc/manual/src/architecture/store/fso.md @@ -0,0 +1,64 @@ +# File System Object + +The Nix store uses a simple file system model for the data it holds in [store objects](store.md#store-object). + +Every file system object is one of the following: + + - File: an executable flag, and arbitrary data for contents + - Directory: mapping of names to child file system objects + - [Symbolic link][symlink]: may point anywhere. + +We call a store object's outermost file system object the *root*. + + data FileSystemObject + = File { isExecutable :: Bool, contents :: Bytes } + | Directory { entries :: Map FileName FileSystemObject } + | SymLink { target :: Path } + +Examples: + +- a directory with contents + + /nix/store/-hello-2.10 + ├── bin + │   └── hello + └── share + ├── info + │   └── hello.info + └── man + └── man1 + └── hello.1.gz + +- a directory with relative symlink and other contents + + /nix/store/-go-1.16.9 + ├── bin -> share/go/bin + ├── nix-support/ + └── share/ + +- a directory with absolute symlink + + /nix/store/d3k...-nodejs + └── nix_node -> /nix/store/f20...-nodejs-10.24. + +A bare file or symlink can be a root file system object. +Examles: + + /nix/store/-hello-2.10.tar.gz + + /nix/store/4j5...-pkg-config-wrapper-0.29.2-doc -> /nix/store/i99...-pkg-config-0.29.2-doc + +Symlinks pointing outside of their own root or to a store object without a matching reference are allowed, but might not function as intended. +Examples: + +- an arbitrarily symlinked file may change or not exist at all + + /nix/store/-foo + └── foo -> /home/foo + +- if a symlink to a store path was not automatically created by Nix, it may be invalid or get invalidated when the store object is deleted + + /nix/store/-bar + └── bar -> /nix/store/abc...-foo + +[symlink]: https://en.m.wikipedia.org/wiki/Symbolic_link diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md index 3b99982e4..68bdadc4a 100644 --- a/doc/manual/src/architecture/store/store.md +++ b/doc/manual/src/architecture/store/store.md @@ -2,7 +2,7 @@ A Nix store is a collection of *store objects*. -## Store Object +## Store Object {#store-object} A store object can hold @@ -102,7 +102,7 @@ That allows processes to resolve references contained in files and thus access t Store objects are therefore implemented as the pair of - - a *file system object* for data + - a [file system object](fso.md) for data - a set of *store paths* for references. [unix-paradigm]: https://en.m.wikipedia.org/wiki/Everything_is_a_file