diff options
Diffstat (limited to 'nixpkgs/doc/functions')
| -rw-r--r-- | nixpkgs/doc/functions/appimagetools.xml | 102 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/debug.xml | 14 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/dockertools.xml | 484 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/fetchers.xml | 148 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/fhs-environments.xml | 122 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/generators.xml | 74 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/library.xml | 28 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/library/asserts.xml | 112 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/library/attrsets.xml | 1670 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/nix-gitignore.xml | 70 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/ocitools.xml | 62 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/overrides.xml | 151 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/prefer-remote-fetch.xml | 21 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/shell.xml | 24 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/snap/example-firefox.nix | 28 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/snap/example-hello.nix | 12 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/snaptools.xml | 59 | ||||
| -rw-r--r-- | nixpkgs/doc/functions/trivial-builders.xml | 79 |
18 files changed, 3260 insertions, 0 deletions
diff --git a/nixpkgs/doc/functions/appimagetools.xml b/nixpkgs/doc/functions/appimagetools.xml new file mode 100644 index 000000000000..37e4251cda2e --- /dev/null +++ b/nixpkgs/doc/functions/appimagetools.xml @@ -0,0 +1,102 @@ +<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-appimageTools"> + <title>pkgs.appimageTools</title> + + <para> + <varname>pkgs.appimageTools</varname> is a set of functions for extracting and wrapping <link xlink:href="https://appimage.org/">AppImage</link> files. They are meant to be used if traditional packaging from source is infeasible, or it would take too long. To quickly run an AppImage file, <literal>pkgs.appimage-run</literal> can be used as well. + </para> + + <warning> + <para> + The <varname>appimageTools</varname> API is unstable and may be subject to backwards-incompatible changes in the future. + </para> + </warning> + + <section xml:id="ssec-pkgs-appimageTools-formats"> + <title>AppImage formats</title> + + <para> + There are different formats for AppImages, see <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the specification</link> for details. + </para> + + <itemizedlist> + <listitem> + <para> + Type 1 images are ISO 9660 files that are also ELF executables. + </para> + </listitem> + <listitem> + <para> + Type 2 images are ELF executables with an appended filesystem. + </para> + </listitem> + </itemizedlist> + + <para> + They can be told apart with <command>file -k</command>: + </para> + +<screen> +<prompt>$ </prompt>file -k type1.AppImage +type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0, +spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data + +<prompt>$ </prompt>file -k type2.AppImage +type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x), scale 232-60668, spot sensor temperature -4.187500, color scheme 15, show scale bar, calibration: offset -0.000000, slope 0.000000 (Lepton 2.x), scale 4111-45000, spot sensor temperature 412442.250000, color scheme 3, minimum point enabled, calibration: offset -75402534979642766821519867692934234112.000000, slope 5815371847733706829839455140374904832.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=79dcc4e55a61c293c5e19edbd8d65b202842579f, stripped\012- data +</screen> + + <para> + Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM filesystem</literal>, and the type 2 AppImage is not. + </para> + </section> + + <section xml:id="ssec-pkgs-appimageTools-wrapping"> + <title>Wrapping</title> + + <para> + Depending on the type of AppImage you're wrapping, you'll have to use <varname>wrapType1</varname> or <varname>wrapType2</varname>. + </para> + +<programlisting> +appimageTools.wrapType2 { # or wrapType1 + name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' /> + src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' /> + url = https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage; + sha256 = "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s"; + }; + extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' /> +}</programlisting> + + <calloutlist> + <callout arearefs='ex-appimageTools-wrapping-1'> + <para> + <varname>name</varname> specifies the name of the resulting image. + </para> + </callout> + <callout arearefs='ex-appimageTools-wrapping-2'> + <para> + <varname>src</varname> specifies the AppImage file to extract. + </para> + </callout> + <callout arearefs='ex-appimageTools-wrapping-2'> + <para> + <varname>extraPkgs</varname> allows you to pass a function to include additional packages inside the FHS environment your AppImage is going to run in. There are a few ways to learn which dependencies an application needs: + <itemizedlist> + <listitem> + <para> + Looking through the extracted AppImage files, reading its scripts and running <command>patchelf</command> and <command>ldd</command> on its executables. This can also be done in <command>appimage-run</command>, by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>. + </para> + </listitem> + <listitem> + <para> + Running <command>strace -vfefile</command> on the wrapped executable, looking for libraries that can't be found. + </para> + </listitem> + </itemizedlist> + </para> + </callout> + </calloutlist> + </section> +</section> diff --git a/nixpkgs/doc/functions/debug.xml b/nixpkgs/doc/functions/debug.xml new file mode 100644 index 000000000000..c27421f12e76 --- /dev/null +++ b/nixpkgs/doc/functions/debug.xml @@ -0,0 +1,14 @@ +<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/nixpkgs/doc/functions/dockertools.xml b/nixpkgs/doc/functions/dockertools.xml new file mode 100644 index 000000000000..2243453c3e97 --- /dev/null +++ b/nixpkgs/doc/functions/dockertools.xml @@ -0,0 +1,484 @@ +<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-dockerTools"> + <title>pkgs.dockerTools</title> + + <para> + <varname>pkgs.dockerTools</varname> is a set of functions for creating and manipulating Docker images according to the <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120"> Docker Image Specification v1.2.0 </link>. Docker itself is not used to perform any of the operations done by these functions. + </para> + + <warning> + <para> + The <varname>dockerTools</varname> API is unstable and may be subject to backwards-incompatible changes in the future. + </para> + </warning> + + <section xml:id="ssec-pkgs-dockerTools-buildImage"> + <title>buildImage</title> + + <para> + This function is analogous to the <command>docker build</command> command, in that it can be used to build a Docker-compatible repository tarball containing a single image with one or multiple layers. As such, the result is suitable for being loaded in Docker with <command>docker load</command>. + </para> + + <para> + The parameters of <varname>buildImage</varname> with relative example values are described below: + </para> + + <example xml:id='ex-dockerTools-buildImage'> + <title>Docker build</title> +<programlisting> +buildImage { + name = "redis"; <co xml:id='ex-dockerTools-buildImage-1' /> + tag = "latest"; <co xml:id='ex-dockerTools-buildImage-2' /> + + fromImage = someBaseImage; <co xml:id='ex-dockerTools-buildImage-3' /> + fromImageName = null; <co xml:id='ex-dockerTools-buildImage-4' /> + fromImageTag = "latest"; <co xml:id='ex-dockerTools-buildImage-5' /> + + contents = pkgs.redis; <co xml:id='ex-dockerTools-buildImage-6' /> + runAsRoot = '' <co xml:id='ex-dockerTools-buildImage-runAsRoot' /> + #!${pkgs.runtimeShell} + mkdir -p /data + ''; + + config = { <co xml:id='ex-dockerTools-buildImage-8' /> + Cmd = [ "/bin/redis-server" ]; + WorkingDir = "/data"; + Volumes = { + "/data" = {}; + }; + }; +} +</programlisting> + </example> + + <para> + The above example will build a Docker image <literal>redis/latest</literal> from the given base image. Loading and running this image in Docker results in <literal>redis-server</literal> being started automatically. + </para> + + <calloutlist> + <callout arearefs='ex-dockerTools-buildImage-1'> + <para> + <varname>name</varname> specifies the name of the resulting image. This is the only required argument for <varname>buildImage</varname>. + </para> + </callout> + <callout arearefs='ex-dockerTools-buildImage-2'> + <para> + <varname>tag</varname> specifies the tag of the resulting image. By default it's <literal>null</literal>, which indicates that the nix output hash will be used as tag. + </para> + </callout> + <callout arearefs='ex-dockerTools-buildImage-3'> + <para> + <varname>fromImage</varname> is the repository tarball containing the base image. It must be a valid Docker image, such as exported by <command>docker save</command>. By default it's <literal>null</literal>, which can be seen as equivalent to <literal>FROM scratch</literal> of a <filename>Dockerfile</filename>. + </para> + </callout> + <callout arearefs='ex-dockerTools-buildImage-4'> + <para> + <varname>fromImageName</varname> can be used to further specify the base image within the repository, in case it contains multiple images. By default it's <literal>null</literal>, in which case <varname>buildImage</varname> will peek the first image available in the repository. + </para> + </callout> + <callout arearefs='ex-dockerTools-buildImage-5'> + <para> + <varname>fromImageTag</varname> can be used to further specify the tag of the base image within the repository, in case an image contains multiple tags. By default it's <literal>null</literal>, in which case <varname>buildImage</varname> will peek the first tag available for the base image. + </para> + </callout> + <callout arearefs='ex-dockerTools-buildImage-6'> + <para> + <varname>contents</varname> is a derivation that will be copied in the new layer of the resulting image. This can be similarly seen as <command>ADD contents/ /</command> in a <filename>Dockerfile</filename>. By default it's <literal>null</literal>. + </para> + </callout> + <callout arearefs='ex-dockerTools-buildImage-runAsRoot'> + <para> + <varname>runAsRoot</varname> is a bash script that will run as root in an environment that overlays the existing layers of the base image with the new resulting layer, including the previously copied <varname>contents</varname> derivation. This can be similarly seen as <command>RUN ...</command> in a <filename>Dockerfile</filename>. + <note> + <para> + Using this parameter requires the <literal>kvm</literal> device to be available. + </para> + </note> + </para> + </callout> + <callout arearefs='ex-dockerTools-buildImage-8'> + <para> + <varname>config</varname> is used to specify the configuration of the containers that will be started off the built image in Docker. The available options are listed in the <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions"> Docker Image Specification v1.2.0 </link>. + </para> + </callout> + </calloutlist> + + <para> + After the new layer has been created, its closure (to which <varname>contents</varname>, <varname>config</varname> and <varname>runAsRoot</varname> contribute) will be copied in the layer itself. Only new dependencies that are not already in the existing layers will be copied. + </para> + + <para> + At the end of the process, only one new single layer will be produced and added to the resulting image. + </para> + + <para> + The resulting repository will only list the single image <varname>image/tag</varname>. In the case of <xref linkend='ex-dockerTools-buildImage'/> it would be <varname>redis/latest</varname>. + </para> + + <para> + It is possible to inspect the arguments with which an image was built using its <varname>buildArgs</varname> attribute. + </para> + + <note> + <para> + If you see errors similar to <literal>getProtocolByName: does not exist (no such protocol name: tcp)</literal> you may need to add <literal>pkgs.iana-etc</literal> to <varname>contents</varname>. + </para> + </note> + + <note> + <para> + If you see errors similar to <literal>Error_Protocol ("certificate has unknown CA",True,UnknownCa)</literal> you may need to add <literal>pkgs.cacert</literal> to <varname>contents</varname>. + </para> + </note> + + <example xml:id="example-pkgs-dockerTools-buildImage-creation-date"> + <title>Impurely Defining a Docker Layer's Creation Date</title> + <para> + By default <function>buildImage</function> will use a static date of one second past the UNIX Epoch. This allows <function>buildImage</function> to produce binary reproducible images. When listing images with <command>docker images</command>, the newly created images will be listed like this: + </para> +<screen><![CDATA[ +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +hello latest 08c791c7846e 48 years ago 25.2MB +]]></screen> + <para> + You can break binary reproducibility but have a sorted, meaningful <literal>CREATED</literal> column by setting <literal>created</literal> to <literal>now</literal>. + </para> +<programlisting><![CDATA[ +pkgs.dockerTools.buildImage { + name = "hello"; + tag = "latest"; + created = "now"; + contents = pkgs.hello; + + config.Cmd = [ "/bin/hello" ]; +} +]]></programlisting> + <para> + and now the Docker CLI will display a reasonable date and sort the images as expected: +<screen><![CDATA[ +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +hello latest de2bf4786de6 About a minute ago 25.2MB +]]></screen> + however, the produced images will not be binary reproducible. + </para> + </example> + </section> + + <section xml:id="ssec-pkgs-dockerTools-buildLayeredImage"> + <title>buildLayeredImage</title> + + <para> + Create a Docker image with many of the store paths being on their own layer to improve sharing between images. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the resulting image. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>tag</varname> <emphasis>optional</emphasis> + </term> + <listitem> + <para> + Tag of the generated image. + </para> + <para> + <emphasis>Default:</emphasis> the output path's hash + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>contents</varname> <emphasis>optional</emphasis> + </term> + <listitem> + <para> + Top level paths in the container. Either a single derivation, or a list of derivations. + </para> + <para> + <emphasis>Default:</emphasis> <literal>[]</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>config</varname> <emphasis>optional</emphasis> + </term> + <listitem> + <para> + Run-time configuration of the container. A full list of the options are available at in the <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions"> Docker Image Specification v1.2.0 </link>. + </para> + <para> + <emphasis>Default:</emphasis> <literal>{}</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>created</varname> <emphasis>optional</emphasis> + </term> + <listitem> + <para> + Date and time the layers were created. Follows the same <literal>now</literal> exception supported by <literal>buildImage</literal>. + </para> + <para> + <emphasis>Default:</emphasis> <literal>1970-01-01T00:00:01Z</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>maxLayers</varname> <emphasis>optional</emphasis> + </term> + <listitem> + <para> + Maximum number of layers to create. + </para> + <para> + <emphasis>Default:</emphasis> <literal>100</literal> + </para> + <para> + <emphasis>Maximum:</emphasis> <literal>125</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>extraCommands</varname> <emphasis>optional</emphasis> + </term> + <listitem> + <para> + Shell commands to run while building the final layer, without access to most of the layer contents. Changes to this layer are "on top" of all the other layers, so can create additional directories and files. + </para> + </listitem> + </varlistentry> + </variablelist> + + <section xml:id="dockerTools-buildLayeredImage-arg-contents"> + <title>Behavior of <varname>contents</varname> in the final image</title> + + <para> + Each path directly listed in <varname>contents</varname> will have a symlink in the root of the image. + </para> + + <para> + For example: +<programlisting><![CDATA[ +pkgs.dockerTools.buildLayeredImage { + name = "hello"; + contents = [ pkgs.hello ]; +} +]]></programlisting> + will create symlinks for all the paths in the <literal>hello</literal> package: +<screen><![CDATA[ +/bin/hello -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello +/share/info/hello.info -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/info/hello.info +/share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo +]]></screen> + </para> + </section> + + <section xml:id="dockerTools-buildLayeredImage-arg-config"> + <title>Automatic inclusion of <varname>config</varname> references</title> + + <para> + The closure of <varname>config</varname> is automatically included in the closure of the final image. + </para> + + <para> + This allows you to make very simple Docker images with very little code. This container will start up and run <command>hello</command>: +<programlisting><![CDATA[ +pkgs.dockerTools.buildLayeredImage { + name = "hello"; + config.Cmd = [ "${pkgs.hello}/bin/hello" ]; +} +]]></programlisting> + </para> + </section> + + <section xml:id="dockerTools-buildLayeredImage-arg-maxLayers"> + <title>Adjusting <varname>maxLayers</varname></title> + + <para> + Increasing the <varname>maxLayers</varname> increases the number of layers which have a chance to be shared between different images. + </para> + + <para> + Modern Docker installations support up to 128 layers, however older versions support as few as 42. + </para> + + <para> + If the produced image will not be extended by other Docker builds, it is safe to set <varname>maxLayers</varname> to <literal>128</literal>. However it will be impossible to extend the image further. + </para> + + <para> + The first (<literal>maxLayers-2</literal>) most "popular" paths will have their own individual layers, then layer #<literal>maxLayers-1</literal> will contain all the remaining "unpopular" paths, and finally layer #<literal>maxLayers</literal> will contain the Image configuration. + </para> + + <para> + Docker's Layers are not inherently ordered, they are content-addressable and are not explicitly layered until they are composed in to an Image. + </para> + </section> + </section> + + <section xml:id="ssec-pkgs-dockerTools-fetchFromRegistry"> + <title>pullImage</title> + + <para> + This function is analogous to the <command>docker pull</command> command, in that it can be used to pull a Docker image from a Docker registry. By default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used to pull images. + </para> + + <para> + Its parameters are described in the example below: + </para> + + <example xml:id='ex-dockerTools-pullImage'> + <title>Docker pull</title> +<programlisting> +pullImage { + imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' /> + imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; <co xml:id='ex-dockerTools-pullImage-2' /> + finalImageName = "nix"; <co xml:id='ex-dockerTools-pullImage-3' /> + finalImageTag = "1.11"; <co xml:id='ex-dockerTools-pullImage-4' /> + sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-5' /> + os = "linux"; <co xml:id='ex-dockerTools-pullImage-6' /> + arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-7' /> +} +</programlisting> + </example> + + <calloutlist> + <callout arearefs='ex-dockerTools-pullImage-1'> + <para> + <varname>imageName</varname> specifies the name of the image to be downloaded, which can also include the registry namespace (e.g. <literal>nixos</literal>). This argument is required. + </para> + </callout> + <callout arearefs='ex-dockerTools-pullImage-2'> + <para> + <varname>imageDigest</varname> specifies the digest of the image to be downloaded. This argument is required. + </para> + </callout> + <callout arearefs='ex-dockerTools-pullImage-3'> + <para> + <varname>finalImageName</varname>, if specified, this is the name of the image to be created. Note it is never used to fetch the image since we prefer to rely on the immutable digest ID. By default it's equal to <varname>imageName</varname>. + </para> + </callout> + <callout arearefs='ex-dockerTools-pullImage-4'> + <para> + <varname>finalImageTag</varname>, if specified, this is the tag of the image to be created. Note it is never used to fetch the image since we prefer to rely on the immutable digest ID. By default it's <literal>latest</literal>. + </para> + </callout> + <callout arearefs='ex-dockerTools-pullImage-5'> + <para> + <varname>sha256</varname> is the checksum of the whole fetched image. This argument is required. + </para> + </callout> + <callout arearefs='ex-dockerTools-pullImage-6'> + <para> + <varname>os</varname>, if specified, is the operating system of the fetched image. By default it's <literal>linux</literal>. + </para> + </callout> + <callout arearefs='ex-dockerTools-pullImage-7'> + <para> + <varname>arch</varname>, if specified, is the cpu architecture of the fetched image. By default it's <literal>x86_64</literal>. + </para> + </callout> + </calloutlist> + + <para> + <literal>nix-prefetch-docker</literal> command can be used to get required image parameters: +<screen> +<prompt>$ </prompt>nix run nixpkgs.nix-prefetch-docker -c nix-prefetch-docker --image-name mysql --image-tag 5 +</screen> + Since a given <varname>imageName</varname> may transparently refer to a manifest list of images which support multiple architectures and/or operating systems, you can supply the <option>--os</option> and <option>--arch</option> arguments to specify exactly which image you want. By default it will match the OS and architecture of the host the command is run on. +<screen> +<prompt>$ </prompt>nix-prefetch-docker --image-name mysql --image-tag 5 --arch x86_64 --os linux +</screen> + Desired image name and tag can be set using <option>--final-image-name</option> and <option>--final-image-tag</option> arguments: +<screen> +<prompt>$ </prompt>nix-prefetch-docker --image-name mysql --image-tag 5 --final-image-name eu.gcr.io/my-project/mysql --final-image-tag prod +</screen> + </para> + </section> + + <section xml:id="ssec-pkgs-dockerTools-exportImage"> + <title>exportImage</title> + + <para> + This function is analogous to the <command>docker export</command> command, in that it can be used to flatten a Docker image that contains multiple layers. It is in fact the result of the merge of all the layers of the image. As such, the result is suitable for being imported in Docker with <command>docker import</command>. + </para> + + <note> + <para> + Using this function requires the <literal>kvm</literal> device to be available. + </para> + </note> + + <para> + The parameters of <varname>exportImage</varname> are the following: + </para> + + <example xml:id='ex-dockerTools-exportImage'> + <title>Docker export</title> +<programlisting> +exportImage { + fromImage = someLayeredImage; + fromImageName = null; + fromImageTag = null; + + name = someLayeredImage.name; +} +</programlisting> + </example> + + <para> + The parameters relative to the base image have the same synopsis as described in <xref linkend='ssec-pkgs-dockerTools-buildImage'/>, except that <varname>fromImage</varname> is the only required argument in this case. + </para> + + <para> + The <varname>name</varname> argument is the name of the derivation output, which defaults to <varname>fromImage.name</varname>. + </para> + </section> + + <section xml:id="ssec-pkgs-dockerTools-shadowSetup"> + <title>shadowSetup</title> + + <para> + This constant string is a helper for setting up the base files for managing users and groups, only if such files don't exist already. It is suitable for being used in a <varname>runAsRoot</varname> <xref linkend='ex-dockerTools-buildImage-runAsRoot'/> script for cases like in the example below: + </para> + + <example xml:id='ex-dockerTools-shadowSetup'> + <title>Shadow base files</title> +<programlisting> +buildImage { + name = "shadow-basic"; + + runAsRoot = '' + #!${pkgs.runtimeShell} + ${shadowSetup} + groupadd -r redis + useradd -r -g redis redis + mkdir /data + chown redis:redis /data + ''; +} +</programlisting> + </example> + + <para> + Creating base files like <literal>/etc/passwd</literal> or <literal>/etc/login.defs</literal> is necessary for shadow-utils to manipulate users and groups. + </para> + </section> +</section> diff --git a/nixpkgs/doc/functions/fetchers.xml b/nixpkgs/doc/functions/fetchers.xml new file mode 100644 index 000000000000..369c1fb153eb --- /dev/null +++ b/nixpkgs/doc/functions/fetchers.xml @@ -0,0 +1,148 @@ +<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-fetchers"> + <title>Fetcher functions</title> + + <para> + When using Nix, you will frequently need to download source code and other files from the internet. Nixpkgs comes with a few helper functions that allow you to fetch fixed-output derivations in a structured way. + </para> + + <para> + The two fetcher primitives are <function>fetchurl</function> and <function>fetchzip</function>. Both of these have two required arguments, a URL and a hash. The hash is typically <literal>sha256</literal>, although many more hash algorithms are supported. Nixpkgs contributors are currently recommended to use <literal>sha256</literal>. This hash will be used by Nix to identify your source. A typical usage of fetchurl is provided below. + </para> + +<programlisting><![CDATA[ +{ stdenv, fetchurl }: + +stdenv.mkDerivation { + name = "hello"; + src = fetchurl { + url = "http://www.example.org/hello.tar.gz"; + sha256 = "1111111111111111111111111111111111111111111111111111"; + }; +} +]]></programlisting> + + <para> + The main difference between <function>fetchurl</function> and <function>fetchzip</function> is in how they store the contents. <function>fetchurl</function> will store the unaltered contents of the URL within the Nix store. <function>fetchzip</function> on the other hand will decompress the archive for you, making files and directories directly accessible in the future. <function>fetchzip</function> can only be used with archives. Despite the name, <function>fetchzip</function> is not limited to .zip files and can also be used with any tarball. + </para> + + <para> + <function>fetchpatch</function> works very similarly to <function>fetchurl</function> with the same arguments expected. It expects patch files as a source and and performs normalization on them before computing the checksum. For example it will remove comments or other unstable parts that are sometimes added by version control systems and can change over time. + </para> + + <para> + Other fetcher functions allow you to add source code directly from a VCS such as subversion or git. These are mostly straightforward names based on the name of the command used with the VCS system. Because they give you a working repository, they act most like <function>fetchzip</function>. + </para> + + <variablelist> + <varlistentry> + <term> + <literal>fetchsvn</literal> + </term> + <listitem> + <para> + Used with Subversion. Expects <literal>url</literal> to a Subversion directory, <literal>rev</literal>, and <literal>sha256</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchgit</literal> + </term> + <listitem> + <para> + Used with Git. Expects <literal>url</literal> to a Git repo, <literal>rev</literal>, and <literal>sha256</literal>. <literal>rev</literal> in this case can be full the git commit id (SHA1 hash) or a tag name like <literal>refs/tags/v1.0</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchfossil</literal> + </term> + <listitem> + <para> + Used with Fossil. Expects <literal>url</literal> to a Fossil archive, <literal>rev</literal>, and <literal>sha256</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchcvs</literal> + </term> + <listitem> + <para> + Used with CVS. Expects <literal>cvsRoot</literal>, <literal>tag</literal>, and <literal>sha256</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchhg</literal> + </term> + <listitem> + <para> + Used with Mercurial. Expects <literal>url</literal>, <literal>rev</literal>, and <literal>sha256</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + A number of fetcher functions wrap part of <function>fetchurl</function> and <function>fetchzip</function>. They are mainly convenience functions intended for commonly used destinations of source code in Nixpkgs. These wrapper fetchers are listed below. + </para> + + <variablelist> + <varlistentry> + <term> + <literal>fetchFromGitHub</literal> + </term> + <listitem> + <para> + <function>fetchFromGitHub</function> expects four arguments. <literal>owner</literal> is a string corresponding to the GitHub user or organization that controls this repository. <literal>repo</literal> corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as <literal>owner</literal>/<literal>repo</literal>. <literal>rev</literal> corresponds to the Git commit hash or tag (e.g <literal>v1.0</literal>) that will be downloaded from Git. Finally, <literal>sha256</literal> corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but <literal>sha256</literal> is currently preferred. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchFromGitLab</literal> + </term> + <listitem> + <para> + This is used with GitLab repositories. The arguments expected are very similar to fetchFromGitHub above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchFromBitbucket</literal> + </term> + <listitem> + <para> + This is used with BitBucket repositories. The arguments expected are very similar to fetchFromGitHub above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchFromSavannah</literal> + </term> + <listitem> + <para> + This is used with Savannah repositories. The arguments expected are very similar to fetchFromGitHub above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fetchFromRepoOrCz</literal> + </term> + <listitem> + <para> + This is used with repo.or.cz repositories. The arguments expected are very similar to fetchFromGitHub above. + </para> + </listitem> + </varlistentry> + </variablelist> +</section> diff --git a/nixpkgs/doc/functions/fhs-environments.xml b/nixpkgs/doc/functions/fhs-environments.xml new file mode 100644 index 000000000000..e7b81e97a23f --- /dev/null +++ b/nixpkgs/doc/functions/fhs-environments.xml @@ -0,0 +1,122 @@ +<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-fhs-environments"> + <title>buildFHSUserEnv</title> + + <para> + <function>buildFHSUserEnv</function> provides a way to build and run FHS-compatible lightweight sandboxes. It creates an isolated root with bound <filename>/nix/store</filename>, so its footprint in terms of disk space needed is quite small. This allows one to run software which is hard or unfeasible to patch for NixOS -- 3rd-party source trees with FHS assumptions, games distributed as tarballs, software with integrity checking and/or external self-updated binaries. It uses Linux namespaces feature to create temporary lightweight environments which are destroyed after all child processes exit, without root user rights requirement. Accepted arguments are: + </para> + + <variablelist> + <varlistentry> + <term> + <literal>name</literal> + </term> + <listitem> + <para> + Environment name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>targetPkgs</literal> + </term> + <listitem> + <para> + Packages to be installed for the main host's architecture (i.e. x86_64 on x86_64 installations). Along with libraries binaries are also installed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>multiPkgs</literal> + </term> + <listitem> + <para> + Packages to be installed for all architectures supported by a host (i.e. i686 and x86_64 on x86_64 installations). Only libraries are installed by default. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>extraBuildCommands</literal> + </term> + <listitem> + <para> + Additional commands to be executed for finalizing the directory structure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>extraBuildCommandsMulti</literal> + </term> + <listitem> + <para> + Like <literal>extraBuildCommands</literal>, but executed only on multilib architectures. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>extraOutputsToInstall</literal> + </term> + <listitem> + <para> + Additional derivation outputs to be linked for both target and multi-architecture packages. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>extraInstallCommands</literal> + </term> + <listitem> + <para> + Additional commands to be executed for finalizing the derivation with runner script. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>runScript</literal> + </term> + <listitem> + <para> + A command that would be executed inside the sandbox and passed all the command line arguments. It defaults to <literal>bash</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + One can create a simple environment using a <literal>shell.nix</literal> like that: + </para> + +<programlisting><![CDATA[ +{ pkgs ? import <nixpkgs> {} }: + +(pkgs.buildFHSUserEnv { + name = "simple-x11-env"; + targetPkgs = pkgs: (with pkgs; + [ udev + alsaLib + ]) ++ (with pkgs.xorg; + [ libX11 + libXcursor + libXrandr + ]); + multiPkgs = pkgs: (with pkgs; + [ udev + alsaLib + ]); + runScript = "bash"; +}).env +]]></programlisting> + + <para> + Running <literal>nix-shell</literal> would then drop you into a shell with these libraries and binaries available. You can use this to run closed-source applications which expect FHS structure without hassles: simply change <literal>runScript</literal> to the application path, e.g. <filename>./bin/start.sh</filename> -- relative paths are supported. + </para> +</section> diff --git a/nixpkgs/doc/functions/generators.xml b/nixpkgs/doc/functions/generators.xml new file mode 100644 index 000000000000..9ce1f85eb173 --- /dev/null +++ b/nixpkgs/doc/functions/generators.xml @@ -0,0 +1,74 @@ +<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/nixpkgs/doc/functions/library.xml b/nixpkgs/doc/functions/library.xml new file mode 100644 index 000000000000..6ffb944b5a60 --- /dev/null +++ b/nixpkgs/doc/functions/library.xml @@ -0,0 +1,28 @@ +<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-functions-library"> + <title>Nixpkgs Library Functions</title> + + <para> + Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or through <code>import <nixpkgs/lib></code>. + </para> + + <xi:include href="./library/asserts.xml" /> + + <xi:include href="./library/attrsets.xml" /> + +<!-- These docs are generated via nixdoc. To add another generated + library function file to this list, the file + `lib-function-docs.nix` must also be updated. --> + + <xi:include href="./library/generated/strings.xml" /> + + <xi:include href="./library/generated/trivial.xml" /> + + <xi:include href="./library/generated/lists.xml" /> + + <xi:include href="./library/generated/debug.xml" /> + + <xi:include href="./library/generated/options.xml" /> +</section> diff --git a/nixpkgs/doc/functions/library/asserts.xml b/nixpkgs/doc/functions/library/asserts.xml new file mode 100644 index 000000000000..10891039e869 --- /dev/null +++ b/nixpkgs/doc/functions/library/asserts.xml @@ -0,0 +1,112 @@ +<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-functions-library-asserts"> + <title>Assert functions</title> + + <section xml:id="function-library-lib.asserts.assertMsg"> + <title><function>lib.asserts.assertMsg</function></title> + + <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> + + <para> + Intended to be used to augment asserts with helpful error messages. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + Condition under which the <varname>msg</varname> should <emphasis>not</emphasis> be printed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>msg</varname> + </term> + <listitem> + <para> + Message to print. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.asserts.assertMsg-example-false"> + <title>Printing when the predicate is false</title> +<programlisting><![CDATA[ +assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly" +stderr> trace: foo is not bar, silly +stderr> assert failed +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.asserts.assertOneOf"> + <title><function>lib.asserts.assertOneOf</function></title> + + <subtitle><literal>assertOneOf :: String -> String -> + 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>. Useful for checking enums. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the variable the user entered <varname>val</varname> into, for inclusion in the error message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>val</varname> + </term> + <listitem> + <para> + The value of what the user provided, to be compared against the values in <varname>xs</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>xs</varname> + </term> + <listitem> + <para> + The list of valid values. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.asserts.assertOneOf-example"> + <title>Ensuring a user provided a possible value</title> +<programlisting><![CDATA[ +let sslLibrary = "bearssl"; +in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]; +=> false +stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl" + ]]></programlisting> + </example> + </section> +</section> diff --git a/nixpkgs/doc/functions/library/attrsets.xml b/nixpkgs/doc/functions/library/attrsets.xml new file mode 100644 index 000000000000..f9234069392e --- /dev/null +++ b/nixpkgs/doc/functions/library/attrsets.xml @@ -0,0 +1,1670 @@ +<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-functions-library-attrset"> + <title>Attribute-Set Functions</title> + + <section xml:id="function-library-lib.attrsets.attrByPath"> + <title><function>lib.attrset.attrByPath</function></title> + + <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> + + <variablelist> + <varlistentry> + <term> + <varname>attrPath</varname> + </term> + <listitem> + <para> + A list of strings representing the path through the nested attribute set <varname>set</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>default</varname> + </term> + <listitem> + <para> + Default value if <varname>attrPath</varname> does not resolve to an existing value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The nested attributeset to select values from. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrset.attrByPath-example-value-exists"> + <title>Extracting a value from a nested attribute set</title> +<programlisting><![CDATA[ +let set = { a = { b = 3; }; }; +in lib.attrsets.attrByPath [ "a" "b" ] 0 set +=> 3 +]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrset.attrByPath-example-default-value"> + <title>No value at the path, instead using the default</title> +<programlisting><![CDATA[ +lib.attrsets.attrByPath [ "a" "b" ] 0 {} +=> 0 +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.hasAttrByPath"> + <title><function>lib.attrsets.hasAttrByPath</function></title> + + <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> + + <variablelist> + <varlistentry> + <term> + <varname>attrPath</varname> + </term> + <listitem> + <para> + A list of strings representing the path through the nested attribute set <varname>set</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The nested attributeset to check. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.hasAttrByPath-example"> + <title>A nested value does exist inside a set</title> +<programlisting><![CDATA[ +lib.attrsets.hasAttrByPath + [ "a" "b" "c" "d" ] + { a = { b = { c = { d = 123; }; }; }; } +=> true +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.setAttrByPath"> + <title><function>lib.attrsets.setAttrByPath</function></title> + + <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>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attrPath</varname> + </term> + <listitem> + <para> + A list of strings representing the path through the nested attribute set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The value to set at the location described by <varname>attrPath</varname>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.setAttrByPath-example"> + <title>Creating a new nested attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.setAttrByPath [ "a" "b" ] 3 +=> { a = { b = 3; }; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.getAttrFromPath"> + <title><function>lib.attrsets.getAttrFromPath</function></title> + + <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. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attrPath</varname> + </term> + <listitem> + <para> + A list of strings representing the path through the nested attribute set <varname>set</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The nested attribute set to find the value in. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.getAttrPath-example-success"> + <title>Succesfully getting a value from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.getAttrFromPath [ "a" "b" ] { a = { b = 3; }; } +=> 3 +]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.getAttrPath-example-throw"> + <title>Throwing after failing to get a value from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.getAttrFromPath [ "x" "y" ] { } +=> error: cannot find attribute `x.y' +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.attrVals"> + <title><function>lib.attrsets.attrVals</function></title> + + <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> + + <variablelist> + <varlistentry> + <term> + <varname>nameList</varname> + </term> + <listitem> + <para> + The list of attributes to fetch from <varname>set</varname>. Each attribute name must exist on the attrbitue set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The set to get attribute values from. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.attrVals-example-success"> + <title>Getting several values from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.attrVals [ "a" "b" "c" ] { a = 1; b = 2; c = 3; } +=> [ 1 2 3 ] +]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.attrVals-failure"> + <title>Getting missing values from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.attrVals [ "d" ] { } +error: attribute 'd' missing +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.attrValues"> + <title><function>lib.attrsets.attrValues</function></title> + + <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> + + <para> + Provides a backwards-compatible interface of <function>builtins.attrValues</function> for Nix version older than 1.8. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attrs</varname> + </term> + <listitem> + <para> + The attribute set. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.attrValues-example"> + <title></title> +<programlisting><![CDATA[ +lib.attrsets.attrValues { a = 1; b = 2; c = 3; } +=> [ 1 2 3 ] +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.catAttrs"> + <title><function>lib.attrsets.catAttrs</function></title> + + <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 ignored. + </para> + + <para> + Provides a backwards-compatible interface of <function>builtins.catAttrs</function> for Nix version older than 1.9. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attr</varname> + </term> + <listitem> + <para> + Attribute name to select from each attribute set in <varname>sets</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>sets</varname> + </term> + <listitem> + <para> + The list of attribute sets to select <varname>attr</varname> from. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.catAttrs-example"> + <title>Collect an attribute from a list of attribute sets.</title> + <para> + Attribute sets which don't have the attribute are ignored. + </para> +<programlisting><![CDATA[ +catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}] +=> [ 1 2 ] + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.filterAttrs"> + <title><function>lib.attrsets.filterAttrs</function></title> + + <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. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> Bool</literal> + </para> + <para> + Predicate which returns true to include an attribute, or returns false to exclude it. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The attribute's name + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Returns <literal>true</literal> to include the attribute, <literal>false</literal> to exclude the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to filter + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.filterAttrs-example"> + <title>Filtering an attributeset</title> +<programlisting><![CDATA[ +filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; } +=> { foo = 1; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.filterAttrsRecursive"> + <title><function>lib.attrsets.filterAttrsRecursive</function></title> + + <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. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> Bool</literal> + </para> + <para> + Predicate which returns true to include an attribute, or returns false to exclude it. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The attribute's name + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Returns <literal>true</literal> to include the attribute, <literal>false</literal> to exclude the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to filter + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.filterAttrsRecursive-example"> + <title>Recursively filtering an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.filterAttrsRecursive + (n: v: v != null) + { + levelA = { + example = "hi"; + levelB = { + hello = "there"; + this-one-is-present = { + this-is-excluded = null; + }; + }; + this-one-is-also-excluded = null; + }; + also-excluded = null; + } +=> { + levelA = { + example = "hi"; + levelB = { + hello = "there"; + this-one-is-present = { }; + }; + }; + } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.foldAttrs"> + <title><function>lib.attrsets.foldAttrs</function></title> + + <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> + + <variablelist> + <varlistentry> + <term> + <varname>op</varname> + </term> + <listitem> + <para> + <literal>Any -> Any -> Any</literal> + </para> + <para> + Given a value <varname>val</varname> and a collector <varname>col</varname>, combine the two. + </para> + <variablelist> + <varlistentry> + <term> + <varname>val</varname> + </term> + <listitem> + <para> + An attribute's value + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>col</varname> + </term> + <listitem> +<!-- TODO: make this not bad, use more fold-ey terms --> + <para> + The result of previous <function>op</function> calls with other values and <function>nul</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>nul</varname> + </term> + <listitem> + <para> + The null-value, the starting value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>list_of_attrs</varname> + </term> + <listitem> + <para> + A list of attribute sets to fold together by key. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.foldAttrs-example"> + <title>Combining an attribute of lists in to one attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.foldAttrs + (n: a: [n] ++ a) [] + [ + { a = 2; b = 7; } + { a = 3; } + { b = 6; } + ] +=> { a = [ 2 3 ]; b = [ 7 6 ]; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.collect"> + <title><function>lib.attrsets.collect</function></title> + + <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 stops when <varname>pred</varname> returns <literal>true</literal>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + <literal>Any -> Bool</literal> + </para> + <para> + Given an attribute's value, determine if recursion should stop. + </para> + <variablelist> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute set value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>attrs</varname> + </term> + <listitem> + <para> + The attribute set to recursively collect. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.collect-example-lists"> + <title>Collecting all lists from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.collect isList { a = { b = ["b"]; }; c = [1]; } +=> [["b"] [1]] +]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.collect-example-outpath"> + <title>Collecting all attribute-sets which contain the <literal>outPath</literal> attribute name.</title> +<programlisting><![CDATA[ +collect (x: x ? outPath) + { a = { outPath = "a/"; }; b = { outPath = "b/"; }; } +=> [{ outPath = "a/"; } { outPath = "b/"; }] +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.nameValuePair"> + <title><function>lib.attrsets.nameValuePair</function></title> + + <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>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The attribute name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute value. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.nameValuePair-example"> + <title>Creating a name value pair</title> +<programlisting><![CDATA[ +nameValuePair "some" 6 +=> { name = "some"; value = 6; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrs"> + <title><function>lib.attrsets.mapAttrs</function></title> + + <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. + </para> + + <para> + Provides a backwards-compatible interface of <function>builtins.mapAttrs</function> for Nix version older than 2.1. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>fn</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> Any</literal> + </para> + <para> + Given an attribute's name and value, return a new value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrs-example"> + <title>Modifying each value of an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.mapAttrs + (name: value: name + "-" value) + { x = "foo"; y = "bar"; } +=> { x = "x-foo"; y = "y-bar"; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrs-prime"> + <title><function>lib.attrsets.mapAttrs'</function></title> + + <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 the new name and value as a <function>nameValuePair</function>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>fn</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> { name = String; value = Any }</literal> + </para> + <para> + Given an attribute's name and value, return a new <link + linkend="function-library-lib.attrsets.nameValuePair">name value pair</link>. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to map over. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrs-prime-example"> + <title>Change the name and value of each attribute of an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name) ("bar-" + value)) + { x = "a"; y = "b"; } +=> { foo_x = "bar-a"; foo_y = "bar-b"; } + + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrsToList"> + <title><function>lib.attrsets.mapAttrsToList</function></title> + + <subtitle><literal>mapAttrsToList :: (String -> Any -> Any) -> + 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. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>fn</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> Any</literal> + </para> + <para> + Given an attribute's name and value, return a new value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to map over. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrsToList-example"> + <title>Combine attribute values and names in to a list</title> +<programlisting><![CDATA[ +lib.attrsets.mapAttrsToList (name: value: "${name}=${value}") + { x = "a"; y = "b"; } +=> [ "x=a" "y=b" ] +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrsRecursive"> + <title><function>lib.attrsets.mapAttrsRecursive</function></title> + + <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 is a <emphasis>list</emphasis> of the names of the containing attributes. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>[ String ] -> Any -> Any</literal> + </para> + <para> + Given a list of attribute names and value, return a new value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name_path</varname> + </term> + <listitem> + <para> + The list of attribute names to this value. + </para> + <para> + For example, the <varname>name_path</varname> for the <literal>example</literal> string in the attribute set <literal>{ foo = { bar = "example"; }; }</literal> is <literal>[ "foo" "bar" ]</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to recursively map over. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrsRecursive-example"> + <title>A contrived example of using <function>lib.attrsets.mapAttrsRecursive</function></title> +<programlisting><![CDATA[ +mapAttrsRecursive + (path: value: concatStringsSep "-" (path ++ [value])) + { + n = { + a = "A"; + m = { + b = "B"; + c = "C"; + }; + }; + d = "D"; + } +=> { + n = { + a = "n-a-A"; + m = { + b = "n-m-b-B"; + c = "n-m-c-C"; + }; + }; + d = "d-D"; + } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrsRecursiveCond"> + <title><function>lib.attrsets.mapAttrsRecursiveCond</function></title> + + <subtitle><literal>mapAttrsRecursiveCond :: (AttrSet -> Bool) -> ([ String ] -> Any -> Any) -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsRecursiveCond" /> + + <para> + Like <function>mapAttrsRecursive</function>, but it takes an additional predicate function that tells it whether to recursive into an attribute set. If it returns false, <function>mapAttrsRecursiveCond</function> does not recurse, but does apply the map function. It is returns true, it does recurse, and does not apply the map function. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>cond</varname> + </term> + <listitem> + <para> + <literal>(AttrSet -> Bool)</literal> + </para> + <para> + Determine if <function>mapAttrsRecursive</function> should recurse deeper in to the attribute set. + </para> + <variablelist> + <varlistentry> + <term> + <varname>attributeset</varname> + </term> + <listitem> + <para> + An attribute set. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>[ String ] -> Any -> Any</literal> + </para> + <para> + Given a list of attribute names and value, return a new value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name_path</varname> + </term> + <listitem> + <para> + The list of attribute names to this value. + </para> + <para> + For example, the <varname>name_path</varname> for the <literal>example</literal> string in the attribute set <literal>{ foo = { bar = "example"; }; }</literal> is <literal>[ "foo" "bar" ]</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to recursively map over. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrsRecursiveCond-example"> + <title>Only convert attribute values to JSON if the containing attribute set is marked for recursion</title> +<programlisting><![CDATA[ +lib.attrsets.mapAttrsRecursiveCond + ({ recurse ? false, ... }: recurse) + (name: value: builtins.toJSON value) + { + dorecur = { + recurse = true; + hello = "there"; + }; + dontrecur = { + converted-to- = "json"; + }; + } +=> { + dorecur = { + hello = "\"there\""; + recurse = "true"; + }; + dontrecur = "{\"converted-to\":\"json\"}"; + } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.genAttrs"> + <title><function>lib.attrsets.genAttrs</function></title> + + <subtitle><literal>genAttrs :: [ String ] -> (String -> Any) -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.genAttrs" /> + + <para> + Generate an attribute set by mapping a function over a list of attribute names. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>names</varname> + </term> + <listitem> + <para> + Names of values in the resulting attribute set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>String -> Any</literal> + </para> + <para> + Takes the name of the attribute and return the attribute's value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute to generate a value for. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.genAttrs-example"> + <title>Generate an attrset based on names only</title> +<programlisting><![CDATA[ +lib.attrsets.genAttrs [ "foo" "bar" ] (name: "x_${name}") +=> { foo = "x_foo"; bar = "x_bar"; } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.isDerivation"> + <title><function>lib.attrsets.isDerivation</function></title> + + <subtitle><literal>isDerivation :: Any -> Bool</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.isDerivation" /> + + <para> + Check whether the argument is a derivation. Any set with <code>{ type = "derivation"; }</code> counts as a derivation. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The value which is possibly a derivation. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.isDerivation-example-true"> + <title>A package is a derivation</title> +<programlisting><![CDATA[ +lib.attrsets.isDerivation (import <nixpkgs> {}).ruby +=> true + ]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.isDerivation-example-false"> + <title>Anything else is not a derivation</title> +<programlisting><![CDATA[ +lib.attrsets.isDerivation "foobar" +=> false + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.toDerivation"> + <title><function>lib.attrsets.toDerivation</function></title> + + <subtitle><literal>toDerivation :: Path -> Derivation</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.toDerivation" /> + + <para> + Converts a store path to a fake derivation. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>path</varname> + </term> + <listitem> + <para> + A store path to convert to a derivation. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section xml:id="function-library-lib.attrsets.optionalAttrs"> + <title><function>lib.attrsets.optionalAttrs</function></title> + + <subtitle><literal>optionalAttrs :: Bool -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.optionalAttrs" /> + + <para> + Conditionally return an attribute set or an empty attribute set. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>cond</varname> + </term> + <listitem> + <para> + Condition under which the <varname>as</varname> attribute set is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>as</varname> + </term> + <listitem> + <para> + The attribute set to return if <varname>cond</varname> is true. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.optionalAttrs-example-true"> + <title>Return the provided attribute set when <varname>cond</varname> is true</title> +<programlisting><![CDATA[ +lib.attrsets.optionalAttrs true { my = "set"; } +=> { my = "set"; } + ]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.optionalAttrs-example-false"> + <title>Return an empty attribute set when <varname>cond</varname> is false</title> +<programlisting><![CDATA[ +lib.attrsets.optionalAttrs false { my = "set"; } +=> { } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.zipAttrsWithNames"> + <title><function>lib.attrsets.zipAttrsWithNames</function></title> + + <subtitle><literal>zipAttrsWithNames :: [ String ] -> (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrsWithNames" /> + + <para> + Merge sets of attributes and use the function <varname>f</varname> to merge attribute values where the attribute name is in <varname>names</varname>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>names</varname> + </term> + <listitem> + <para> + A list of attribute names to zip. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>(String -> [ Any ] -> Any</literal> + </para> + <para> + Accepts an attribute name, all the values, and returns a combined value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute each value came from. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>vs</varname> + </term> + <listitem> + <para> + A list of values collected from the list of attribute sets. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>sets</varname> + </term> + <listitem> + <para> + A list of attribute sets to zip together. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.zipAttrsWithNames-example"> + <title>Summing a list of attribute sets of numbers</title> +<programlisting><![CDATA[ +lib.attrsets.zipAttrsWithNames + [ "a" "b" ] + (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}") + [ + { a = 1; b = 1; c = 1; } + { a = 10; } + { b = 100; } + { c = 1000; } + ] +=> { a = "a 11"; b = "b 101"; } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.zipAttrsWith"> + <title><function>lib.attrsets.zipAttrsWith</function></title> + + <subtitle><literal>zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrsWith" /> + + <para> + Merge sets of attributes and use the function <varname>f</varname> to merge attribute values. Similar to <xref + linkend="function-library-lib.attrsets.zipAttrsWithNames" /> where all key names are passed for <varname>names</varname>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>(String -> [ Any ] -> Any</literal> + </para> + <para> + Accepts an attribute name, all the values, and returns a combined value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute each value came from. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>vs</varname> + </term> + <listitem> + <para> + A list of values collected from the list of attribute sets. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>sets</varname> + </term> + <listitem> + <para> + A list of attribute sets to zip together. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.zipAttrsWith-example"> + <title>Summing a list of attribute sets of numbers</title> +<programlisting><![CDATA[ +lib.attrsets.zipAttrsWith + (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}") + [ + { a = 1; b = 1; c = 1; } + { a = 10; } + { b = 100; } + { c = 1000; } + ] +=> { a = "a 11"; b = "b 101"; c = "c 1001"; } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.zipAttrs"> + <title><function>lib.attrsets.zipAttrs</function></title> + + <subtitle><literal>zipAttrsWith :: [ AttrSet ] -> AttrSet</literal> + </subtitle> + + <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. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>sets</varname> + </term> + <listitem> + <para> + A list of attribute sets to zip together. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.zipAttrs-example"> + <title>Combining a list of attribute sets</title> +<programlisting><![CDATA[ +lib.attrsets.zipAttrs + [ + { a = 1; b = 1; c = 1; } + { a = 10; } + { b = 100; } + { c = 1000; } + ] +=> { a = [ 1 10 ]; b = [ 1 100 ]; c = [ 1 1000 ]; } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.recursiveUpdateUntil"> + <title><function>lib.attrsets.recursiveUpdateUntil</function></title> + + <subtitle><literal>recursiveUpdateUntil :: ( [ String ] -> AttrSet -> AttrSet -> Bool ) -> AttrSet -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.recursiveUpdateUntil" /> + + <para> + Does the same as the update operator <literal>//</literal> except that attributes are merged until the given predicate is verified. The predicate should accept 3 arguments which are the path to reach the attribute, a part of the first attribute set and a part of the second attribute set. When the predicate is verified, the value of the first attribute set is replaced by the value of the second attribute set. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + <literal>[ String ] -> AttrSet -> AttrSet -> Bool</literal> + </para> + <variablelist> + <varlistentry> + <term> + <varname>path</varname> + </term> + <listitem> + <para> + The path to the values in the left and right hand sides. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>l</varname> + </term> + <listitem> + <para> + The left hand side value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>r</varname> + </term> + <listitem> + <para> + The right hand side value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>lhs</varname> + </term> + <listitem> + <para> + The left hand attribute set of the merge. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>rhs</varname> + </term> + <listitem> + <para> + The right hand attribute set of the merge. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.recursiveUpdateUntil-example"> + <title>Recursively merging two attribute sets</title> +<programlisting><![CDATA[ +lib.attrsets.recursiveUpdateUntil (path: l: r: path == ["foo"]) + { + # first attribute set + foo.bar = 1; + foo.baz = 2; + bar = 3; + } + { + #second attribute set + foo.bar = 1; + foo.quz = 2; + baz = 4; + } +=> { + foo.bar = 1; # 'foo.*' from the second set + foo.quz = 2; # + bar = 3; # 'bar' from the first set + baz = 4; # 'baz' from the second set +} + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.recursiveUpdate"> + <title><function>lib.attrsets.recursiveUpdate</function></title> + + <subtitle><literal>recursiveUpdate :: AttrSet -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.recursiveUpdate" /> + + <para> + A recursive variant of the update operator <literal>//</literal>. The recursion stops when one of the attribute values is not an attribute set, in which case the right hand side value takes precedence over the left hand side value. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>lhs</varname> + </term> + <listitem> + <para> + The left hand attribute set of the merge. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>rhs</varname> + </term> + <listitem> + <para> + The right hand attribute set of the merge. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.recursiveUpdate-example"> + <title>Recursively merging two attribute sets</title> +<programlisting><![CDATA[ +recursiveUpdate + { + boot.loader.grub.enable = true; + boot.loader.grub.device = "/dev/hda"; + } + { + boot.loader.grub.device = ""; + } +=> { + boot.loader.grub.enable = true; + boot.loader.grub.device = ""; +} +]]></programlisting> + </example> + </section> +</section> diff --git a/nixpkgs/doc/functions/nix-gitignore.xml b/nixpkgs/doc/functions/nix-gitignore.xml new file mode 100644 index 000000000000..37a82b196ccf --- /dev/null +++ b/nixpkgs/doc/functions/nix-gitignore.xml @@ -0,0 +1,70 @@ +<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/nixpkgs/doc/functions/ocitools.xml b/nixpkgs/doc/functions/ocitools.xml new file mode 100644 index 000000000000..f61075b242f8 --- /dev/null +++ b/nixpkgs/doc/functions/ocitools.xml @@ -0,0 +1,62 @@ +<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-ociTools"> + <title>pkgs.ociTools</title> + + <para> + <varname>pkgs.ociTools</varname> is a set of functions for creating containers according to the <link xlink:href="https://github.com/opencontainers/runtime-spec">OCI container specification v1.0.0</link>. Beyond that it makes no assumptions about the container runner you choose to use to run the created container. + </para> + + <section xml:id="ssec-pkgs-ociTools-buildContainer"> + <title>buildContainer</title> + + <para> + This function creates a simple OCI container that runs a single command inside of it. An OCI container consists of a <varname>config.json</varname> and a rootfs directory.The nix store of the container will contain all referenced dependencies of the given command. + </para> + + <para> + The parameters of <varname>buildContainer</varname> with an example value are described below: + </para> + + <example xml:id='ex-ociTools-buildContainer'> + <title>Build Container</title> +<programlisting> +buildContainer { + args = [ (with pkgs; writeScript "run.sh" '' + #!${bash}/bin/bash + ${coreutils}/bin/exec ${bash}/bin/bash + '').outPath ]; <co xml:id='ex-ociTools-buildContainer-1' /> + + mounts = { + "/data" = { + type = "none"; + source = "/var/lib/mydata"; + options = [ "bind" ]; + }; + };<co xml:id='ex-ociTools-buildContainer-2' /> + + readonly = false; <co xml:id='ex-ociTools-buildContainer-3' /> +} + + </programlisting> + <calloutlist> + <callout arearefs='ex-ociTools-buildContainer-1'> + <para> + <varname>args</varname> specifies a set of arguments to run inside the container. This is the only required argument for <varname>buildContainer</varname>. All referenced packages inside the derivation will be made available inside the container + </para> + </callout> + <callout arearefs='ex-ociTools-buildContainer-2'> + <para> + <varname>mounts</varname> specifies additional mount points chosen by the user. By default only a minimal set of necessary filesystems are mounted into the container (e.g procfs, cgroupfs) + </para> + </callout> + <callout arearefs='ex-ociTools-buildContainer-3'> + <para> + <varname>readonly</varname> makes the container's rootfs read-only if it is set to true. The default value is false <literal>false</literal>. + </para> + </callout> + </calloutlist> + </example> + </section> +</section> diff --git a/nixpkgs/doc/functions/overrides.xml b/nixpkgs/doc/functions/overrides.xml new file mode 100644 index 000000000000..4ba4283c6094 --- /dev/null +++ b/nixpkgs/doc/functions/overrides.xml @@ -0,0 +1,151 @@ +<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-overrides"> + <title>Overriding</title> + + <para> + Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g. derivation attributes, the results of derivations. + </para> + + <para> + These functions are used to make changes to packages, returning only single packages. <link xlink:href="#chap-overlays">Overlays</link>, on the other hand, can be used to combine the overridden packages across the entire package set of Nixpkgs. + </para> + + <section xml:id="sec-pkg-override"> + <title><pkg>.override</title> + + <para> + The function <varname>override</varname> is usually available for all the derivations in the nixpkgs expression (<varname>pkgs</varname>). + </para> + + <para> + It is used to override the arguments passed to a function. + </para> + + <para> + Example usages: +<programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting> +<!-- TODO: move below programlisting to a new section about extending and overlays + and reference it + --> +<programlisting> +import pkgs.path { overlays = [ (self: super: { + foo = super.foo.override { barSupport = true ; }; + })]}; +</programlisting> +<programlisting> +mypkg = pkgs.callPackage ./mypkg.nix { + mydep = pkgs.mydep.override { ... }; + } +</programlisting> + </para> + + <para> + In the first example, <varname>pkgs.foo</varname> is the result of a function call with some default arguments, usually a derivation. Using <varname>pkgs.foo.override</varname> will call the same function with the given new arguments. + </para> + </section> + + <section xml:id="sec-pkg-overrideAttrs"> + <title><pkg>.overrideAttrs</title> + + <para> + The function <varname>overrideAttrs</varname> allows overriding the attribute set passed to a <varname>stdenv.mkDerivation</varname> call, producing a new derivation based on the original one. This function is available on all derivations produced by the <varname>stdenv.mkDerivation</varname> function, which is most packages in the nixpkgs expression <varname>pkgs</varname>. + </para> + + <para> + Example usage: +<programlisting> +helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec { + separateDebugInfo = true; +}); +</programlisting> + </para> + + <para> + In the above example, the <varname>separateDebugInfo</varname> attribute is overridden to be true, thus building debug info for <varname>helloWithDebug</varname>, while all other attributes will be retained from the original <varname>hello</varname> package. + </para> + + <para> + The argument <varname>oldAttrs</varname> is conventionally used to refer to the attr set originally passed to <varname>stdenv.mkDerivation</varname>. + </para> + + <note> + <para> + Note that <varname>separateDebugInfo</varname> is processed only by the <varname>stdenv.mkDerivation</varname> function, not the generated, raw Nix derivation. Thus, using <varname>overrideDerivation</varname> will not work in this case, as it overrides only the attributes of the final derivation. It is for this reason that <varname>overrideAttrs</varname> should be preferred in (almost) all cases to <varname>overrideDerivation</varname>, i.e. to allow using <varname>stdenv.mkDerivation</varname> to process input arguments, as well as the fact that it is easier to use (you can use the same attribute names you see in your Nix code, instead of the ones generated (e.g. <varname>buildInputs</varname> vs <varname>nativeBuildInputs</varname>), and it involves less typing). + </para> + </note> + </section> + + <section xml:id="sec-pkg-overrideDerivation"> + <title><pkg>.overrideDerivation</title> + + <warning> + <para> + You should prefer <varname>overrideAttrs</varname> in almost all cases, see its documentation for the reasons why. <varname>overrideDerivation</varname> is not deprecated and will continue to work, but is less nice to use and does not have as many abilities as <varname>overrideAttrs</varname>. + </para> + </warning> + + <warning> + <para> + Do not use this function in Nixpkgs as it evaluates a Derivation before modifying it, which breaks package abstraction and removes error-checking of function arguments. In addition, this evaluation-per-function application incurs a performance penalty, which can become a problem if many overrides are used. It is only intended for ad-hoc customisation, such as in <filename>~/.config/nixpkgs/config.nix</filename>. + </para> + </warning> + + <para> + The function <varname>overrideDerivation</varname> creates a new derivation based on an existing one by overriding the original's attributes with the attribute set produced by the specified function. This function is available on all derivations defined using the <varname>makeOverridable</varname> function. Most standard derivation-producing functions, such as <varname>stdenv.mkDerivation</varname>, are defined using this function, which means most packages in the nixpkgs expression, <varname>pkgs</varname>, have this function. + </para> + + <para> + Example usage: +<programlisting> +mySed = pkgs.gnused.overrideDerivation (oldAttrs: { + name = "sed-4.2.2-pre"; + src = fetchurl { + url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2; + sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k"; + }; + patches = []; +}); +</programlisting> + </para> + + <para> + In the above example, the <varname>name</varname>, <varname>src</varname>, and <varname>patches</varname> of the derivation will be overridden, while all other attributes will be retained from the original derivation. + </para> + + <para> + The argument <varname>oldAttrs</varname> is used to refer to the attribute set of the original derivation. + </para> + + <note> + <para> + A package's attributes are evaluated *before* being modified by the <varname>overrideDerivation</varname> function. For example, the <varname>name</varname> attribute reference in <varname>url = "mirror://gnu/hello/${name}.tar.gz";</varname> is filled-in *before* the <varname>overrideDerivation</varname> function modifies the attribute set. This means that overriding the <varname>name</varname> attribute, in this example, *will not* change the value of the <varname>url</varname> attribute. Instead, we need to override both the <varname>name</varname> *and* <varname>url</varname> attributes. + </para> + </note> + </section> + + <section xml:id="sec-lib-makeOverridable"> + <title>lib.makeOverridable</title> + + <para> + The function <varname>lib.makeOverridable</varname> is used to make the result of a function easily customizable. This utility only makes sense for functions that accept an argument set and return an attribute set. + </para> + + <para> + Example usage: +<programlisting> +f = { a, b }: { result = a+b; }; +c = lib.makeOverridable f { a = 1; b = 2; }; +</programlisting> + </para> + + <para> + The variable <varname>c</varname> is the value of the <varname>f</varname> function applied with some default arguments. Hence the value of <varname>c.result</varname> is <literal>3</literal>, in this example. + </para> + + <para> + The variable <varname>c</varname> however also has some additional functions, like <link linkend="sec-pkg-override">c.override</link> which can be used to override the default arguments. In this example the value of <varname>(c.override { a = 4; }).result</varname> is 6. + </para> + </section> +</section> diff --git a/nixpkgs/doc/functions/prefer-remote-fetch.xml b/nixpkgs/doc/functions/prefer-remote-fetch.xml new file mode 100644 index 000000000000..94d25d3d3aeb --- /dev/null +++ b/nixpkgs/doc/functions/prefer-remote-fetch.xml @@ -0,0 +1,21 @@ +<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> diff --git a/nixpkgs/doc/functions/shell.xml b/nixpkgs/doc/functions/shell.xml new file mode 100644 index 000000000000..cef65d06b882 --- /dev/null +++ b/nixpkgs/doc/functions/shell.xml @@ -0,0 +1,24 @@ +<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-mkShell"> + <title>pkgs.mkShell</title> + + <para> + <function>pkgs.mkShell</function> is a special kind of derivation that is only useful when using it combined with <command>nix-shell</command>. It will in fact fail to instantiate when invoked with <command>nix-build</command>. + </para> + + <section xml:id="sec-pkgs-mkShell-usage"> + <title>Usage</title> + +<programlisting><![CDATA[ +{ pkgs ? import <nixpkgs> {} }: +pkgs.mkShell { + # this will make all the build inputs from hello and gnutar + # available to the shell environment + inputsFrom = with pkgs; [ hello gnutar ]; + buildInputs = [ pkgs.gnumake ]; +} +]]></programlisting> + </section> +</section> diff --git a/nixpkgs/doc/functions/snap/example-firefox.nix b/nixpkgs/doc/functions/snap/example-firefox.nix new file mode 100644 index 000000000000..d58c98a65a2e --- /dev/null +++ b/nixpkgs/doc/functions/snap/example-firefox.nix @@ -0,0 +1,28 @@ +let + inherit (import <nixpkgs> { }) snapTools firefox; +in snapTools.makeSnap { + meta = { + name = "nix-example-firefox"; + summary = firefox.meta.description; + architectures = [ "amd64" ]; + apps.nix-example-firefox = { + command = "${firefox}/bin/firefox"; + plugs = [ + "pulseaudio" + "camera" + "browser-support" + "avahi-observe" + "cups-control" + "desktop" + "desktop-legacy" + "gsettings" + "home" + "network" + "mount-observe" + "removable-media" + "x11" + ]; + }; + confinement = "strict"; + }; +} diff --git a/nixpkgs/doc/functions/snap/example-hello.nix b/nixpkgs/doc/functions/snap/example-hello.nix new file mode 100644 index 000000000000..123da80c5477 --- /dev/null +++ b/nixpkgs/doc/functions/snap/example-hello.nix @@ -0,0 +1,12 @@ +let + inherit (import <nixpkgs> { }) snapTools hello; +in snapTools.makeSnap { + meta = { + name = "hello"; + summary = hello.meta.description; + description = hello.meta.longDescription; + architectures = [ "amd64" ]; + confinement = "strict"; + apps.hello.command = "${hello}/bin/hello"; + }; +} diff --git a/nixpkgs/doc/functions/snaptools.xml b/nixpkgs/doc/functions/snaptools.xml new file mode 100644 index 000000000000..422fcfa37d88 --- /dev/null +++ b/nixpkgs/doc/functions/snaptools.xml @@ -0,0 +1,59 @@ +<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-snapTools"> + <title>pkgs.snapTools</title> + + <para> + <varname>pkgs.snapTools</varname> is a set of functions for creating Snapcraft images. Snap and Snapcraft is not used to perform these operations. + </para> + + <section xml:id="ssec-pkgs-snapTools-makeSnap-signature"> + <title>The makeSnap Function</title> + + <para> + <function>makeSnap</function> takes a single named argument, <parameter>meta</parameter>. This argument mirrors <link xlink:href="https://docs.snapcraft.io/snap-format">the upstream <filename>snap.yaml</filename> format</link> exactly. + </para> + + <para> + The <parameter>base</parameter> should not be be specified, as <function>makeSnap</function> will force set it. + </para> + + <para> + Currently, <function>makeSnap</function> does not support creating GUI stubs. + </para> + </section> + + <section xml:id="ssec-pkgs-snapTools-build-a-snap-hello"> + <title>Build a Hello World Snap</title> + + <example xml:id="ex-snapTools-buildSnap-hello"> + <title>Making a Hello World Snap</title> + <para> + The following expression packages GNU Hello as a Snapcraft snap. + </para> +<programlisting><xi:include href="./snap/example-hello.nix" parse="text" /></programlisting> + <para> + <command>nix-build</command> this expression and install it with <command>snap install ./result --dangerous</command>. <command>hello</command> will now be the Snapcraft version of the package. + </para> + </example> + </section> + + <section xml:id="ssec-pkgs-snapTools-build-a-snap-firefox"> + <title>Build a Hello World Snap</title> + + <example xml:id="ex-snapTools-buildSnap-firefox"> + <title>Making a Graphical Snap</title> + <para> + Graphical programs require many more integrations with the host. This example uses Firefox as an example, because it is one of the most complicated programs we could package. + </para> +<programlisting><xi:include href="./snap/example-firefox.nix" parse="text" /></programlisting> + <para> + <command>nix-build</command> this expression and install it with <command>snap install ./result --dangerous</command>. <command>nix-example-firefox</command> will now be the Snapcraft version of the Firefox package. + </para> + <para> + The specific meaning behind plugs can be looked up in the <link xlink:href="https://docs.snapcraft.io/supported-interfaces">Snapcraft interface documentation</link>. + </para> + </example> + </section> +</section> diff --git a/nixpkgs/doc/functions/trivial-builders.xml b/nixpkgs/doc/functions/trivial-builders.xml new file mode 100644 index 000000000000..ae9f3a1b255d --- /dev/null +++ b/nixpkgs/doc/functions/trivial-builders.xml @@ -0,0 +1,79 @@ +<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-trivial-builders"> + <title>Trivial builders</title> + + <para> + Nixpkgs provides a couple of functions that help with building derivations. The most important one, <function>stdenv.mkDerivation</function>, has already been documented above. The following functions wrap <function>stdenv.mkDerivation</function>, making it easier to use in certain cases. + </para> + + <variablelist> + <varlistentry> + <term> + <literal>runCommand</literal> + </term> + <listitem> + <para> + This takes three arguments, <literal>name</literal>, <literal>env</literal>, and <literal>buildCommand</literal>. <literal>name</literal> is just the name that Nix will append to the store path in the same way that <literal>stdenv.mkDerivation</literal> uses its <literal>name</literal> attribute. <literal>env</literal> is an attribute set specifying environment variables that will be set for this derivation. These attributes are then passed to the wrapped <literal>stdenv.mkDerivation</literal>. <literal>buildCommand</literal> specifies the commands that will be run to create this derivation. Note that you will need to create <literal>$out</literal> for Nix to register the command as successful. + </para> + <para> + An example of using <literal>runCommand</literal> is provided below. + </para> +<programlisting> +(import <nixpkgs> {}).runCommand "my-example" {} '' + echo My example command is running + + mkdir $out + + echo I can write data to the Nix store > $out/message + + echo I can also run basic commands like: + + echo ls + ls + + echo whoami + whoami + + echo date + date +'' +</programlisting> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>runCommandCC</literal> + </term> + <listitem> + <para> + This works just like <literal>runCommand</literal>. The only difference is that it also provides a C compiler in <literal>buildCommand</literal>’s environment. To minimize your dependencies, you should only use this if you are sure you will need a C compiler as part of running your command. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>writeTextFile</literal>, <literal>writeText</literal>, <literal>writeTextDir</literal>, <literal>writeScript</literal>, <literal>writeScriptBin</literal> + </term> + <listitem> + <para> + These functions write <literal>text</literal> to the Nix store. This is useful for creating scripts from Nix expressions. <literal>writeTextFile</literal> takes an attribute set and expects two arguments, <literal>name</literal> and <literal>text</literal>. <literal>name</literal> corresponds to the name used in the Nix store path. <literal>text</literal> will be the contents of the file. You can also set <literal>executable</literal> to true to make this file have the executable bit set. + </para> + <para> + Many more commands wrap <literal>writeTextFile</literal> including <literal>writeText</literal>, <literal>writeTextDir</literal>, <literal>writeScript</literal>, and <literal>writeScriptBin</literal>. These are convenience functions over <literal>writeTextFile</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>symlinkJoin</literal> + </term> + <listitem> + <para> + This can be used to put many derivations into the same directory structure. It works by creating a new derivation and adding symlinks to each of the paths listed. It expects two arguments, <literal>name</literal>, and <literal>paths</literal>. <literal>name</literal> is the name used in the Nix store path for the created derivation. <literal>paths</literal> is a list of paths that will be symlinked. These paths can be to Nix store derivations or any other subdirectory contained within. + </para> + </listitem> + </varlistentry> + </variablelist> +</section> |