Document store object content addressing & improve JSON format

The JSON format no longer uses the legacy ATerm `r:` prefixing nonsese,
but separate fields.

Progress on #9866

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>

src/libcmd/misc-store-flags.cc

@@ -103,27 +103,27 @@ 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):
+    - [`nar`](@docroot@/store/store-object/content-address.md#method-nix-archive)
+      (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`:
+    - [`flat`](@docroot@/store/store-object/content-address.md#method-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
+    - [`text`](@docroot@/store/store-object/content-address.md#method-text):
+      Like `flat`, but used for
       [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.
+      for regular usage prefer `nar` and `flat`.
         )",
         .labels = {"content-address-method"},
         .handler = {[method](std::string s) {

src/libstore/derivations.cc

@@ -1216,16 +1216,19 @@ nlohmann::json DerivationOutput::toJSON(
         },
         [&](const DerivationOutput::CAFixed & dof) {
             res["path"] = store.printStorePath(dof.path(store, drvName, outputName));
-            res["hashAlgo"] = dof.ca.printMethodAlgo();
+            res["method"] = std::string { dof.ca.method.render() };
+            res["hashAlgo"] = printHashAlgo(dof.ca.hash.algo);
             res["hash"] = dof.ca.hash.to_string(HashFormat::Base16, false);
             // FIXME print refs?
         },
         [&](const DerivationOutput::CAFloating & dof) {
-            res["hashAlgo"] = std::string { dof.method.renderPrefix() } + printHashAlgo(dof.hashAlgo);
+            res["method"] = std::string { dof.method.render() };
+            res["hashAlgo"] = printHashAlgo(dof.hashAlgo);
         },
         [&](const DerivationOutput::Deferred &) {},
         [&](const DerivationOutput::Impure & doi) {
-            res["hashAlgo"] = std::string { doi.method.renderPrefix() } + printHashAlgo(doi.hashAlgo);
+            res["method"] = std::string { doi.method.render() };
+            res["hashAlgo"] = printHashAlgo(doi.hashAlgo);
             res["impure"] = true;
         },
     }, raw);
@@ -1245,12 +1248,13 @@ DerivationOutput DerivationOutput::fromJSON(
         keys.insert(key);
 
     auto methodAlgo = [&]() -> std::pair<ContentAddressMethod, HashAlgorithm> {
-        auto & str = getString(valueAt(json, "hashAlgo"));
-        std::string_view s = str;
-        ContentAddressMethod method = ContentAddressMethod::parsePrefix(s);
+        auto & method_ = getString(valueAt(json, "method"));
+        ContentAddressMethod method = ContentAddressMethod::parse(method_);
         if (method == TextIngestionMethod {})
             xpSettings.require(Xp::DynamicDerivations);
-        auto hashAlgo = parseHashAlgo(s);
+
+        auto & hashAlgo_ = getString(valueAt(json, "hashAlgo"));
+        auto hashAlgo = parseHashAlgo(hashAlgo_);
         return { std::move(method), std::move(hashAlgo) };
     };
 
@@ -1260,7 +1264,7 @@ DerivationOutput DerivationOutput::fromJSON(
         };
     }
 
-    else if (keys == (std::set<std::string_view> { "path", "hashAlgo", "hash" })) {
+    else if (keys == (std::set<std::string_view> { "path", "method", "hashAlgo", "hash" })) {
         auto [method, hashAlgo] = methodAlgo();
         auto dof = DerivationOutput::CAFixed {
             .ca = ContentAddress {
@@ -1273,7 +1277,7 @@ DerivationOutput DerivationOutput::fromJSON(
         return dof;
     }
 
-    else if (keys == (std::set<std::string_view> { "hashAlgo" })) {
+    else if (keys == (std::set<std::string_view> { "method", "hashAlgo" })) {
         xpSettings.require(Xp::CaDerivations);
         auto [method, hashAlgo] = methodAlgo();
         return DerivationOutput::CAFloating {
@@ -1286,7 +1290,7 @@ DerivationOutput DerivationOutput::fromJSON(
         return DerivationOutput::Deferred {};
     }
 
-    else if (keys == (std::set<std::string_view> { "hashAlgo", "impure" })) {
+    else if (keys == (std::set<std::string_view> { "method", "hashAlgo", "impure" })) {
         xpSettings.require(Xp::ImpureDerivations);
         auto [method, hashAlgo] = methodAlgo();
         return DerivationOutput::Impure {

src/nix/flake.md

@@ -134,7 +134,9 @@ The following generic flake reference attributes are supported:
   repository or tarball. The default is the root directory of the
   flake.
 
-* `narHash`: The hash of the NAR serialisation (in SRI format) of the
+* `narHash`: The hash of the
+  [Nix Archive (NAR) serialisation][Nix Archive]
+  (in SRI format) of the
   contents of the flake. This is useful for flake types such as
   tarballs that lack a unique content identifier such as a Git commit
   hash.
@@ -423,8 +425,9 @@ The following attributes are supported in `flake.nix`:
   * `lastModified`: The commit time of the revision `rev` as an integer
     denoting the number of seconds since 1970.
 
-  * `narHash`: The SHA-256 (in SRI format) of the NAR serialization of
-    the flake's source tree.
+  * `narHash`: The SHA-256 (in SRI format) of the
+    [Nix Archive (NAR) serialisation][Nix Archive]
+    NAR serialization of the flake's source tree.
 
   The value returned by the `outputs` function must be an attribute
   set. The attributes can have arbitrary values; however, various
@@ -703,4 +706,5 @@ will not look at the lock files of dependencies. However, lock file
 generation itself *does* use the lock files of dependencies by
 default.
 
+[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
 )""

src/nix/nar-cat.md

@@ -2,7 +2,7 @@ R""(
 
 # Examples
 
-* List a file in a NAR and pipe it through `gunzip`:
+* List a file in a [Nix Archive (NAR)][Nix Archive] and pipe it through `gunzip`:
 
   ```console
   # nix nar cat ./hello.nar /share/man/man1/hello.1.gz | gunzip
@@ -16,4 +16,5 @@ R""(
 This command prints on standard output the contents of the regular
 file *path* inside the NAR file *nar*.
 
+[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
 )""

src/nix/nar-dump-path.md

@@ -2,7 +2,7 @@ R""(
 
 # Examples
 
-* To serialise directory `foo` as a NAR:
+* To serialise directory `foo` as a [Nix Archive (NAR)][Nix Archive]:
 
   ```console
   # nix nar pack ./foo > foo.nar
@@ -10,8 +10,10 @@ R""(
 
 # Description
 
-This command generates a NAR file containing the serialisation of
+This command generates a [Nix Archive (NAR)][Nix Archive] file containing the serialisation of
 *path*, which must contain only regular files, directories and
 symbolic links. The NAR is written to standard output.
 
+[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
+
 )""

src/nix/nar-ls.md

@@ -2,7 +2,7 @@ R""(
 
 # Examples
 
-* To list a specific file in a NAR:
+* To list a specific file in a [NAR][Nix Archive]:
 
   ```console
   # nix nar ls --long ./hello.nar /bin/hello
@@ -19,6 +19,8 @@ R""(
 
 # Description
 
-This command shows information about a *path* inside NAR file *nar*.
+This command shows information about a *path* inside [Nix Archive (NAR)][Nix Archive] file *nar*.
+
+[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
 
 )""

src/nix/nar.md

@@ -3,11 +3,14 @@ R""(
 # Description
 
 `nix nar` provides several subcommands for creating and inspecting
-*Nix Archives* (NARs).
+[*Nix Archives* (NARs)][Nix Archive].
 
 # File format
 
-For the definition of the NAR file format, see Figure 5.2 in
-https://edolstra.github.io/pubs/phd-thesis.pdf.
+For the definition of the Nix Archive file format, see
+[within the protocols chapter](@docroot@/protocols/nix-archive.md)
+of the manual.
+
+[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
 
 )""

src/nix/store-dump-path.md

@@ -17,7 +17,9 @@ R""(
 
 # Description
 
-This command generates a NAR file containing the serialisation of the
+This command generates a [Nix Archive (NAR)][Nix Archive] file containing the serialisation of the
 store path [*installable*](./nix.md#installables). The NAR is written to standard output.
 
+[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
+
 )""

src/nix/verify.md

@@ -46,4 +46,6 @@ The exit status of this command is the sum of the following values:
 * **4** if any path couldn't be verified for any other reason (such as
   an I/O error).
 
+[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
+
 )""