diff --git a/doc/Makefile b/doc/Makefile
index 173e1c0b19ee..65a37eb05a3a 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -69,7 +69,7 @@ highlightjs:
cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/
-manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml
+manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml **/**/*.xml
xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
.version:
diff --git a/doc/functions.xml b/doc/functions.xml
index 88011061ae6e..4193bb49f77a 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -7,7 +7,7 @@
The nixpkgs repository has several utility functions to manipulate Nix
expressions.
-
+
diff --git a/doc/functions/library.xml b/doc/functions/library.xml
new file mode 100644
index 000000000000..901423c52a18
--- /dev/null
+++ b/doc/functions/library.xml
@@ -0,0 +1,15 @@
+
+ Nixpkgs Library Functions
+
+
+ Nixpkgs provides a standard library at pkgs.lib, or
+ through import <nixpkgs/lib>.
+
+
+
+
+
+
diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml
new file mode 100644
index 000000000000..1f42078c8cf3
--- /dev/null
+++ b/doc/functions/library/asserts.xml
@@ -0,0 +1,113 @@
+
+ Assert functions
+
+
+ <function>lib.asserts.assertMsg</function>
+
+ assertMsg :: Bool -> String -> Bool
+
+
+
+ Print a trace message if pred is false.
+
+
+
+ Intended to be used to augment asserts with helpful error messages.
+
+
+
+
+
+ pred
+
+
+
+ Condition under which the msg should
+ not be printed.
+
+
+
+
+
+ msg
+
+
+
+ Message to print.
+
+
+
+
+
+
+ Printing when the predicate is false
+ trace: foo is not bar, silly
+stderr> assert failed
+]]>
+
+
+
+
+ <function>lib.asserts.assertOneOf</function>
+
+ assertOneOf :: String -> String ->
+ StringList -> Bool
+
+
+
+ Specialized asserts.assertMsg for checking if
+ val is one of the elements of xs.
+ Useful for checking enums.
+
+
+
+
+
+ name
+
+
+
+ The name of the variable the user entered val into,
+ for inclusion in the error message.
+
+
+
+
+
+ val
+
+
+
+ The value of what the user provided, to be compared against the values in
+ xs.
+
+
+
+
+
+ xs
+
+
+
+ The list of valid values.
+
+
+
+
+
+
+ Ensuring a user provided a possible value
+ false
+stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
+ ]]>
+
+
+
diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml
new file mode 100644
index 000000000000..7ad3f949a024
--- /dev/null
+++ b/doc/functions/library/attrsets.xml
@@ -0,0 +1,938 @@
+
+ Attribute-Set Functions
+
+
+ <function>lib.attrset.attrByPath</function>
+
+ attrByPath :: [String] -> Any -> AttrSet
+
+
+
+ Return an attribute from within nested attribute sets.
+
+
+
+
+
+ attrPath
+
+
+
+ A list of strings representing the path through the nested attribute set
+ set.
+
+
+
+
+
+ default
+
+
+
+ Default value if attrPath does not resolve to an
+ existing value.
+
+
+
+
+
+ set
+
+
+
+ The nested attributeset to select values from.
+
+
+
+
+
+
+ Extracting a value from a nested attribute set
+ 3
+]]>
+
+
+
+ No value at the path, instead using the default
+ 0
+]]>
+
+
+
+
+ <function>lib.attrsets.hasAttrByPath</function>
+
+ hasAttrByPath :: [String] -> AttrSet -> Bool
+
+
+
+ Determine if an attribute exists within a nested attribute set.
+
+
+
+
+
+ attrPath
+
+
+
+ A list of strings representing the path through the nested attribute set
+ set.
+
+
+
+
+
+ set
+
+
+
+ The nested attributeset to check.
+
+
+
+
+
+
+ A nested value does exist inside a set
+ true
+]]>
+
+
+
+
+ <function>lib.attrsets.setAttrByPath</function>
+
+ setAttrByPath :: [String] -> Any -> AttrSet
+
+
+
+ Create a new attribute set with value set at the nested
+ attribute location specified in attrPath.
+
+
+
+
+
+ attrPath
+
+
+
+ A list of strings representing the path through the nested attribute set.
+
+
+
+
+
+ value
+
+
+
+ The value to set at the location described by
+ attrPath.
+
+
+
+
+
+
+ Creating a new nested attribute set
+ { a = { b = 3; }; }
+]]>
+
+
+
+
+ <function>lib.attrsets.getAttrFromPath</function>
+
+ getAttrFromPath :: [String] -> AttrSet -> Value
+
+
+
+ Like except
+ without a default, and it will throw if the value doesn't exist.
+
+
+
+
+
+ attrPath
+
+
+
+ A list of strings representing the path through the nested attribute set
+ set.
+
+
+
+
+
+ set
+
+
+
+ The nested attribute set to find the value in.
+
+
+
+
+
+
+ Succesfully getting a value from an attribute set
+ 3
+]]>
+
+
+
+ Throwing after failing to get a value from an attribute set
+ error: cannot find attribute `x.y'
+]]>
+
+
+
+
+ <function>lib.attrsets.attrVals</function>
+
+ attrVals :: [String] -> AttrSet -> [Any]
+
+
+
+ Return the specified attributes from a set. All values must exist.
+
+
+
+
+
+ nameList
+
+
+
+ The list of attributes to fetch from set. Each
+ attribute name must exist on the attrbitue set.
+
+
+
+
+
+ set
+
+
+
+ The set to get attribute values from.
+
+
+
+
+
+
+ Getting several values from an attribute set
+ [ 1 2 3 ]
+]]>
+
+
+
+ Getting missing values from an attribute set
+
+
+
+
+
+ <function>lib.attrsets.attrValues</function>
+
+ attrValues :: AttrSet -> [Any]
+
+
+
+ Get all the attribute values from an attribute set.
+
+
+
+ Provides a backwards-compatible interface of
+ builtins.attrValues for Nix version older than 1.8.
+
+
+
+
+
+ attrs
+
+
+
+ The attribute set.
+
+
+
+
+
+
+
+ [ 1 2 3 ]
+]]>
+
+
+
+
+ <function>lib.attrsets.catAttrs</function>
+
+ catAttrs :: String -> AttrSet -> [Any]
+
+
+
+ Collect each attribute named `attr' from the list of attribute sets,
+ sets. Sets that don't contain the named attribute are
+ ignored.
+
+
+
+ Provides a backwards-compatible interface of
+ builtins.catAttrs for Nix version older than 1.9.
+
+
+
+
+
+ attr
+
+
+
+ Attribute name to select from each attribute set in
+ sets.
+
+
+
+
+
+ sets
+
+
+
+ The list of attribute sets to select attr from.
+
+
+
+
+
+
+ Collect an attribute from a list of attribute sets.
+
+ Attribute sets which don't have the attribute are ignored.
+
+ [ 1 2 ]
+ ]]>
+
+
+
+
+ <function>lib.attrsets.filterAttrs</function>
+
+ filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet
+
+
+
+ Filter an attribute set by removing all attributes for which the given
+ predicate return false.
+
+
+
+
+
+ pred
+
+
+
+ String -> Any -> Bool
+
+
+ Predicate which returns true to include an attribute, or returns false to
+ exclude it.
+
+
+
+
+ name
+
+
+
+ The attribute's name
+
+
+
+
+
+ value
+
+
+
+ The attribute's value
+
+
+
+
+
+ Returns true to include the attribute,
+ false to exclude the attribute.
+
+
+
+
+
+ set
+
+
+
+ The attribute set to filter
+
+
+
+
+
+
+ Filtering an attributeset
+ { foo = 1; }
+]]>
+
+
+
+
+ <function>lib.attrsets.filterAttrsRecursive</function>
+
+ filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet
+
+
+
+ Filter an attribute set recursively by removing all attributes for which the
+ given predicate return false.
+
+
+
+
+
+ pred
+
+
+
+ String -> Any -> Bool
+
+
+ Predicate which returns true to include an attribute, or returns false to
+ exclude it.
+
+
+
+
+ name
+
+
+
+ The attribute's name
+
+
+
+
+
+ value
+
+
+
+ The attribute's value
+
+
+
+
+
+ Returns true to include the attribute,
+ false to exclude the attribute.
+
+
+
+
+
+ set
+
+
+
+ The attribute set to filter
+
+
+
+
+
+
+ Recursively filtering an attribute set
+ {
+ levelA = {
+ example = "hi";
+ levelB = {
+ hello = "there";
+ this-one-is-present = { };
+ };
+ };
+ }
+ ]]>
+
+
+
+
+ <function>lib.attrsets.foldAttrs</function>
+
+ foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any
+
+
+
+ Apply fold function to values grouped by key.
+
+
+
+
+
+ op
+
+
+
+ Any -> Any -> Any
+
+
+ Given a value val and a collector
+ col, combine the two.
+
+
+
+
+ val
+
+
+
+ An attribute's value
+
+
+
+
+
+ col
+
+
+
+
+ The result of previous op calls with other values
+ and nul.
+
+
+
+
+
+
+
+
+ nul
+
+
+
+ The null-value, the starting value.
+
+
+
+
+
+ list_of_attrs
+
+
+
+ A list of attribute sets to fold together by key.
+
+
+
+
+
+
+ Combining an attribute of lists in to one attribute set
+ { a = [ 2 3 ]; b = [ 7 6 ]; }
+]]>
+
+
+
+
+ <function>lib.attrsets.collect</function>
+
+ collect :: (Any -> Bool) -> AttrSet -> [Any]
+
+
+
+ Recursively collect sets that verify a given predicate named
+ pred from the set attrs. The recursion
+ stops when pred returns true.
+
+
+
+
+
+ pred
+
+
+
+ Any -> Bool
+
+
+ Given an attribute's value, determine if recursion should stop.
+
+
+
+
+ value
+
+
+
+ The attribute set value.
+
+
+
+
+
+
+
+
+ attrs
+
+
+
+ The attribute set to recursively collect.
+
+
+
+
+
+
+ Collecting all lists from an attribute set
+ [["b"] [1]]
+]]>
+
+
+
+ Collecting all attribute-sets which contain the <literal>outPath</literal> attribute name.
+ [{ outPath = "a/"; } { outPath = "b/"; }]
+]]>
+
+
+
+
+ <function>lib.attrsets.nameValuePair</function>
+
+ nameValuePair :: String -> Any -> AttrSet
+
+
+
+ Utility function that creates a {name, value} pair as
+ expected by builtins.listToAttrs.
+
+
+
+
+
+ name
+
+
+
+ The attribute name.
+
+
+
+
+
+ value
+
+
+
+ The attribute value.
+
+
+
+
+
+
+ Creating a name value pair
+ { name = "some"; value = 6; }
+]]>
+
+
+
+
+ <function>lib.attrsets.mapAttrs</function>
+
+
+
+
+
+ Apply a function to each element in an attribute set, creating a new
+ attribute set.
+
+
+
+ Provides a backwards-compatible interface of
+ builtins.mapAttrs for Nix version older than 2.1.
+
+
+
+
+
+ fn
+
+
+
+ String -> Any -> Any
+
+
+ Given an attribute's name and value, return a new value.
+
+
+
+
+ name
+
+
+
+ The name of the attribute.
+
+
+
+
+
+ value
+
+
+
+ The attribute's value.
+
+
+
+
+
+
+
+
+
+ Modifying each value of an attribute set
+ { x = "x-foo"; y = "y-bar"; }
+]]>
+
+
+
+
+ <function>lib.attrsets.mapAttrs'</function>
+
+ mapAttrs' :: (String -> Any -> { name = String; value = Any }) -> AttrSet -> AttrSet
+
+
+
+ Like mapAttrs, but allows the name of each attribute to
+ be changed in addition to the value. The applied function should return both
+ the new name and value as a nameValuePair.
+
+
+
+
+
+ fn
+
+
+
+ String -> Any -> { name = String; value = Any }
+
+
+ Given an attribute's name and value, return a new
+ name
+ value pair.
+
+
+
+
+ name
+
+
+
+ The name of the attribute.
+
+
+
+
+
+ value
+
+
+
+ The attribute's value.
+
+
+
+
+
+
+
+
+ set
+
+
+
+ The attribute set to map over.
+
+
+
+
+
+
+ Change the name and value of each attribute of an attribute set
+ { foo_x = "bar-a"; foo_y = "bar-b"; }
+
+ ]]>
+
+
+
+
+ <function>lib.attrsets.mapAttrsToList</function>
+
+ mapAttrsToList :: (String -> Any -> Any) ->
+ AttrSet -> Any
+
+
+
+ Call fn for each attribute in the given
+ set and return the result in a list.
+
+
+
+
+
+ fn
+
+
+
+ String -> Any -> Any
+
+
+ Given an attribute's name and value, return a new value.
+
+
+
+
+ name
+
+
+
+ The name of the attribute.
+
+
+
+
+
+ value
+
+
+
+ The attribute's value.
+
+
+
+
+
+
+
+
+ set
+
+
+
+ The attribute set to map over.
+
+
+
+
+
+
+ Combine attribute values and names in to a list
+ [ "x=a" "y=b" ]
+]]>
+
+
+
+
+ <function>lib.attrsets.mapAttrsRecursive</function>
+
+ mapAttrsRecursive :: ([String] > Any -> Any) -> AttrSet -> AttrSet
+
+
+
+ Like mapAttrs, except that it recursively applies
+ itself to attribute sets. Also, the first argument of the argument function
+ is a list of the names of the containing attributes.
+
+
+