diff options
Diffstat (limited to 'doc/functions')
-rw-r--r-- | doc/functions/debug.section.md | 5 | ||||
-rw-r--r-- | doc/functions/debug.xml | 14 | ||||
-rw-r--r-- | doc/functions/generators.section.md | 56 | ||||
-rw-r--r-- | doc/functions/generators.xml | 74 | ||||
-rw-r--r-- | doc/functions/library.xml | 2 | ||||
-rw-r--r-- | doc/functions/library/asserts.xml | 2 | ||||
-rw-r--r-- | doc/functions/library/attrsets.xml | 49 | ||||
-rw-r--r-- | doc/functions/nix-gitignore.section.md | 49 | ||||
-rw-r--r-- | doc/functions/nix-gitignore.xml | 70 | ||||
-rw-r--r-- | doc/functions/prefer-remote-fetch.section.md | 17 | ||||
-rw-r--r-- | doc/functions/prefer-remote-fetch.xml | 21 |
11 files changed, 173 insertions, 186 deletions
diff --git a/doc/functions/debug.section.md b/doc/functions/debug.section.md new file mode 100644 index 00000000000..b2d8589431a --- /dev/null +++ b/doc/functions/debug.section.md @@ -0,0 +1,5 @@ +# Debugging Nix Expressions {#sec-debug} + +Nix is a unityped, dynamic language, this means every value can potentially appear anywhere. Since it is also non-strict, evaluation order and what ultimately is evaluated might surprise you. Therefore it is important to be able to debug nix expressions. + +In the `lib/debug.nix` file you will find a number of functions that help (pretty-)printing values while evaluation is running. You can even specify how deep these values should be printed recursively, and transform them on the fly. Please consult the docstrings in `lib/debug.nix` for usage information. diff --git a/doc/functions/debug.xml b/doc/functions/debug.xml deleted file mode 100644 index c27421f12e7..00000000000 --- a/doc/functions/debug.xml +++ /dev/null @@ -1,14 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="sec-debug"> - <title>Debugging Nix Expressions</title> - - <para> - Nix is a unityped, dynamic language, this means every value can potentially appear anywhere. Since it is also non-strict, evaluation order and what ultimately is evaluated might surprise you. Therefore it is important to be able to debug nix expressions. - </para> - - <para> - In the <literal>lib/debug.nix</literal> file you will find a number of functions that help (pretty-)printing values while evaluation is runnnig. You can even specify how deep these values should be printed recursively, and transform them on the fly. Please consult the docstrings in <literal>lib/debug.nix</literal> for usage information. - </para> -</section> diff --git a/doc/functions/generators.section.md b/doc/functions/generators.section.md new file mode 100644 index 00000000000..d54e5027c79 --- /dev/null +++ b/doc/functions/generators.section.md @@ -0,0 +1,56 @@ +# Generators {#sec-generators} +Generators are functions that create file formats from nix data structures, e. g. for configuration files. There are generators available for: `INI`, `JSON` and `YAML` + +All generators follow a similar call interface: `generatorName configFunctions data`, where `configFunctions` is an attrset of user-defined functions that format nested parts of the content. They each have common defaults, so often they do not need to be set manually. An example is `mkSectionName ? (name: libStr.escape [ "[" "]" ] name)` from the `INI` generator. It receives the name of a section and sanitizes it. The default `mkSectionName` escapes `[` and `]` with a backslash. + +Generators can be fine-tuned to produce exactly the file format required by your application/service. One example is an INI-file format which uses `: ` as separator, the strings `"yes"`/`"no"` as boolean values and requires all string values to be quoted: + +```nix +with lib; +let + customToINI = generators.toINI { + # specifies how to format a key/value pair + mkKeyValue = generators.mkKeyValueDefault { + # specifies the generated string for a subset of nix values + mkValueString = v: + if v == true then ''"yes"'' + else if v == false then ''"no"'' + else if isString v then ''"${v}"'' + # and delegats all other values to the default generator + else generators.mkValueStringDefault {} v; + } ":"; + }; + +# the INI file can now be given as plain old nix values +in customToINI { + main = { + pushinfo = true; + autopush = false; + host = "localhost"; + port = 42; + }; + mergetool = { + merge = "diff3"; + }; +} +``` + +This will produce the following INI file as nix string: + +```INI +[main] +autopush:"no" +host:"localhost" +port:42 +pushinfo:"yes" +str\:ange:"very::strange" + +[mergetool] +merge:"diff3" +``` + +::: {.note} +Nix store paths can be converted to strings by enclosing a derivation attribute like so: `"${drv}"`. +::: + +Detailed documentation for each generator can be found in `lib/generators.nix`. diff --git a/doc/functions/generators.xml b/doc/functions/generators.xml deleted file mode 100644 index 9ce1f85eb17..00000000000 --- a/doc/functions/generators.xml +++ /dev/null @@ -1,74 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="sec-generators"> - <title>Generators</title> - - <para> - Generators are functions that create file formats from nix data structures, e. g. for configuration files. There are generators available for: <literal>INI</literal>, <literal>JSON</literal> and <literal>YAML</literal> - </para> - - <para> - All generators follow a similar call interface: <code>generatorName configFunctions data</code>, where <literal>configFunctions</literal> is an attrset of user-defined functions that format nested parts of the content. They each have common defaults, so often they do not need to be set manually. An example is <code>mkSectionName ? (name: libStr.escape [ "[" "]" ] name)</code> from the <literal>INI</literal> generator. It receives the name of a section and sanitizes it. The default <literal>mkSectionName</literal> escapes <literal>[</literal> and <literal>]</literal> with a backslash. - </para> - - <para> - Generators can be fine-tuned to produce exactly the file format required by your application/service. One example is an INI-file format which uses <literal>: </literal> as separator, the strings <literal>"yes"</literal>/<literal>"no"</literal> as boolean values and requires all string values to be quoted: - </para> - -<programlisting> -with lib; -let - customToINI = generators.toINI { - # specifies how to format a key/value pair - mkKeyValue = generators.mkKeyValueDefault { - # specifies the generated string for a subset of nix values - mkValueString = v: - if v == true then ''"yes"'' - else if v == false then ''"no"'' - else if isString v then ''"${v}"'' - # and delegats all other values to the default generator - else generators.mkValueStringDefault {} v; - } ":"; - }; - -# the INI file can now be given as plain old nix values -in customToINI { - main = { - pushinfo = true; - autopush = false; - host = "localhost"; - port = 42; - }; - mergetool = { - merge = "diff3"; - }; -} -</programlisting> - - <para> - This will produce the following INI file as nix string: - </para> - -<programlisting> -[main] -autopush:"no" -host:"localhost" -port:42 -pushinfo:"yes" -str\:ange:"very::strange" - -[mergetool] -merge:"diff3" -</programlisting> - - <note> - <para> - Nix store paths can be converted to strings by enclosing a derivation attribute like so: <code>"${drv}"</code>. - </para> - </note> - - <para> - Detailed documentation for each generator can be found in <literal>lib/generators.nix</literal>. - </para> -</section> diff --git a/doc/functions/library.xml b/doc/functions/library.xml index 6ffb944b5a6..21bcf5b88c9 100644 --- a/doc/functions/library.xml +++ b/doc/functions/library.xml @@ -25,4 +25,6 @@ <xi:include href="./library/generated/debug.xml" /> <xi:include href="./library/generated/options.xml" /> + + <xi:include href="./library/generated/sources.xml" /> </section> diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml index 10891039e86..7c94222ef13 100644 --- a/doc/functions/library/asserts.xml +++ b/doc/functions/library/asserts.xml @@ -103,7 +103,7 @@ stderr> assert failed <title>Ensuring a user provided a possible value</title> <programlisting><![CDATA[ let sslLibrary = "bearssl"; -in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]; +in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "libressl" ]; => false stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl" ]]></programlisting> diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml index 3c5823c2589..ef132514da1 100644 --- a/doc/functions/library/attrsets.xml +++ b/doc/functions/library/attrsets.xml @@ -7,7 +7,7 @@ <section xml:id="function-library-lib.attrsets.attrByPath"> <title><function>lib.attrset.attrByPath</function></title> - <subtitle><literal>attrByPath :: [String] -> Any -> AttrSet</literal> + <subtitle><literal>attrByPath :: [String] -> Any -> AttrSet -> Any</literal> </subtitle> <xi:include href="./locations.xml" xpointer="lib.attrsets.attrByPath" /> @@ -166,7 +166,7 @@ lib.attrsets.setAttrByPath [ "a" "b" ] 3 <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. + Like [](#function-library-lib.attrsets.attrByPath) except without a default, and it will throw if the value doesn't exist. </para> <variablelist> @@ -855,7 +855,7 @@ lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name) <title><function>lib.attrsets.mapAttrsToList</function></title> <subtitle><literal>mapAttrsToList :: (String -> Any -> Any) -> - AttrSet -> Any</literal> + AttrSet -> [Any]</literal> </subtitle> <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsToList" /> @@ -1480,7 +1480,7 @@ lib.attrsets.zipAttrsWith <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrs" /> <para> - Merge sets of attributes and combine each attribute value in to a list. Similar to <xref linkend="function-library-lib.attrsets.zipAttrsWith" /> where the merge function returns a list of all values. + Merge sets of attributes and combine each attribute value in to a list. Similar to [](#function-library-lib.attrsets.zipAttrsWith) where the merge function returns a list of all values. </para> <variablelist> @@ -1677,8 +1677,7 @@ recursiveUpdate <xi:include href="./locations.xml" xpointer="lib.attrsets.recurseIntoAttrs" /> <para> - Make various Nix tools consider the contents of the resulting - attribute set when looking for what to build, find, etc. + Make various Nix tools consider the contents of the resulting attribute set when looking for what to build, find, etc. </para> <para> @@ -1711,4 +1710,42 @@ recursiveUpdate </example> </section> + <section xml:id="function-library-lib.attrsets.cartesianProductOfSets"> + <title><function>lib.attrsets.cartesianProductOfSets</function></title> + + <subtitle><literal>cartesianProductOfSets :: AttrSet -> [ AttrSet ]</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.cartesianProductOfSets" /> + + <para> + Return the cartesian product of attribute set value combinations. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + An attribute set with attributes that carry lists of values. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.cartesianProductOfSets-example"> + <title>Creating the cartesian product of a list of attribute values</title> +<programlisting><![CDATA[ +cartesianProductOfSets { a = [ 1 2 ]; b = [ 10 20 ]; } +=> [ + { a = 1; b = 10; } + { a = 1; b = 20; } + { a = 2; b = 10; } + { a = 2; b = 20; } + ] +]]></programlisting> + </example> + </section> </section> diff --git a/doc/functions/nix-gitignore.section.md b/doc/functions/nix-gitignore.section.md new file mode 100644 index 00000000000..2fb833b2300 --- /dev/null +++ b/doc/functions/nix-gitignore.section.md @@ -0,0 +1,49 @@ +# pkgs.nix-gitignore {#sec-pkgs-nix-gitignore} + +`pkgs.nix-gitignore` is a function that acts similarly to `builtins.filterSource` but also allows filtering with the help of the gitignore format. + +## Usage {#sec-pkgs-nix-gitignore-usage} + +`pkgs.nix-gitignore` exports a number of functions, but you\'ll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string. + +```nix +{ pkgs ? import <nixpkgs> {} }: + + nix-gitignore.gitignoreSource [] ./source + # Simplest version + + nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source + # This one reads the ./source/.gitignore and concats the auxiliary ignores + + nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source + # Use this string as gitignore, don't read ./source/.gitignore. + + nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source + # It also accepts a list (of strings and paths) that will be concatenated + # once the paths are turned to strings via readFile. +``` + +These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`: + +```nix +gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true); +gitignoreSource = gitignoreFilterSource (_: _: true); +``` + +Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it\'s blacklisted by either your filter or the gitignoreFilter. + +If you want to make your own filter from scratch, you may use + +```nix +gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root; +``` + +## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive} + +If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function: + +```nix +gitignoreFilterRecursiveSource = filter: patterns: root: +# OR +gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true); +``` diff --git a/doc/functions/nix-gitignore.xml b/doc/functions/nix-gitignore.xml deleted file mode 100644 index 37a82b196cc..00000000000 --- a/doc/functions/nix-gitignore.xml +++ /dev/null @@ -1,70 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="sec-pkgs-nix-gitignore"> - <title>pkgs.nix-gitignore</title> - - <para> - <function>pkgs.nix-gitignore</function> is a function that acts similarly to <literal>builtins.filterSource</literal> but also allows filtering with the help of the gitignore format. - </para> - - <section xml:id="sec-pkgs-nix-gitignore-usage"> - <title>Usage</title> - - <para> - <literal>pkgs.nix-gitignore</literal> exports a number of functions, but you'll most likely need either <literal>gitignoreSource</literal> or <literal>gitignoreSourcePure</literal>. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string. - </para> - -<programlisting><![CDATA[ -{ pkgs ? import <nixpkgs> {} }: - - nix-gitignore.gitignoreSource [] ./source - # Simplest version - - nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source - # This one reads the ./source/.gitignore and concats the auxiliary ignores - - nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source - # Use this string as gitignore, don't read ./source/.gitignore. - - nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source - # It also accepts a list (of strings and paths) that will be concatenated - # once the paths are turned to strings via readFile. - ]]></programlisting> - - <para> - These functions are derived from the <literal>Filter</literal> functions by setting the first filter argument to <literal>(_: _: true)</literal>: - </para> - -<programlisting><![CDATA[ -gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true); -gitignoreSource = gitignoreFilterSource (_: _: true); - ]]></programlisting> - - <para> - Those filter functions accept the same arguments the <literal>builtins.filterSource</literal> function would pass to its filters, thus <literal>fn: gitignoreFilterSourcePure fn ""</literal> should be extensionally equivalent to <literal>filterSource</literal>. The file is blacklisted iff it's blacklisted by either your filter or the gitignoreFilter. - </para> - - <para> - If you want to make your own filter from scratch, you may use - </para> - -<programlisting><![CDATA[ -gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root; - ]]></programlisting> - </section> - - <section xml:id="sec-pkgs-nix-gitignore-usage-recursive"> - <title>gitignore files in subdirectories</title> - - <para> - If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function: - </para> - -<programlisting><![CDATA[ -gitignoreFilterRecursiveSource = filter: patterns: root: -# OR -gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true); - ]]></programlisting> - </section> -</section> diff --git a/doc/functions/prefer-remote-fetch.section.md b/doc/functions/prefer-remote-fetch.section.md new file mode 100644 index 00000000000..8760c100224 --- /dev/null +++ b/doc/functions/prefer-remote-fetch.section.md @@ -0,0 +1,17 @@ +# prefer-remote-fetch overlay {#sec-prefer-remote-fetch} + +`prefer-remote-fetch` is an overlay that download sources on remote builder. This is useful when the evaluating machine has a slow upload while the builder can fetch faster directly from the source. To use it, put the following snippet as a new overlay: + +```nix +self: super: + (super.prefer-remote-fetch self super) +``` + +A full configuration example for that sets the overlay up for your own account, could look like this + +```ShellSession +$ mkdir ~/.config/nixpkgs/overlays/ +$ cat > ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix <<EOF + self: super: super.prefer-remote-fetch self super +EOF +``` diff --git a/doc/functions/prefer-remote-fetch.xml b/doc/functions/prefer-remote-fetch.xml deleted file mode 100644 index 94d25d3d3ae..00000000000 --- a/doc/functions/prefer-remote-fetch.xml +++ /dev/null @@ -1,21 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/xinclude" - xml:id="sec-prefer-remote-fetch"> - <title>prefer-remote-fetch overlay</title> - - <para> - <function>prefer-remote-fetch</function> is an overlay that download sources on remote builder. This is useful when the evaluating machine has a slow upload while the builder can fetch faster directly from the source. To use it, put the following snippet as a new overlay: -<programlisting> -self: super: - (super.prefer-remote-fetch self super) -</programlisting> - A full configuration example for that sets the overlay up for your own account, could look like this -<screen> -<prompt>$ </prompt>mkdir ~/.config/nixpkgs/overlays/ -<prompt>$ </prompt>cat > ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix <<EOF - self: super: super.prefer-remote-fetch self super -EOF -</screen> - </para> -</section> |