Merge pull request #47920 from grahamc/link-to-definition

docs: Link to Definition

doc/.gitignore

@@ -4,3 +4,4 @@
 out
 manual-full.xml
 highlightjs
+functions/library/locations.xml

doc/Makefile

@@ -19,7 +19,7 @@ fix-misc-xml:
 
 .PHONY: clean
 clean:
-	rm -f ${MD_TARGETS} .version manual-full.xml
+	rm -f ${MD_TARGETS} .version manual-full.xml functions/library/locations.xml
 	rm -rf ./out/ ./highlightjs
 
 .PHONY: validate
@@ -69,13 +69,17 @@ highlightjs:
 	cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/
 
 
-manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml **/**/*.xml
+manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml *.xml **/*.xml **/**/*.xml
 	xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
 
 .version:
 	nix-instantiate --eval \
 		-E '(import ../lib).version' > .version
 
+functions/library/locations.xml:
+	nix-build ./lib-function-locations.nix \
+		--out-link ./functions/library/locations.xml
+
 %.section.xml: %.section.md
 	pandoc $^ -w docbook+smart \
 		-f markdown+smart \

doc/default.nix

@@ -1,6 +1,7 @@
+{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
 let
-  pkgs = import ./.. { };
   lib = pkgs.lib;
+  locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; };
 in
 pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
@@ -29,6 +30,8 @@ pkgs.stdenv.mkDerivation {
   ];
 
   postPatch = ''
+    rm -rf ./functions/library/locations.xml
+    ln -s ${locationsXml} ./functions/library/locations.xml
     echo ${lib.version} > .version
   '';
 

doc/functions/library/asserts.xml

@@ -10,6 +10,8 @@
   <subtitle><literal>assertMsg :: Bool -> String -> Bool</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" />
+
   <para>
    Print a trace message if <literal>pred</literal> is false.
   </para>
@@ -59,6 +61,8 @@ stderr> assert failed
       StringList -> Bool</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" />
+
   <para>
    Specialized <function>asserts.assertMsg</function> for checking if
    <varname>val</varname> is one of the elements of <varname>xs</varname>.

doc/functions/library/attrsets.xml

@@ -10,6 +10,8 @@
   <subtitle><literal>attrByPath :: [String] -> Any -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.attrByPath" />
+
   <para>
    Return an attribute from within nested attribute sets.
   </para>
@@ -73,6 +75,8 @@ lib.attrsets.attrByPath [ "a" "b" ] 0 {}
   <subtitle><literal>hasAttrByPath :: [String] -> AttrSet -> Bool</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.hasAttrByPath" />
+
   <para>
    Determine if an attribute exists within a nested attribute set.
   </para>
@@ -118,6 +122,8 @@ lib.attrsets.hasAttrByPath
   <subtitle><literal>setAttrByPath :: [String] -> Any -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.setAttrByPath" />
+
   <para>
    Create a new attribute set with <varname>value</varname> set at the nested
    attribute location specified in <varname>attrPath</varname>.
@@ -162,6 +168,8 @@ lib.attrsets.setAttrByPath [ "a" "b" ] 3
   <subtitle><literal>getAttrFromPath :: [String] -> AttrSet -> Value</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.getAttrFromPath" />
+
   <para>
    Like <xref linkend="function-library-lib.attrsets.attrByPath" /> except
    without a default, and it will throw if the value doesn't exist.
@@ -214,6 +222,8 @@ lib.attrsets.getAttrFromPath [ "x" "y" ] { }
   <subtitle><literal>attrVals :: [String] -> AttrSet -> [Any]</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.attrVals" />
+
   <para>
    Return the specified attributes from a set. All values must exist.
   </para>
@@ -265,6 +275,8 @@ error: attribute 'd' missing
   <subtitle><literal>attrValues :: AttrSet -> [Any]</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.attrValues" />
+
   <para>
    Get all the attribute values from an attribute set.
   </para>
@@ -302,6 +314,8 @@ lib.attrsets.attrValues { a = 1; b = 2; c = 3; }
   <subtitle><literal>catAttrs :: String -> AttrSet -> [Any]</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.catAttrs" />
+
   <para>
    Collect each attribute named `attr' from the list of attribute sets,
    <varname>sets</varname>. Sets that don't contain the named attribute are
@@ -355,6 +369,8 @@ catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
   <subtitle><literal>filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrs" />
+
   <para>
    Filter an attribute set by removing all attributes for which the given
    predicate return false.
@@ -428,6 +444,8 @@ filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; }
   <subtitle><literal>filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrsRecursive" />
+
   <para>
    Filter an attribute set recursively by removing all attributes for which the
    given predicate return false.
@@ -523,6 +541,8 @@ lib.attrsets.filterAttrsRecursive
   <subtitle><literal>foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.foldAttrs" />
+
   <para>
    Apply fold function to values grouped by key.
   </para>
@@ -609,6 +629,8 @@ lib.attrsets.foldAttrs
   <subtitle><literal>collect :: (Any -> Bool) -> AttrSet -> [Any]</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.collect" />
+
   <para>
    Recursively collect sets that verify a given predicate named
    <varname>pred</varname> from the set <varname>attrs</varname>. The recursion
@@ -677,6 +699,8 @@ collect (x: x ? outPath)
   <subtitle><literal>nameValuePair :: String -> Any -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.nameValuePair" />
+
   <para>
    Utility function that creates a <literal>{name, value}</literal> pair as
    expected by <function>builtins.listToAttrs</function>.
@@ -720,6 +744,8 @@ nameValuePair "some" 6
   <subtitle><literal></literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs" />
+
   <para>
    Apply a function to each element in an attribute set, creating a new
    attribute set.
@@ -785,6 +811,8 @@ lib.attrsets.mapAttrs
   <subtitle><literal>mapAttrs' :: (String -> Any -> { name = String; value = Any }) -> AttrSet -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs-prime" />
+
   <para>
    Like <function>mapAttrs</function>, but allows the name of each attribute to
    be changed in addition to the value. The applied function should return both
@@ -860,6 +888,8 @@ lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name)
    AttrSet -> Any</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsToList" />
+
   <para>
    Call <varname>fn</varname> for each attribute in the given
    <varname>set</varname> and return the result in a list.
@@ -929,6 +959,8 @@ lib.attrsets.mapAttrsToList (name: value: "${name}=${value}")
   <subtitle><literal>mapAttrsRecursive :: ([String] > Any -> Any) -> AttrSet -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsRecursive" />
+
   <para>
    Like <function>mapAttrs</function>, except that it recursively applies
    itself to attribute sets. Also, the first argument of the argument function

doc/lib-function-locations.nix

@@ -0,0 +1,85 @@
+{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
+let
+  revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master");
+
+  libDefPos = set:
+    builtins.map
+      (name: {
+        name = name;
+        location = builtins.unsafeGetAttrPos name set;
+      })
+      (builtins.attrNames set);
+
+  libset = toplib:
+    builtins.map
+      (subsetname: {
+        subsetname = subsetname;
+        functions = libDefPos toplib."${subsetname}";
+      })
+      (builtins.filter
+        (name: builtins.isAttrs toplib."${name}")
+        (builtins.attrNames toplib));
+
+  nixpkgsLib = pkgs.lib;
+
+  flattenedLibSubset = { subsetname, functions }:
+  builtins.map
+    (fn: {
+      name = "lib.${subsetname}.${fn.name}";
+      value = fn.location;
+    })
+    functions;
+
+  locatedlibsets = libs: builtins.map flattenedLibSubset (libset libs);
+  removeFilenamePrefix = prefix: filename:
+    let
+    prefixLen = (builtins.stringLength prefix) + 1; # +1 to remove the leading /
+      filenameLen = builtins.stringLength filename;
+      substr = builtins.substring prefixLen filenameLen filename;
+      in substr;
+
+  removeNixpkgs = removeFilenamePrefix (builtins.toString pkgs.path);
+
+  liblocations =
+    builtins.filter
+      (elem: elem.value != null)
+      (nixpkgsLib.lists.flatten
+        (locatedlibsets nixpkgsLib));
+
+  fnLocationRelative = { name, value }:
+    {
+      inherit name;
+      value = value // { file = removeNixpkgs value.file; };
+    };
+
+  relativeLocs = (builtins.map fnLocationRelative liblocations);
+  sanitizeId = builtins.replaceStrings
+    [ "'"      ]
+    [ "-prime" ];
+
+  urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}";
+  xmlstrings = (nixpkgsLib.strings.concatMapStrings
+      ({ name, value }:
+      ''
+      <section><title>${name}</title>
+        <para xml:id="${sanitizeId name}">
+        Located at
+        <link
+          xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link>
+        in  <literal>&lt;nixpkgs&gt;</literal>.
+        </para>
+        </section>
+      '')
+      relativeLocs);
+
+in pkgs.writeText
+    "locations.xml"
+    ''
+    <section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         version="5">
+         <title>All the locations for every lib function</title>
+         <para>This file is only for inclusion by other files.</para>
+         ${xmlstrings}
+    </section>
+    ''

doc/shell.nix

@@ -1,5 +1,5 @@
 { pkgs ? import ../. {} }:
-(import ./default.nix).overrideAttrs (x: {
+(import ./default.nix {}).overrideAttrs (x: {
   buildInputs = x.buildInputs ++ [ pkgs.xmloscopy pkgs.ruby ];
 
 })

lib/trivial.nix

@@ -105,6 +105,16 @@ rec {
     then lib.strings.fileContents suffixFile
     else "pre-git";
 
+  # Attempt to get the revision nixpkgs is from
+  revisionWithDefault = default:
+    let
+      revisionFile = "${toString ./..}/.git-revision";
+      gitRepo      = "${toString ./..}/.git";
+    in if lib.pathIsDirectory gitRepo
+       then lib.commitIdFromGitRepo gitRepo
+       else if lib.pathExists revisionFile then lib.fileContents revisionFile
+       else default;
+
   nixpkgsVersion = builtins.trace "`lib.nixpkgsVersion` is deprecated, use `lib.version` instead!" version;
 
   # Whether we're being called by nix-shell.

nixos/modules/misc/version.nix

@@ -5,7 +5,6 @@ with lib;
 let
   cfg = config.system.nixos;
 
-  revisionFile = "${toString pkgs.path}/.git-revision";
   gitRepo      = "${toString pkgs.path}/.git";
   gitCommitId  = lib.substring 0 7 (commitIdFromGitRepo gitRepo);
 in
@@ -37,9 +36,7 @@ in
     nixos.revision = mkOption {
       internal = true;
       type = types.str;
-      default = if pathIsDirectory gitRepo then commitIdFromGitRepo gitRepo
+      default = lib.trivial.revisionWithDefault "master";
-                else if pathExists revisionFile then fileContents revisionFile
-                else "master";
       description = "The Git revision from which this NixOS configuration was built.";
     };
 

pkgs/top-level/release.nix

@@ -8,7 +8,7 @@
 
    $ nix-build pkgs/top-level/release.nix -A coreutils.x86_64-linux
 */
-{ nixpkgs ? { outPath = (import ../../lib).cleanSource ../..; revCount = 1234; shortRev = "abcdef"; }
+{ nixpkgs ? { outPath = (import ../../lib).cleanSource ../..; revCount = 1234; shortRev = "abcdef"; revision = "0000000000000000000000000000000000000000"; }
 , officialRelease ? false
   # The platforms for which we build Nixpkgs.
 , supportedSystems ? [ "x86_64-linux" "x86_64-darwin" "aarch64-linux" ]
@@ -32,7 +32,7 @@ let
 
       metrics = import ./metrics.nix { inherit pkgs nixpkgs; };
 
-      manual = import ../../doc;
+      manual = import ../../doc { inherit pkgs nixpkgs; };
       lib-tests = import ../../lib/tests/release.nix { inherit pkgs; };
 
       darwin-tested = if supportDarwin then pkgs.releaseTools.aggregate