From 5fda995491f1f6b32b46b45c2b47f3e329c997f6 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Fri, 29 Apr 2022 00:24:23 +0200 Subject: [PATCH] formalize file system objects convention: describe every data type in prose, and illustrate with a class diagram, and a textual representation of an abstract data type. right now we save ourselves the trouble of doing class diagrams, we can add them later. but they are important. --- doc/manual/src/architecture/store/objects.md | 25 ++++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md index d7a27b528..7f341c87c 100644 --- a/doc/manual/src/architecture/store/objects.md +++ b/doc/manual/src/architecture/store/objects.md @@ -6,31 +6,42 @@ A store object is the pair of - a [file system object](#file-system-object) - a set of [references](#reference) to store objects. +We call a store object's outermost file system object the *root*. + +```haskell +data StoreOject = StoreObject { + root :: FileSystemObject +, references :: Set StoreObject +} +``` + ## File system object {#file-system-object} The Nix store uses a simple file system model. - data FileSystemObject - = File Executable Contents - | Directory (Map FileName FileSystemObject) - | SymLink Path - 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](https://en.m.wikipedia.org/wiki/Symbolic_link): may point anywhere. - In particular, symlinks pointing outside of their own root file system object, or to a store object without a matching reference, are allowed, but might not function as intended. +```haskell +data FileSystemObject + = File { isExecutable :: Bool, contents :: Bytes } + | Directory { entries :: Map FileName FileSystemObject } + | SymLink { target :: Path } +``` A bare file or symlink can be a root file system object. +Symlinks pointing outside of their own root, or to a store object without a matching reference, are allowed, but might not function as intended. + ## Reference {#reference} A store object can refer to other store objects or itself. Nix collects these references by scanning file contents for [store paths](./paths.md) when a new store object is created. -While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness: +While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness. Anything outside a given store is not under control of Nix, and therefore cannot be guaranteed to be present when needed. However, having references match store paths in files is not enforced by the data model: