Merge pull request #8318 from fricklerhandwerk/doc-currentTime

document `builtins.currentTime`

doc/manual/src/language/builtin-constants.md

@@ -17,3 +17,27 @@ These constants are built into the Nix language evaluator:
   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"`.
+
+  Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
+
+- [`builtins.currentTime`]{#builtins-currentTime} (integer)
+
+  Return the [Unix time](https://en.wikipedia.org/wiki/Unix_time) at first evaluation.
+  Repeated references to that name will re-use the initially obtained value.
+
+  Example:
+
+  ```console
+  $ nix repl
+  Welcome to Nix 2.15.1 Type :? for help.
+
+  nix-repl> builtins.currentTime
+  1683705525
+
+  nix-repl> builtins.currentTime
+  1683705525
+  ```
+
+  The [store path](@docroot@/glossary.md#gloss-store-path) of a derivation depending on `currentTime` will differ for each evaluation.
+
+  Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).

src/libexpr/eval.hh

@@ -745,7 +745,13 @@ struct EvalSettings : Config
         )"};
 
     Setting<bool> pureEval{this, false, "pure-eval",
-        "Whether to restrict file system and network access to files specified by cryptographic hash."};
+        R"(
+          Pure evaluation mode ensures that the result of Nix expressions is fully determined by explicitly declared inputs, and not influenced by external state:
+
+          - Restrict file system and network access to files specified by cryptographic hash
+          - Disable [`bultins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem) and [`builtins.currentTime`](@docroot@/language/builtin-constants.md#builtins-currentTime)
+        )"
+        };
 
     Setting<bool> enableImportFromDerivation{
         this, true, "allow-import-from-derivation",

src/libexpr/primops.cc

@@ -1501,7 +1501,7 @@ static RegisterPrimOp primop_storePath({
       causes the path to be *copied* again to the Nix store, resulting
       in a new path (e.g. `/nix/store/ld01dnzc…-source-source`).
 
-      This function is not available in pure evaluation mode.
+      Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
     )",
     .fun = prim_storePath,
 });

src/libexpr/primops/fetchTree.cc

@@ -286,9 +286,9 @@ static RegisterPrimOp primop_fetchurl({
     .name = "__fetchurl",
     .args = {"url"},
     .doc = R"(
-      Download the specified URL and return the path of the downloaded
+      Download the specified URL and return the path of the downloaded file.
-      file. This function is not available if [restricted evaluation
+
-      mode](../command-ref/conf-file.md) is enabled.
+      Not available in [restricted evaluation mode](@docroot@/command-ref/conf-file.md#conf-restrict-eval).
     )",
     .fun = prim_fetchurl,
 });
@@ -338,8 +338,7 @@ static RegisterPrimOp primop_fetchTarball({
       stdenv.mkDerivation { … }
       ```
 
-      This function is not available if [restricted evaluation
+      Not available in [restricted evaluation mode](@docroot@/command-ref/conf-file.md#conf-restrict-eval).
-      mode](../command-ref/conf-file.md) is enabled.
     )",
     .fun = prim_fetchTarball,
 });
@@ -470,14 +469,9 @@ static RegisterPrimOp primop_fetchGit({
           }
           ```
 
-          > **Note**
+          Nix will refetch the branch according to the [`tarball-ttl`](@docroot@/command-ref/conf-file.md#conf-tarball-ttl) setting.
-          >
-          > Nix will refetch the branch in accordance with
-          > the option `tarball-ttl`.
 
-          > **Note**
+          This behavior is disabled in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
-          >
-          > This behavior is disabled in *Pure evaluation mode*.
 
         - To fetch the content of a checked-out work directory:
 

src/libutil/experimental-features.cc

@@ -50,6 +50,8 @@ constexpr std::array<ExperimentalFeatureDetails, 13> xpFeatureDetails = {{
             or other impure derivations can rely on impure derivations. Finally,
             an impure derivation cannot also be
             [content-addressed](#xp-feature-ca-derivations).
+
+            This is a more explicit alternative to using [`builtins.currentTime`](@docroot@/language/builtin-constants.md#builtins-currentTime).
         )",
     },
     {