Merge remote-tracking branch 'upstream/master' into auto-uid-allocation

5 files changed, 69 insertions, 52 deletions

diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md
index 31ebadda1..5b208df67 100644
--- a/doc/manual/src/expressions/advanced-attributes.md
+++ b/doc/manual/src/expressions/advanced-attributes.md
@@ -2,14 +2,14 @@
 
 Derivations can declare some infrequently used optional attributes.
 
-  - `allowedReferences`  
+  - `allowedReferences`\
     The optional attribute `allowedReferences` specifies a list of legal
     references (dependencies) of the output of the builder. For example,
-    
+
     ```nix
     allowedReferences = [];
     ```
-    
+
     enforces that the output of a derivation cannot have any runtime
     dependencies on its inputs. To allow an output to have a runtime
     dependency on itself, use `"out"` as a list item. This is used in
@@ -17,45 +17,45 @@ Derivations can declare some infrequently used optional attributes.
     booting Linux don’t have accidental dependencies on other paths in
     the Nix store.
 
-  - `allowedRequisites`  
+  - `allowedRequisites`\
     This attribute is similar to `allowedReferences`, but it specifies
     the legal requisites of the whole closure, so all the dependencies
     recursively. For example,
-    
+
     ```nix
     allowedRequisites = [ foobar ];
     ```
-    
+
     enforces that the output of a derivation cannot have any other
     runtime dependency than `foobar`, and in addition it enforces that
     `foobar` itself doesn't introduce any other dependency itself.
 
-  - `disallowedReferences`  
+  - `disallowedReferences`\
     The optional attribute `disallowedReferences` specifies a list of
     illegal references (dependencies) of the output of the builder. For
     example,
-    
+
     ```nix
     disallowedReferences = [ foo ];
     ```
-    
+
     enforces that the output of a derivation cannot have a direct
     runtime dependencies on the derivation `foo`.
 
-  - `disallowedRequisites`  
+  - `disallowedRequisites`\
     This attribute is similar to `disallowedReferences`, but it
     specifies illegal requisites for the whole closure, so all the
     dependencies recursively. For example,
-    
+
     ```nix
     disallowedRequisites = [ foobar ];
     ```
-    
+
     enforces that the output of a derivation cannot have any runtime
     dependency on `foobar` or any other derivation depending recursively
     on `foobar`.
 
-  - `exportReferencesGraph`  
+  - `exportReferencesGraph`\
     This attribute allows builders access to the references graph of
     their inputs. The attribute is a list of inputs in the Nix store
     whose references graph the builder needs to know. The value of
@@ -65,17 +65,17 @@ Derivations can declare some infrequently used optional attributes.
     files have the format used by `nix-store --register-validity`
     (with the deriver fields left empty). For example, when the
     following derivation is built:
-    
+
     ```nix
     derivation {
       ...
       exportReferencesGraph = [ "libfoo-graph" libfoo ];
     };
     ```
-    
+
     the references graph of `libfoo` is placed in the file
     `libfoo-graph` in the temporary build directory.
-    
+
     `exportReferencesGraph` is useful for builders that want to do
     something with the closure of a store path. Examples include the
     builders in NixOS that generate the initial ramdisk for booting
@@ -84,66 +84,66 @@ Derivations can declare some infrequently used optional attributes.
     with a Nix store containing the closure of a bootable NixOS
     configuration).
 
-  - `impureEnvVars`  
+  - `impureEnvVars`\
     This attribute allows you to specify a list of environment variables
     that should be passed from the environment of the calling user to
     the builder. Usually, the environment is cleared completely when the
     builder is executed, but with this attribute you can allow specific
     environment variables to be passed unmodified. For example,
     `fetchurl` in Nixpkgs has the line
-    
+
     ```nix
     impureEnvVars = [ "http_proxy" "https_proxy" ... ];
     ```
-    
+
     to make it use the proxy server configuration specified by the user
     in the environment variables `http_proxy` and friends.
-    
+
     This attribute is only allowed in *fixed-output derivations* (see
     below), where impurities such as these are okay since (the hash
     of) the output is known in advance. It is ignored for all other
     derivations.
-    
+
     > **Warning**
-    > 
+    >
     > `impureEnvVars` implementation takes environment variables from
     > the current builder process. When a daemon is building its
     > environmental variables are used. Without the daemon, the
     > environmental variables come from the environment of the
     > `nix-build`.
 
-  - `outputHash`; `outputHashAlgo`; `outputHashMode`  
+  - `outputHash`; `outputHashAlgo`; `outputHashMode`\
     These attributes declare that the derivation is a so-called
     *fixed-output derivation*, which means that a cryptographic hash of
     the output is already known in advance. When the build of a
     fixed-output derivation finishes, Nix computes the cryptographic
     hash of the output and compares it to the hash declared with these
     attributes. If there is a mismatch, the build fails.
-    
+
     The rationale for fixed-output derivations is derivations such as
     those produced by the `fetchurl` function. This function downloads a
     file from a given URL. To ensure that the downloaded file has not
     been modified, the caller must also specify a cryptographic hash of
     the file. For example,
-    
+
     ```nix
     fetchurl {
       url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
       sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
     }
     ```
-    
+
     It sometimes happens that the URL of the file changes, e.g., because
     servers are reorganised or no longer available. We then must update
     the call to `fetchurl`, e.g.,
-    
+
     ```nix
     fetchurl {
       url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
       sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
     }
     ```
-    
+
     If a `fetchurl` derivation was treated like a normal derivation, the
     output paths of the derivation and *all derivations depending on it*
     would change. For instance, if we were to change the URL of the
@@ -151,16 +151,16 @@ Derivations can declare some infrequently used optional attributes.
     other packages depend) massive rebuilds would be needed. This is
     unfortunate for a change which we know cannot have a real effect as
     it propagates upwards through the dependency graph.
-    
+
     For fixed-output derivations, on the other hand, the name of the
     output path only depends on the `outputHash*` and `name` attributes,
     while all other attributes are ignored for the purpose of computing
     the output path. (The `name` attribute is included because it is
     part of the path.)
-    
+
     As an example, here is the (simplified) Nix expression for
     `fetchurl`:
-    
+
     ```nix
     { stdenv, curl }: # The curl program is used for downloading.
 
@@ -180,43 +180,51 @@ Derivations can declare some infrequently used optional attributes.
       inherit url;
     }
     ```
-    
+
     The `outputHashAlgo` attribute specifies the hash algorithm used to
     compute the hash. It can currently be `"sha1"`, `"sha256"` or
     `"sha512"`.
-    
+
     The `outputHashMode` attribute determines how the hash is computed.
     It must be one of the following two values:
-    
-      - `"flat"`  
+
+      - `"flat"`\
         The output must be a non-executable regular file. If it isn’t,
         the build fails. The hash is simply computed over the contents
         of that file (so it’s equal to what Unix commands like
         `sha256sum` or `sha1sum` produce).
-        
+
         This is the default.
