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

nixpkgs docs: Reformat

Browse Source
This commit is contained in:
Graham Christensen 2018-10-02 15:59:59 -04:00
parent 444e04b985
commit c07ba7c856
No known key found for this signature in database
GPG Key ID: ACA1C1D120C83D5C
8 changed files with 788 additions and 777 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/cross-compilation.xml
View File

@ -47,9 +47,10 @@
<para> <para>
In Nixpkgs, these three platforms are defined as attribute sets under the In Nixpkgs, these three platforms are defined as attribute sets under the
names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>, and names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>,
<literal>targetPlatform</literal>. They are always defined as attributes in and <literal>targetPlatform</literal>. They are always defined as
the standard environment. That means one can access them like: attributes in the standard environment. That means one can access them
like:
<programlisting>{ stdenv, fooDep, barDep, .. }: ...stdenv.buildPlatform...</programlisting> <programlisting>{ stdenv, fooDep, barDep, .. }: ...stdenv.buildPlatform...</programlisting>
. .
</para> </para>

30
doc/functions/debug.xml
View File

@ -2,20 +2,20 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-debug"> xml:id="sec-debug">
<title>Debugging Nix Expressions</title> <title>Debugging Nix Expressions</title>
<para> <para>
Nix is a unityped, dynamic language, this means every value can potentially Nix is a unityped, dynamic language, this means every value can potentially
appear anywhere. Since it is also non-strict, evaluation order and what appear anywhere. Since it is also non-strict, evaluation order and what
ultimately is evaluated might surprise you. Therefore it is important to be ultimately is evaluated might surprise you. Therefore it is important to be
able to debug nix expressions. able to debug nix expressions.
</para> </para>
<para> <para>
In the <literal>lib/debug.nix</literal> file you will find a number of In the <literal>lib/debug.nix</literal> file you will find a number of
functions that help (pretty-)printing values while evaluation is runnnig. functions that help (pretty-)printing values while evaluation is runnnig. You
You can even specify how deep these values should be printed recursively, can even specify how deep these values should be printed recursively, and
and transform them on the fly. Please consult the docstrings in transform them on the fly. Please consult the docstrings in
<literal>lib/debug.nix</literal> for usage information. <literal>lib/debug.nix</literal> for usage information.
</para> </para>
</section> </section>

848
doc/functions/dockertools.xml
View File

