Merge pull request #10479 from obsidiansystems/ca-fso-docs

Document file system object content addressing

src/libcmd/misc-store-flags.cc

@@ -81,9 +81,15 @@ Args::Flag fileIngestionMethod(FileIngestionMethod * method)
     How to compute the hash of the input.
     One of:
 
-    - `nar` (the default): Serialises the input as an archive (following the [_Nix Archive Format_](https://edolstra.github.io/pubs/phd-thesis.pdf#page=101)) and passes that to the hash function.
+    - `nar` (the default):
+      Serialises the input as a
+      [Nix Archive](@docroot@/store/file-system-object/content-address.md#serial-nix-archive)
+      and passes that to the hash function.
 
-    - `flat`: Assumes that the input is a single file and directly passes it to the hash function;
+    - `flat`:
+      Assumes that the input is a single file and
+      [directly passes](@docroot@/store/file-system-object/content-address.md#serial-flat)
+      it to the hash function.
         )",
         .labels = {"file-ingestion-method"},
         .handler = {[method](std::string s) {
@@ -97,16 +103,24 @@ Args::Flag contentAddressMethod(ContentAddressMethod * method)
     return Args::Flag {
         .longName  = "mode",
         // FIXME indentation carefully made for context, this is messed up.
+        /* FIXME link to store object content-addressing not file system
+           object content addressing once we have that page. */
         .description = R"(
     How to compute the content-address of the store object.
     One of:
 
-    - `nar` (the default): Serialises the input as an archive (following the [_Nix Archive Format_](https://edolstra.github.io/pubs/phd-thesis.pdf#page=101)) and passes that to the hash function.
+    - `nar` (the default):
+      Serialises the input as a
+      [Nix Archive](@docroot@/store/file-system-object/content-address.md#serial-nix-archive)
+      and passes that to the hash function.
 
-    - `flat`: Assumes that the input is a single file and directly passes it to the hash function;
+    - `flat`:
+      Assumes that the input is a single file and
+      [directly passes](@docroot@/store/file-system-object/content-address.md#serial-flat)
+      it to the hash function.
 
     - `text`: Like `flat`, but used for
-      [derivations](@docroot@/glossary.md#store-derivation) serialized in store object and 
+      [derivations](@docroot@/glossary.md#store-derivation) serialized in store object and
       [`builtins.toFile`](@docroot@/language/builtins.html#builtins-toFile).
       For advanced use-cases only;
       for regular usage prefer `nar` and `flat.

src/libexpr/primops.cc

@@ -4515,7 +4515,7 @@ void EvalState::createBaseEnv()
           1683705525
           ```
 
-          The [store path](@docroot@/glossary.md#gloss-store-path) of a derivation depending on `currentTime` will differ for each evaluation, unless both evaluate `builtins.currentTime` in the same second.
+          The [store path](@docroot@/store/store-path.md) of a derivation depending on `currentTime` will differ for each evaluation, unless both evaluate `builtins.currentTime` in the same second.
         )",
         .impureOnly = true,
     });

src/libexpr/primops/fetchTree.cc

@@ -200,8 +200,8 @@ static RegisterPrimOp primop_fetchTree({
     .doc = R"(
       Fetch a file system tree or a plain file using one of the supported backends and return an attribute set with:
 
-      - the resulting fixed-output [store path](@docroot@/glossary.md#gloss-store-path)
-      - the corresponding [NAR](@docroot@/glossary.md#gloss-nar) hash
+      - the resulting fixed-output [store path](@docroot@/store/store-path.md)
+      - the corresponding [NAR](@docroot@/store/file-system-object/content-address.md#serial-nix-archive) hash
       - backend-specific metadata (currently not documented). <!-- TODO: document output attributes -->
 
       *input* must be an attribute set with the following attributes:

src/libstore/globals.hh

@@ -910,7 +910,7 @@ public:
         "substituters",
         R"(
           A list of [URLs of Nix stores](@docroot@/store/types/index.md#store-url-format) to be used as substituters, separated by whitespace.
-          A substituter is an additional [store](@docroot@/glossary.md#gloss-store) from which Nix can obtain [store objects](@docroot@/glossary.md#gloss-store-object) instead of building them.
+          A substituter is an additional [store](@docroot@/glossary.md#gloss-store) from which Nix can obtain [store objects](@docroot@/store/store-object.md) instead of building them.
 
           Substituters are tried based on their priority value, which each substituter can set independently.
           Lower value means higher priority.

src/libstore/path.hh

@@ -13,7 +13,7 @@ struct Hash;
  * \ref StorePath "Store path" is the fundamental reference type of Nix.
  * A store paths refers to a Store object.
  *
- * See glossary.html#gloss-store-path for more information on a
+ * See store/store-path.html for more information on a
  * conceptual level.
  */
 class StorePath

src/libutil/file-content-address.hh

@@ -12,16 +12,28 @@ struct SourcePath;
 /**
  * An enumeration of the ways we can serialize file system
  * objects.
+ *
+ * See `file-system-object/content-address.md#serial` in the manual for
+ * a user-facing description of this concept, but note that this type is also
+ * used for storing or sending copies; not just for addressing.
+ * Note also that there are other content addressing methods that don't
+ * correspond to a serialisation method.
  */
 enum struct FileSerialisationMethod : uint8_t {
     /**
      * Flat-file. The contents of a single file exactly.
+     *
+     * See `file-system-object/content-address.md#serial-flat` in the
+     * manual.
      */
     Flat,
 
     /**
      * Nix Archive. Serializes the file-system object in
      * Nix Archive format.
+     *
+     * See `file-system-object/content-address.md#serial-nix-archive` in
+     * the manual.
      */
     Recursive,
 };
@@ -81,33 +93,32 @@ HashResult hashPath(
 /**
  * An enumeration of the ways we can ingest file system
  * objects, producing a hash or digest.
+ *
+ * See `file-system-object/content-address.md` in the manual for a
+ * user-facing description of this concept.
  */
 enum struct FileIngestionMethod : uint8_t {
     /**
      * Hash `FileSerialisationMethod::Flat` serialisation.
+     *
+     * See `file-system-object/content-address.md#serial-flat` in the
+     * manual.
      */
     Flat,
 
     /**
-     * Hash `FileSerialisationMethod::Git` serialisation.
+     * Hash `FileSerialisationMethod::Recursive` serialisation.
+     *
+     * See `file-system-object/content-address.md#serial-flat` in the
+     * manual.
      */
     Recursive,
 
     /**
-     * Git hashing. In particular files are hashed as git "blobs", and
-     * directories are hashed as git "trees".
+     * Git hashing.
      *
-     * Unlike `Flat` and `Recursive`, this is not a hash of a single
-     * serialisation but a [Merkle
-     * DAG](https://en.wikipedia.org/wiki/Merkle_tree) of multiple
-     * rounds of serialisation and hashing.
-     *
-     * @note Git's data model is slightly different, in that a plain
-     * file doesn't have an executable bit, directory entries do
-     * instead. We decide treat a bare file as non-executable by fiat,
-     * as we do with `FileIngestionMethod::Flat` which also lacks this
-     * information. Thus, Git can encode some but all of Nix's "File
-     * System Objects", and this sort of hashing is likewise partial.
+     * See `file-system-object/content-address.md#serial-git` in the
+     * manual.
      */
     Git,
 };

src/nix/derivation-show.md

@@ -50,7 +50,7 @@ By default, this command only shows top-level derivations, but with
 
 `nix derivation show` outputs a JSON map of [store path]s to derivations in the following format:
 
-[store path]: @docroot@/glossary.md#gloss-store-path
+[store path]: @docroot@/store/store-path.md
 
 {{#include ../../protocols/json/derivation.md}}
 

src/nix/unix/daemon.cc

@@ -58,7 +58,7 @@ struct AuthorizationSettings : Config {
         this, {"root"}, "trusted-users",
         R"(
           A list of user names, separated by whitespace.
-          These users will have additional rights when connecting to the Nix daemon, such as the ability to specify additional [substituters](#conf-substituters), or to import unsigned [NARs](@docroot@/glossary.md#gloss-nar).
+          These users will have additional rights when connecting to the Nix daemon, such as the ability to specify additional [substituters](#conf-substituters), or to import unsigned realisations or unsigned input-addressed store objects.
 
           You can also specify groups by prefixing names with `@`.
           For instance, `@wheel` means all users in the `wheel` group.