-    
-      - `"recursive"`  
+
+      - `"recursive"`\
         The hash is computed over the NAR archive dump of the output
         (i.e., the result of [`nix-store
         --dump`](../command-ref/nix-store.md#operation---dump)). In
         this case, the output can be anything, including a directory
         tree.
-    
+
     The `outputHash` attribute, finally, must be a string containing
     the hash in either hexadecimal or base-32 notation. (See the
     [`nix-hash` command](../command-ref/nix-hash.md) for information
     about converting to and from base-32 notation.)
+    
+  - `__contentAddressed`
+    If this **experimental** attribute is set to true, then the derivation
+    outputs will be stored in a content-addressed location rather than the
+    traditional input-addressed one.
+    This only has an effect if the `ca-derivation` experimental feature is enabled.
+    
+    Setting this attribute also requires setting `outputHashMode` and `outputHashAlgo` like for *fixed-output derivations* (see above).
 
-  - `passAsFile`  
+  - `passAsFile`\
     A list of names of attributes that should be passed via files rather
     than environment variables. For example, if you have
-    
+
     ```nix
     passAsFile = ["big"];
     big = "a very long string";
     ```
-    
+
     then when the builder runs, the environment variable `bigPath`
     will contain the absolute path to a temporary file containing `a
     very long string`. That is, for any attribute *x* listed in
@@ -226,7 +234,7 @@ Derivations can declare some infrequently used optional attributes.
     builder, since most operating systems impose a limit on the size
     of the environment (typically, a few hundred kilobyte).
 
-  - `preferLocalBuild`  
+  - `preferLocalBuild`\
     If this attribute is set to `true` and [distributed building is
     enabled](../advanced-topics/distributed-builds.md), then, if
     possible, the derivaton will be built locally instead of forwarded
@@ -234,14 +242,14 @@ Derivations can declare some infrequently used optional attributes.
     where the cost of doing a download or remote build would exceed
     the cost of building locally.
 
-  - `allowSubstitutes`  
+  - `allowSubstitutes`\
     If this attribute is set to `false`, then Nix will always build this
     derivation; it will not try to substitute its outputs. This is
     useful for very trivial derivations (such as `writeText` in Nixpkgs)
     that are cheaper to build than to substitute from a binary cache.
-    
+
     > **Note**
-    > 
+    >
     > You need to have a builder configured which satisfies the
     > derivation’s `system` attribute, since the derivation cannot be
     > substituted. Thus it is usually a good idea to align `system` with
diff --git a/doc/manual/src/expressions/builtin-constants.md b/doc/manual/src/expressions/builtin-constants.md
index 3345a715b..1404289e5 100644
--- a/doc/manual/src/expressions/builtin-constants.md
+++ b/doc/manual/src/expressions/builtin-constants.md
@@ -2,7 +2,7 @@
 
 Here are the constants built into the Nix expression evaluator:
 
-  - `builtins`  
+  - `builtins`\
     The set `builtins` contains all the built-in functions and values.
     You can use `builtins` to test for the availability of features in
     the Nix installation, e.g.,
@@ -14,7 +14,7 @@ Here are the constants built into the Nix expression evaluator:
     This allows a Nix expression to fall back gracefully on older Nix
     installations that don’t have the desired built-in function.
 
-  - `builtins.currentSystem`  
+  - `builtins.currentSystem`\
     The built-in value `currentSystem` evaluates to the Nix platform
     identifier for the Nix installation on which the expression is being
     evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
diff --git a/doc/manual/src/expressions/builtins-prefix.md b/doc/manual/src/expressions/builtins-prefix.md
index 0f7c3d32f..87127de2a 100644
--- a/doc/manual/src/expressions/builtins-prefix.md
+++ b/doc/manual/src/expressions/builtins-prefix.md
@@ -9,7 +9,8 @@ scope. Instead, you can access them through the `builtins` built-in
 value, which is a set that contains all built-in functions and values.
 For instance, `derivation` is also available as `builtins.derivation`.
 
-  - `derivation` *attrs*; `builtins.derivation` *attrs*  
-
-    `derivation` is described in [its own section](derivations.md).
-
+<dl>
+  <dt><code>derivation <var>attrs</var></code>;
+      <code>builtins.derivation <var>attrs</var></code></dt>
+  <dd><p><var>derivation</var> in described in
+         <a href="derivations.md">its own section</a>.</p></dd>
diff --git a/doc/manual/src/expressions/builtins-suffix.md b/doc/manual/src/expressions/builtins-suffix.md
new file mode 100644
index 000000000..a74db2857
--- /dev/null
+++ b/doc/manual/src/expressions/builtins-suffix.md
@@ -0,0 +1 @@
+</dl>
diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
index ce31029cc..28fa23b58 100644
--- a/doc/manual/src/expressions/language-values.md
+++ b/doc/manual/src/expressions/language-values.md
@@ -139,6 +139,13 @@ Nix has the following basic data types:
     environment variable `NIX_PATH` will be searched for the given file
     or directory name.
 
+    Antiquotation is supported in any paths except those in angle brackets.
+    `./${foo}-${bar}.nix` is a more convenient way of writing 
+    `./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
+    least one slash must appear *before* any antiquotations for this to be
+    recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
+    operation. `./a.${foo}/b.${bar}` is a path.
+
   - *Booleans* with values `true` and `false`.
 
   - The null value, denoted as `null`.