@ -2,40 +2,40 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-pkgs-dockerTools"> xml:id="sec-pkgs-dockerTools">
<title>pkgs.dockerTools</title> <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> <para>
<varname>pkgs.dockerTools</varname> is a set of functions for creating and This function is analogous to the <command>docker build</command> command,
manipulating Docker images according to the in that can used to build a Docker-compatible repository tarball containing
<link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120"> a single image with one or multiple layers. As such, the result is suitable
Docker Image Specification v1.2.0 </link>. Docker itself is not used to for being loaded in Docker with <command>docker load</command>.
perform any of the operations done by these functions.
</para> </para>
<warning> <para>
<para> The parameters of <varname>buildImage</varname> with relative example values
The <varname>dockerTools</varname> API is unstable and may be subject to are described below:
backwards-incompatible changes in the future. </para>
</para>
</warning>
<section xml:id="ssec-pkgs-dockerTools-buildImage"> <example xml:id='ex-dockerTools-buildImage'>
<title>buildImage</title> <title>Docker build</title>
<para>
This function is analogous to the <command>docker build</command> command,
in that can 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> <programlisting>
buildImage { buildImage {
name = "redis"; <co xml:id='ex-dockerTools-buildImage-1' /> name = "redis"; <co xml:id='ex-dockerTools-buildImage-1' />
@ -60,151 +60,150 @@ buildImage {
}; };
} }
</programlisting> </programlisting>
</example> </example>
<para> <para>
The above example will build a Docker image <literal>redis/latest</literal> 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 from the given base image. Loading and running this image in Docker results
in <literal>redis-server</literal> being started automatically. in <literal>redis-server</literal> being started automatically.
</para> </para>
<calloutlist> <calloutlist>
<callout arearefs='ex-dockerTools-buildImage-1'> <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> <para>
If you see errors similar to <literal>getProtocolByName: does not exist <varname>name</varname> specifies the name of the resulting image. This is
(no such protocol name: tcp)</literal> you may need to add the only required argument for <varname>buildImage</varname>.
<literal>pkgs.iana-etc</literal> to <varname>contents</varname>.
</para> </para>
</note> </callout>
<callout arearefs='ex-dockerTools-buildImage-2'>
<note>
<para> <para>
If you see errors similar to <literal>Error_Protocol ("certificate has <varname>tag</varname> specifies the tag of the resulting image. By
unknown CA",True,UnknownCa)</literal> you may need to add default it's <literal>null</literal>, which indicates that the nix output
<literal>pkgs.cacert</literal> to <varname>contents</varname>. hash will be used as tag.
</para> </para>
</note> </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>
<example xml:id="example-pkgs-dockerTools-buildImage-creation-date"> <para>
<title>Impurely Defining a Docker Layer's Creation Date</title> After the new layer has been created, its closure (to which
<para> <varname>contents</varname>, <varname>config</varname> and
By default <function>buildImage</function> will use a static <varname>runAsRoot</varname> contribute) will be copied in the layer itself.
date of one second past the UNIX Epoch. This allows Only new dependencies that are not already in the existing layers will be
<function>buildImage</function> to produce binary reproducible copied.
images. When listing images with <command>docker list </para>
images</command>, the newly created images will be listed like
this: <para>
</para> At the end of the process, only one new single layer will be produced and
<screen><![CDATA[ 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 list images</command>, the newly created images will be
listed like this:
</para>
<screen><![CDATA[
$ docker image list $ docker image list
REPOSITORY TAG IMAGE ID CREATED SIZE REPOSITORY TAG IMAGE ID CREATED SIZE
hello latest 08c791c7846e 48 years ago 25.2MB hello latest 08c791c7846e 48 years ago 25.2MB
]]></screen> ]]></screen>
<para> <para>
You can break binary reproducibility but have a sorted, You can break binary reproducibility but have a sorted, meaningful
meaningful <literal>CREATED</literal> column by setting <literal>CREATED</literal> column by setting <literal>created</literal> to
<literal>created</literal> to <literal>now</literal>. <literal>now</literal>.
</para> </para>
<programlisting><![CDATA[ <programlisting><![CDATA[
pkgs.dockerTools.buildImage { pkgs.dockerTools.buildImage {
name = "hello"; name = "hello";
tag = "latest"; tag = "latest";
@ -214,206 +213,206 @@ pkgs.dockerTools.buildImage {
config.Cmd = [ "/bin/hello" ]; config.Cmd = [ "/bin/hello" ];
} }
]]></programlisting> ]]></programlisting>
<para> <para>
and now the Docker CLI will display a reasonable date and and now the Docker CLI will display a reasonable date and sort the images
sort the images as expected: as expected:
<screen><![CDATA[ <screen><![CDATA[
$ docker image list $ docker image list
REPOSITORY TAG IMAGE ID CREATED SIZE REPOSITORY TAG IMAGE ID CREATED SIZE
hello latest de2bf4786de6 About a minute ago 25.2MB hello latest de2bf4786de6 About a minute ago 25.2MB
]]></screen> ]]></screen>
however, the produced images will not be binary reproducible. however, the produced images will not be binary reproducible.
</para> </para>
</example> </example>
</section> </section>
<section xml:id="ssec-pkgs-dockerTools-buildLayeredImage"> <section xml:id="ssec-pkgs-dockerTools-buildLayeredImage">
<title>buildLayeredImage</title> <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>24</literal>
</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dockerTools-buildLayeredImage-arg-contents">
<title>Behavior of <varname>contents</varname> in the final image</title>
<para> <para>
Create a Docker image with many of the store paths being on their own layer Each path directly listed in <varname>contents</varname> will have a
to improve sharing between images. symlink in the root of the image.
</para> </para>
<variablelist> <para>
<varlistentry> For example:
<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>24</literal>
</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[ <programlisting><![CDATA[
pkgs.dockerTools.buildLayeredImage { pkgs.dockerTools.buildLayeredImage {
name = "hello"; name = "hello";
contents = [ pkgs.hello ]; contents = [ pkgs.hello ];
} }
]]></programlisting> ]]></programlisting>
will create symlinks for all the paths in the <literal>hello</literal> will create symlinks for all the paths in the <literal>hello</literal>
package: package:
<screen><![CDATA[ <screen><![CDATA[
/bin/hello -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello /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/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 /share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo
]]></screen> ]]></screen>
</para> </para>
</section> </section>
<section xml:id="dockerTools-buildLayeredImage-arg-config"> <section xml:id="dockerTools-buildLayeredImage-arg-config">
<title>Automatic inclusion of <varname>config</varname> references</title> <title>Automatic inclusion of <varname>config</varname> references</title>
<para> <para>
The closure of <varname>config</varname> is automatically included in the The closure of <varname>config</varname> is automatically included in the
closure of the final image. closure of the final image.
</para> </para>
<para> <para>
This allows you to make very simple Docker images with very little code. This allows you to make very simple Docker images with very little code.
This container will start up and run <command>hello</command>: This container will start up and run <command>hello</command>:
<programlisting><![CDATA[ <programlisting><![CDATA[
pkgs.dockerTools.buildLayeredImage { pkgs.dockerTools.buildLayeredImage {
name = "hello"; name = "hello";
config.Cmd = [ "${pkgs.hello}/bin/hello" ]; config.Cmd = [ "${pkgs.hello}/bin/hello" ];
} }
]]></programlisting> ]]></programlisting>
</para> </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>
<section xml:id="ssec-pkgs-dockerTools-fetchFromRegistry"> <section xml:id="dockerTools-buildLayeredImage-arg-maxLayers">
<title>pullImage</title> <title>Adjusting <varname>maxLayers</varname></title>
<para> <para>
This function is analogous to the <command>docker pull</command> command, Increasing the <varname>maxLayers</varname> increases the number of layers
in that can be used to pull a Docker image from a Docker registry. By which have a chance to be shared between different images.
default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is
used to pull images.
</para> </para>
<para> <para>
Its parameters are described in the example below: Modern Docker installations support up to 128 layers, however older
versions support as few as 42.
</para> </para>
<example xml:id='ex-dockerTools-pullImage'> <para>
<title>Docker pull</title> 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 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> <programlisting>
pullImage { pullImage {
imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' /> imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' />
@ -424,86 +423,86 @@ pullImage {
arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' /> arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' />
} }
</programlisting> </programlisting>
</example> </example>
<calloutlist> <calloutlist>
<callout arearefs='ex-dockerTools-pullImage-1'> <callout arearefs='ex-dockerTools-pullImage-1'>
<para> <para>
<varname>imageName</varname> specifies the name of the image to be <varname>imageName</varname> specifies the name of the image to be
downloaded, which can also include the registry namespace (e.g. downloaded, which can also include the registry namespace (e.g.
<literal>nixos</literal>). This argument is required. <literal>nixos</literal>). This argument is required.
</para> </para>
</callout> </callout>
<callout arearefs='ex-dockerTools-pullImage-2'> <callout arearefs='ex-dockerTools-pullImage-2'>
<para> <para>
<varname>imageDigest</varname> specifies the digest of the image to be <varname>imageDigest</varname> specifies the digest of the image to be
downloaded. Skopeo can be used to get the digest of an image, with its downloaded. Skopeo can be used to get the digest of an image, with its
<varname>inspect</varname> subcommand. Since a given <varname>inspect</varname> subcommand. Since a given
<varname>imageName</varname> may transparently refer to a manifest list <varname>imageName</varname> may transparently refer to a manifest list of
of images which support multiple architectures and/or operating systems, images which support multiple architectures and/or operating systems,
supply the `--override-os` and `--override-arch` arguments to specify supply the `--override-os` and `--override-arch` arguments to specify
exactly which image you want. By default it will match the OS and exactly which image you want. By default it will match the OS and
architecture of the host the command is run on. architecture of the host the command is run on.
<programlisting> <programlisting>
$ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'" $ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'"
sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
</programlisting> </programlisting>
This argument is required. This argument is required.
</para>
</callout>
<callout arearefs='ex-dockerTools-pullImage-3'>
<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-4'>
<para>
<varname>sha256</varname> is the checksum of the whole fetched image.
This argument is required.
</para>
</callout>
<callout arearefs='ex-dockerTools-pullImage-5'>
<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-6'>
<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>
</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 can 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> </para>
</note> </callout>
<callout arearefs='ex-dockerTools-pullImage-3'>
<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-4'>
<para>
<varname>sha256</varname> is the checksum of the whole fetched image. This
argument is required.
</para>
</callout>
<callout arearefs='ex-dockerTools-pullImage-5'>
<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-6'>
<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>
</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 can 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> <para>
The parameters of <varname>exportImage</varname> are the following: Using this function requires the <literal>kvm</literal> device to be
available.
</para> </para>
</note>
<example xml:id='ex-dockerTools-exportImage'> <para>
<title>Docker export</title> The parameters of <varname>exportImage</varname> are the following:
</para>
<example xml:id='ex-dockerTools-exportImage'>
<title>Docker export</title>
<programlisting> <programlisting>
exportImage { exportImage {
fromImage = someLayeredImage; fromImage = someLayeredImage;
@ -513,34 +512,33 @@ exportImage {
name = someLayeredImage.name; name = someLayeredImage.name;
} }
</programlisting> </programlisting>
</example> </example>
<para> <para>
The parameters relative to the base image have the same synopsis as The parameters relative to the base image have the same synopsis as
described in <xref linkend='ssec-pkgs-dockerTools-buildImage'/>, except described in <xref linkend='ssec-pkgs-dockerTools-buildImage'/>, except that
that <varname>fromImage</varname> is the only required argument in this <varname>fromImage</varname> is the only required argument in this case.
case. </para>
</para>
<para> <para>
The <varname>name</varname> argument is the name of the derivation output, The <varname>name</varname> argument is the name of the derivation output,
which defaults to <varname>fromImage.name</varname>. which defaults to <varname>fromImage.name</varname>.
</para> </para>
</section> </section>
<section xml:id="ssec-pkgs-dockerTools-shadowSetup"> <section xml:id="ssec-pkgs-dockerTools-shadowSetup">
<title>shadowSetup</title> <title>shadowSetup</title>
<para> <para>
This constant string is a helper for setting up the base files for managing 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 users and groups, only if such files don't exist already. It is suitable for
for being used in a <varname>runAsRoot</varname> being used in a <varname>runAsRoot</varname>
<xref linkend='ex-dockerTools-buildImage-runAsRoot'/> script for cases like <xref linkend='ex-dockerTools-buildImage-runAsRoot'/> script for cases like
in the example below: in the example below:
</para> </para>
<example xml:id='ex-dockerTools-shadowSetup'> <example xml:id='ex-dockerTools-shadowSetup'>
<title>Shadow base files</title> <title>Shadow base files</title>
<programlisting> <programlisting>
buildImage { buildImage {
name = "shadow-basic"; name = "shadow-basic";
@ -555,12 +553,12 @@ buildImage {
''; '';
} }
</programlisting> </programlisting>
</example> </example>
<para> <para>
Creating base files like <literal>/etc/passwd</literal> or Creating base files like <literal>/etc/passwd</literal> or
<literal>/etc/login.defs</literal> are necessary for shadow-utils to <literal>/etc/login.defs</literal> are necessary for shadow-utils to
manipulate users and groups. manipulate users and groups.
</para> </para>
</section>
</section> </section>
</section>

228
doc/functions/fhs-environments.xml
View File

@ -2,116 +2,114 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-fhs-environments"> xml:id="sec-fhs-environments">
<title>buildFHSUserEnv</title> <title>buildFHSUserEnv</title>
<para> <para>
<function>buildFHSUserEnv</function> provides a way to build and run <function>buildFHSUserEnv</function> provides a way to build and run
FHS-compatible lightweight sandboxes. It creates an isolated root with bound FHS-compatible lightweight sandboxes. It creates an isolated root with bound
<filename>/nix/store</filename>, so its footprint in terms of disk space <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 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 unfeasible to patch for NixOS -- 3rd-party source trees with FHS assumptions,
assumptions, games distributed as tarballs, software with integrity checking games distributed as tarballs, software with integrity checking and/or
and/or external self-updated binaries. It uses Linux namespaces feature to external self-updated binaries. It uses Linux namespaces feature to create
create temporary lightweight environments which are destroyed after all temporary lightweight environments which are destroyed after all child
child processes exit, without root user rights requirement. Accepted processes exit, without root user rights requirement. Accepted arguments are:
arguments are: </para>
</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<literal>name</literal> <literal>name</literal>
</term> </term>
<listitem> <listitem>
<para> <para>
Environment name. Environment name.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<literal>targetPkgs</literal> <literal>targetPkgs</literal>
</term> </term>
<listitem> <listitem>
<para> <para>
Packages to be installed for the main host's architecture (i.e. x86_64 on 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. x86_64 installations). Along with libraries binaries are also installed.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<literal>multiPkgs</literal> <literal>multiPkgs</literal>
</term> </term>
<listitem> <listitem>
<para> <para>
Packages to be installed for all architectures supported by a host (i.e. 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 i686 and x86_64 on x86_64 installations). Only libraries are installed by
default. default.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<literal>extraBuildCommands</literal> <literal>extraBuildCommands</literal>
</term> </term>
<listitem> <listitem>
<para> <para>
Additional commands to be executed for finalizing the directory Additional commands to be executed for finalizing the directory structure.
structure. </para>
</para> </listitem>
</listitem> </varlistentry>
</varlistentry> <varlistentry>
<varlistentry> <term>
<term> <literal>extraBuildCommandsMulti</literal>
<literal>extraBuildCommandsMulti</literal> </term>
</term> <listitem>
<listitem> <para>
<para> Like <literal>extraBuildCommands</literal>, but executed only on multilib
Like <literal>extraBuildCommands</literal>, but executed only on multilib architectures.
architectures. </para>
</para> </listitem>
</listitem> </varlistentry>
</varlistentry> <varlistentry>
<varlistentry> <term>
<term> <literal>extraOutputsToInstall</literal>
<literal>extraOutputsToInstall</literal> </term>
</term> <listitem>
<listitem> <para>
<para> Additional derivation outputs to be linked for both target and
Additional derivation outputs to be linked for both target and multi-architecture packages.
multi-architecture packages. </para>
</para> </listitem>
</listitem> </varlistentry>
</varlistentry> <varlistentry>
<varlistentry> <term>
<term> <literal>extraInstallCommands</literal>
<literal>extraInstallCommands</literal> </term>
</term> <listitem>
<listitem> <para>
<para> Additional commands to be executed for finalizing the derivation with
Additional commands to be executed for finalizing the derivation with runner script.
runner script. </para>
</para> </listitem>
</listitem> </varlistentry>
</varlistentry> <varlistentry>
<varlistentry> <term>
<term> <literal>runScript</literal>
<literal>runScript</literal> </term>
</term> <listitem>
<listitem> <para>
<para> A command that would be executed inside the sandbox and passed all the
A command that would be executed inside the sandbox and passed all the command line arguments. It defaults to <literal>bash</literal>.
command line arguments. It defaults to <literal>bash</literal>. </para>
</para> </listitem>
</listitem> </varlistentry>
</varlistentry> </variablelist>
</variablelist>
<para> <para>
One can create a simple environment using a <literal>shell.nix</literal> One can create a simple environment using a <literal>shell.nix</literal> like
like that: that:
</para> </para>
<programlisting><![CDATA[ <programlisting><![CDATA[
{ pkgs ? import <nixpkgs> {} }: { pkgs ? import <nixpkgs> {} }:
@ -134,11 +132,11 @@
}).env }).env
]]></programlisting> ]]></programlisting>
<para> <para>
Running <literal>nix-shell</literal> would then drop you into a shell with Running <literal>nix-shell</literal> would then drop you into a shell with
these libraries and binaries available. You can use this to run these libraries and binaries available. You can use this to run closed-source
closed-source applications which expect FHS structure without hassles: applications which expect FHS structure without hassles: simply change
simply change <literal>runScript</literal> to the application path, e.g. <literal>runScript</literal> to the application path, e.g.
<filename>./bin/start.sh</filename> -- relative paths are supported. <filename>./bin/start.sh</filename> -- relative paths are supported.
</para> </para>
</section> </section>

