public/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
docs: Link to Definition
This commit is contained in:
Graham Christensen 2018-10-05 13:13:15 -04:00 committed by GitHub
commit b4755393cc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 146 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/.gitignore vendored
View File

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

8
doc/Makefile
View File

@ -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 \

5
doc/default.nix
View File

@ -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
'';

4
doc/functions/library/asserts.xml
View File

@ -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>.

32
doc/functions/library/attrsets.xml
View File

@ -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

85
doc/lib-function-locations.nix Normal file
View File

@ -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>
''

2
doc/shell.nix
View File

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

10
lib/trivial.nix
View File

@ -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.

5
nixos/modules/misc/version.nix
View File

@ -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
else if pathExists revisionFile then fileContents revisionFile
else "master";
default = lib.trivial.revisionWithDefault "master";
description = "The Git revision from which this NixOS configuration was built.";
};

4
pkgs/top-level/release.nix
View File

@ -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