Merge remote-tracking branch 'origin/master' into lazy-trees

doc/manual/generate-manpage.nix

@@ -1,11 +1,11 @@
-{ command }:
+{ toplevel }:
 
 with builtins;
 with import <nix/utils.nix>;
 
 let
 
-  showCommand = { command, details, filename }:
+  showCommand = { command, details, filename, toplevel }:
     let
       result = ''
         > **Warning** \
@@ -57,14 +57,15 @@ let
       maybeOptions = if details.flags == {} then "" else ''
         # Options
 
-        ${showOptions details.flags}
+        ${showOptions details.flags toplevel.flags}
       '';
-      showOptions = options:
+      showOptions = options: commonOptions:
         let
+          allOptions = options // commonOptions;
           showCategory = cat: ''
             ${if cat != "" then "**${cat}:**" else ""}
 
-            ${listOptions (filterAttrs (n: v: v.category == cat) options)}
+            ${listOptions (filterAttrs (n: v: v.category == cat) allOptions)}
             '';
           listOptions = opts: concatStringsSep "\n" (attrValues (mapAttrs showOption opts));
           showOption = name: option:
@@ -76,30 +77,33 @@ let
 
                 ${option.description}
             '';
-          categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues options)));
+          categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues allOptions)));
         in concatStrings (map showCategory categories);
     in squash result;
 
   appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
 
-  processCommand = { command, details, filename }:
+  processCommand = { command, details, filename, toplevel }:
     let
       cmd = {
         inherit command;
         name = filename + ".md";
-        value = showCommand { inherit command details filename; };
+        value = showCommand { inherit command details filename toplevel; };
       };
       subcommand = subCmd: processCommand {
         command = command + " " + subCmd;
         details = details.commands.${subCmd};
         filename = appendName filename subCmd;
+        inherit toplevel;
       };
     in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
 
+  parsedToplevel = builtins.fromJSON toplevel;
   manpages = processCommand {
     command = "nix";
-    details = builtins.fromJSON command;
+    details = parsedToplevel;
     filename = "nix";
+    toplevel = parsedToplevel;
   };
 
   tableOfContents = let

doc/manual/generate-options.nix

@@ -11,16 +11,16 @@ concatStrings (map
     + concatStrings (map (s: "    ${s}\n") (splitLines option.description)) + "\n\n"
     + (if option.documentDefault
        then "    **Default:** " + (
-       if option.value == "" || option.value == []
+       if option.defaultValue == "" || option.defaultValue == []
        then "*empty*"
-       else if isBool option.value
-       then (if option.value then "`true`" else "`false`")
+       else if isBool option.defaultValue
+       then (if option.defaultValue then "`true`" else "`false`")
        else
          # n.b. a StringMap value type is specified as a string, but
          # this shows the value type.  The empty stringmap is "null" in
          # JSON, but that converts to "{ }" here.
-         (if isAttrs option.value then "`\"\"`"
-          else "`" + toString option.value + "`")) + "\n\n"
+         (if isAttrs option.defaultValue then "`\"\"`"
+          else "`" + toString option.defaultValue + "`")) + "\n\n"
        else "    **Default:** *machine-specific*\n")
     + (if option.aliases != []
        then "    **Deprecated alias:** " + (concatStringsSep ", " (map (s: "`${s}`") option.aliases)) + "\n\n"

doc/manual/local.mk

@@ -50,7 +50,7 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
 
 $(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix
 	@rm -rf $@
-	$(trace-gen) $(nix-eval) --write-to $@ --expr 'import doc/manual/generate-manpage.nix { command = builtins.readFile $<; }'
+	$(trace-gen) $(nix-eval) --write-to $@ --expr 'import doc/manual/generate-manpage.nix { toplevel = builtins.readFile $<; }'
 
 $(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/generate-options.nix $(d)/src/command-ref/conf-file-prefix.md $(bindir)/nix
 	@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp

doc/manual/src/language/values.md

@@ -150,6 +150,20 @@
   recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
   operation. `./a.${foo}/b.${bar}` is a path.
 
+  When a path appears in an antiquotation, and is thus coerced into a string,
+  the path is first copied into the Nix store and the resulting string is
+  the Nix store path. For instance `"${./foo.txt}" will cause `foo.txt` in
+  the current directory to be copied into the Nix store and result in the
+  string `"/nix/store/<HASH>-foo.txt"`.
+
+  Note that the Nix language assumes that all input files will remain
+  _unchanged_ during the course of the Nix expression evaluation.
+  If you for example antiquote a file path during a `nix repl` session, and
+  then later in the same session, after having changed the file contents,
+  evaluate the antiquotation with the file path again, then Nix will still
+  return the first store path. It will _not_ reread the file contents to
+  produce a different Nix store path.
+
 - <a id="type-boolean" href="#type-boolean">Boolean</a>
 
   *Booleans* with values `true` and `false`.