73
doc/functions/generators.xml
View File

@ -2,33 +2,32 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-generators"> xml:id="sec-generators">
<title>Generators</title> <title>Generators</title>
<para> <para>
Generators are functions that create file formats from nix data structures, Generators are functions that create file formats from nix data structures,
e. g. for configuration files. There are generators available for: e. g. for configuration files. There are generators available for:
<literal>INI</literal>, <literal>JSON</literal> and <literal>YAML</literal> <literal>INI</literal>, <literal>JSON</literal> and <literal>YAML</literal>
</para> </para>
<para> <para>
All generators follow a similar call interface: <code>generatorName All generators follow a similar call interface: <code>generatorName
configFunctions data</code>, where <literal>configFunctions</literal> is an configFunctions data</code>, where <literal>configFunctions</literal> is an
attrset of user-defined functions that format nested parts of the content. 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 They each have common defaults, so often they do not need to be set manually.
manually. An example is <code>mkSectionName ? (name: libStr.escape [ "[" "]" An example is <code>mkSectionName ? (name: libStr.escape [ "[" "]" ]
] name)</code> from the <literal>INI</literal> generator. It receives the name)</code> from the <literal>INI</literal> generator. It receives the name
name of a section and sanitizes it. The default of a section and sanitizes it. The default <literal>mkSectionName</literal>
<literal>mkSectionName</literal> escapes <literal>[</literal> and escapes <literal>[</literal> and <literal>]</literal> with a backslash.
<literal>]</literal> with a backslash. </para>
</para>
<para> <para>
Generators can be fine-tuned to produce exactly the file format required by 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 your application/service. One example is an INI-file format which uses
<literal>: </literal> as separator, the strings <literal>: </literal> as separator, the strings
<literal>"yes"</literal>/<literal>"no"</literal> as boolean values and <literal>"yes"</literal>/<literal>"no"</literal> as boolean values and
requires all string values to be quoted: requires all string values to be quoted:
</para> </para>
<programlisting> <programlisting>
with lib; with lib;
@ -60,9 +59,9 @@ in customToINI {
} }
</programlisting> </programlisting>
<para> <para>
This will produce the following INI file as nix string: This will produce the following INI file as nix string:
</para> </para>
<programlisting> <programlisting>
[main] [main]
@ -76,15 +75,15 @@ str\:ange:"very::strange"
merge:"diff3" merge:"diff3"
</programlisting> </programlisting>
<note> <note>
<para>
Nix store paths can be converted to strings by enclosing a derivation
attribute like so: <code>"${drv}"</code>.
</para>
</note>
<para> <para>
Detailed documentation for each generator can be found in Nix store paths can be converted to strings by enclosing a derivation
<literal>lib/generators.nix</literal>. attribute like so: <code>"${drv}"</code>.
</para> </para>
</section> </note>
<para>
Detailed documentation for each generator can be found in
<literal>lib/generators.nix</literal>.
</para>
</section>

284
doc/functions/overrides.xml
View File

@ -2,28 +2,28 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-overrides"> xml:id="sec-overrides">
<title>Overriding</title> <title>Overriding</title>
<para>
Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g.
derivation attributes, the results of derivations or even the whole package
set.
</para>
<section xml:id="sec-pkg-override">
<title>&lt;pkg&gt;.override</title>
<para> <para>
Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g. The function <varname>override</varname> is usually available for all the
derivation attributes, the results of derivations or even the whole package derivations in the nixpkgs expression (<varname>pkgs</varname>).
set.
</para> </para>
<section xml:id="sec-pkg-override"> <para>
<title>&lt;pkg&gt;.override</title> It is used to override the arguments passed to a function.
</para>
<para> <para>
The function <varname>override</varname> is usually available for all the Example usages:
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> <programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting>
<programlisting> <programlisting>
import pkgs.path { overlays = [ (self: super: { import pkgs.path { overlays = [ (self: super: {
@ -35,105 +35,103 @@ mypkg = pkgs.callPackage ./mypkg.nix {
mydep = pkgs.mydep.override { ... }; mydep = pkgs.mydep.override { ... };
} }
</programlisting> </programlisting>
</para> </para>
<para> <para>
In the first example, <varname>pkgs.foo</varname> is the result of a In the first example, <varname>pkgs.foo</varname> is the result of a
function call with some default arguments, usually a derivation. Using function call with some default arguments, usually a derivation. Using
<varname>pkgs.foo.override</varname> will call the same function with the <varname>pkgs.foo.override</varname> will call the same function with the
given new arguments. given new arguments.
</para> </para>
</section> </section>
<section xml:id="sec-pkg-overrideAttrs"> <section xml:id="sec-pkg-overrideAttrs">
<title>&lt;pkg&gt;.overrideAttrs</title> <title>&lt;pkg&gt;.overrideAttrs</title>
<para> <para>
The function <varname>overrideAttrs</varname> allows overriding the The function <varname>overrideAttrs</varname> allows overriding the
attribute set passed to a <varname>stdenv.mkDerivation</varname> call, attribute set passed to a <varname>stdenv.mkDerivation</varname> call,
producing a new derivation based on the original one. This function is producing a new derivation based on the original one. This function is
available on all derivations produced by the available on all derivations produced by the
<varname>stdenv.mkDerivation</varname> function, which is most packages in <varname>stdenv.mkDerivation</varname> function, which is most packages in
the nixpkgs expression <varname>pkgs</varname>. the nixpkgs expression <varname>pkgs</varname>.
</para> </para>
<para> <para>
Example usage: Example usage:
<programlisting> <programlisting>
helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec { helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec {
separateDebugInfo = true; separateDebugInfo = true;
}); });
</programlisting> </programlisting>
</para> </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> <para>
In the above example, the <varname>separateDebugInfo</varname> attribute is Note that <varname>separateDebugInfo</varname> is processed only by the
overridden to be true, thus building debug info for <varname>stdenv.mkDerivation</varname> function, not the generated, raw Nix
<varname>helloWithDebug</varname>, while all other attributes will be derivation. Thus, using <varname>overrideDerivation</varname> will not work
retained from the original <varname>hello</varname> package. 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>sdenv.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 involves less typing.
</para> </para>
</note>
</section>
<section xml:id="sec-pkg-overrideDerivation">
<title>&lt;pkg&gt;.overrideDerivation</title>
<warning>
<para> <para>
The argument <varname>oldAttrs</varname> is conventionally used to refer to You should prefer <varname>overrideAttrs</varname> in almost all cases, see
the attr set originally passed to <varname>stdenv.mkDerivation</varname>. 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> </para>
</warning>
<note> <warning>
<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>sdenv.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 involves less typing.
</para>
</note>
</section>
<section xml:id="sec-pkg-overrideDerivation">
<title>&lt;pkg&gt;.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> <para>
The function <varname>overrideDerivation</varname> creates a new derivation Do not use this function in Nixpkgs as it evaluates a Derivation before
based on an existing one by overriding the original's attributes with the modifying it, which breaks package abstraction and removes error-checking
attribute set produced by the specified function. This function is of function arguments. In addition, this evaluation-per-function
available on all derivations defined using the application incurs a performance penalty, which can become a problem if
<varname>makeOverridable</varname> function. Most standard many overrides are used. It is only intended for ad-hoc customisation, such
derivation-producing functions, such as as in <filename>~/.config/nixpkgs/config.nix</filename>.
<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>
</warning>
<para> <para>
Example usage: 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> <programlisting>
mySed = pkgs.gnused.overrideDerivation (oldAttrs: { mySed = pkgs.gnused.overrideDerivation (oldAttrs: {
name = "sed-4.2.2-pre"; name = "sed-4.2.2-pre";
@ -144,62 +142,62 @@ mySed = pkgs.gnused.overrideDerivation (oldAttrs: {
patches = []; patches = [];
}); });
</programlisting> </programlisting>
</para> </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> <para>
In the above example, the <varname>name</varname>, <varname>src</varname>, A package's attributes are evaluated *before* being modified by the
and <varname>patches</varname> of the derivation will be overridden, while <varname>overrideDerivation</varname> function. For example, the
all other attributes will be retained from the original derivation. <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> </para>
</note>
</section>
<para> <section xml:id="sec-lib-makeOverridable">
The argument <varname>oldAttrs</varname> is used to refer to the attribute <title>lib.makeOverridable</title>
set of the original derivation.
</para>
<note> <para>
<para> The function <varname>lib.makeOverridable</varname> is used to make the
A package's attributes are evaluated *before* being modified by the result of a function easily customizable. This utility only makes sense for
<varname>overrideDerivation</varname> function. For example, the functions that accept an argument set and return an attribute set.
<varname>name</varname> attribute reference in <varname>url = </para>
"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"> <para>
<title>lib.makeOverridable</title> Example usage:
<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> <programlisting>
f = { a, b }: { result = a+b; }; f = { a, b }: { result = a+b; };
c = lib.makeOverridable f { a = 1; b = 2; }; c = lib.makeOverridable f { a = 1; b = 2; };
</programlisting> </programlisting>
</para> </para>
<para> <para>
The variable <varname>c</varname> is the value of the <varname>f</varname> The variable <varname>c</varname> is the value of the <varname>f</varname>
function applied with some default arguments. Hence the value of function applied with some default arguments. Hence the value of
<varname>c.result</varname> is <literal>3</literal>, in this example. <varname>c.result</varname> is <literal>3</literal>, in this example.
</para> </para>
<para> <para>
The variable <varname>c</varname> however also has some additional The variable <varname>c</varname> however also has some additional
functions, like <link linkend="sec-pkg-override">c.override</link> which functions, like <link linkend="sec-pkg-override">c.override</link> which can
can be used to override the default arguments. In this example the value of be used to override the default arguments. In this example the value of
<varname>(c.override { a = 4; }).result</varname> is 6. <varname>(c.override { a = 4; }).result</varname> is 6.
</para> </para>
</section>
</section> </section>
</section>

21
doc/functions/shell.xml
View File

@ -2,19 +2,18 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-pkgs-mkShell"> xml:id="sec-pkgs-mkShell">
<title>pkgs.mkShell</title> <title>pkgs.mkShell</title>
<para> <para>
<function>pkgs.mkShell</function> is a special kind of derivation <function>pkgs.mkShell</function> is a special kind of derivation that is
that is only useful when using it combined with only useful when using it combined with <command>nix-shell</command>. It will
<command>nix-shell</command>. It will in fact fail to instantiate in fact fail to instantiate when invoked with <command>nix-build</command>.
when invoked with <command>nix-build</command>. </para>
</para>
<section xml:id="sec-pkgs-mkShell-usage"> <section xml:id="sec-pkgs-mkShell-usage">
<title>Usage</title> <title>Usage</title>
<programlisting><![CDATA[ <programlisting><![CDATA[
{ pkgs ? import <nixpkgs> {} }: { pkgs ? import <nixpkgs> {} }:
pkgs.mkShell { pkgs.mkShell {
# this will make all the build inputs from hello and gnutar # this will make all the build inputs from hello and gnutar
@ -23,5 +22,5 @@ pkgs.mkShell {
buildInputs = [ pkgs.gnumake ]; buildInputs = [ pkgs.gnumake ];
} }
]]></programlisting> ]]></programlisting>
</section> </section>
</section> </section>

74
doc/package-notes.xml
View File

@ -671,8 +671,9 @@ overrides = self: super: rec {
plugins = with availablePlugins; [ python perl ]; plugins = with availablePlugins; [ python perl ];
} }
}</programlisting> }</programlisting>
If the <literal>configure</literal> function returns an attrset without the <literal>plugins</literal> If the <literal>configure</literal> function returns an attrset without the
attribute, <literal>availablePlugins</literal> will be used automatically. <literal>plugins</literal> attribute, <literal>availablePlugins</literal>
will be used automatically.
</para> </para>
<para> <para>
@ -706,9 +707,11 @@ overrides = self: super: rec {
}; } }; }
</programlisting> </programlisting>
</para> </para>
<para> <para>
WeeChat allows to set defaults on startup using the <literal>--run-command</literal>. WeeChat allows to set defaults on startup using the
The <literal>configure</literal> method can be used to pass commands to the program: <literal>--run-command</literal>. The <literal>configure</literal> method
can be used to pass commands to the program:
<programlisting>weechat.override { <programlisting>weechat.override {
configure = { availablePlugins, ... }: { configure = { availablePlugins, ... }: {
init = '' init = ''
@ -717,12 +720,14 @@ overrides = self: super: rec {
''; '';
}; };
}</programlisting> }</programlisting>
Further values can be added to the list of commands when running Further values can be added to the list of commands when running
<literal>weechat --run-command "your-commands"</literal>. <literal>weechat --run-command "your-commands"</literal>.
</para> </para>
<para> <para>
Additionally it's possible to specify scripts to be loaded when starting <literal>weechat</literal>. Additionally it's possible to specify scripts to be loaded when starting
These will be loaded before the commands from <literal>init</literal>: <literal>weechat</literal>. These will be loaded before the commands from
<literal>init</literal>:
<programlisting>weechat.override { <programlisting>weechat.override {
configure = { availablePlugins, ... }: { configure = { availablePlugins, ... }: {
scripts = with pkgs.weechatScripts; [ scripts = with pkgs.weechatScripts; [
@ -734,11 +739,13 @@ overrides = self: super: rec {
}; };
}</programlisting> }</programlisting>
</para> </para>
<para> <para>
In <literal>nixpkgs</literal> there's a subpackage which contains derivations for In <literal>nixpkgs</literal> there's a subpackage which contains
WeeChat scripts. Such derivations expect a <literal>passthru.scripts</literal> attribute derivations for WeeChat scripts. Such derivations expect a
which contains a list of all scripts inside the store path. Furthermore all scripts <literal>passthru.scripts</literal> attribute which contains a list of all
have to live in <literal>$out/share</literal>. An exemplary derivation looks like this: scripts inside the store path. Furthermore all scripts have to live in
<literal>$out/share</literal>. An exemplary derivation looks like this:
<programlisting>{ stdenv, fetchurl }: <programlisting>{ stdenv, fetchurl }:
stdenv.mkDerivation { stdenv.mkDerivation {
@ -817,20 +824,26 @@ citrix_receiver.override {
<section xml:id="sec-ibus-typing-booster"> <section xml:id="sec-ibus-typing-booster">
<title>ibus-engines.typing-booster</title> <title>ibus-engines.typing-booster</title>
<para>This package is an ibus-based completion method to speed up typing.</para> <para>
This package is an ibus-based completion method to speed up typing.
</para>
<section xml:id="sec-ibus-typing-booster-activate"> <section xml:id="sec-ibus-typing-booster-activate">
<title>Activating the engine</title> <title>Activating the engine</title>
<para> <para>
IBus needs to be configured accordingly to activate <literal>typing-booster</literal>. The configuration IBus needs to be configured accordingly to activate
depends on the desktop manager in use. For detailed instructions, please refer to the <literal>typing-booster</literal>. The configuration depends on the desktop
<link xlink:href="https://mike-fabian.github.io/ibus-typing-booster/documentation.html">upstream docs</link>. manager in use. For detailed instructions, please refer to the
<link xlink:href="https://mike-fabian.github.io/ibus-typing-booster/documentation.html">upstream
docs</link>.
</para> </para>
<para> <para>
On NixOS you need to explicitly enable <literal>ibus</literal> with given engines On NixOS you need to explicitly enable <literal>ibus</literal> with given
before customizing your desktop to use <literal>typing-booster</literal>. This can be achieved engines before customizing your desktop to use
using the <literal>ibus</literal> module: <literal>typing-booster</literal>. This can be achieved using the
<literal>ibus</literal> module:
<programlisting>{ pkgs, ... }: { <programlisting>{ pkgs, ... }: {
i18n.inputMethod = { i18n.inputMethod = {
enabled = "ibus"; enabled = "ibus";
@ -844,17 +857,20 @@ citrix_receiver.override {
<title>Using custom hunspell dictionaries</title> <title>Using custom hunspell dictionaries</title>
<para> <para>
The IBus engine is based on <literal>hunspell</literal> to support completion in many languages. The IBus engine is based on <literal>hunspell</literal> to support
By default the dictionaries <literal>de-de</literal>, <literal>en-us</literal>, <literal>es-es</literal>, completion in many languages. By default the dictionaries
<literal>it-it</literal>, <literal>sv-se</literal> and <literal>sv-fi</literal> <literal>de-de</literal>, <literal>en-us</literal>,
are in use. To add another dictionary, the package can be overridden like this: <literal>es-es</literal>, <literal>it-it</literal>,
<literal>sv-se</literal> and <literal>sv-fi</literal> are in use. To add
another dictionary, the package can be overridden like this:
<programlisting>ibus-engines.typing-booster.override { <programlisting>ibus-engines.typing-booster.override {
langs = [ "de-at" "en-gb" ]; langs = [ "de-at" "en-gb" ];
}</programlisting> }</programlisting>
</para> </para>
<para> <para>
<emphasis>Note: each language passed to <literal>langs</literal> must be an attribute name in <emphasis>Note: each language passed to <literal>langs</literal> must be an
<literal>pkgs.hunspellDicts</literal>.</emphasis> attribute name in <literal>pkgs.hunspellDicts</literal>.</emphasis>
</para> </para>
</section> </section>
@ -862,10 +878,12 @@ citrix_receiver.override {
<title>Built-in emoji picker</title> <title>Built-in emoji picker</title>
<para> <para>
The <literal>ibus-engines.typing-booster</literal> package contains a program The <literal>ibus-engines.typing-booster</literal> package contains a
named <literal>emoji-picker</literal>. To display all emojis correctly, program named <literal>emoji-picker</literal>. To display all emojis
a special font such as <literal>noto-fonts-emoji</literal> is needed: correctly, a special font such as <literal>noto-fonts-emoji</literal> is
needed:
</para> </para>
<para> <para>
On NixOS it can be installed using the following expression: On NixOS it can be installed using the following expression:
<programlisting>{ pkgs, ... }: { <programlisting>{ pkgs, ... }: {