commit
e3082c313b
@ -1,8 +0,0 @@ |
||||
;;; Directory Local Variables |
||||
;;; For more information see (info "(emacs) Directory Variables") |
||||
|
||||
((nil |
||||
(bug-reference-bug-regexp . "\\(\\(?:[Ii]ssue \\|[Ff]ixe[ds] \\|[Rr]esolve[ds]? \\|[Cc]lose[ds]? \\|[Pp]\\(?:ull [Rr]equest\\|[Rr]\\) \\|(\\)#\\([0-9]+\\))?\\)") |
||||
(bug-reference-url-format . "https://github.com/NixOS/nixpkgs/issues/%s")) |
||||
(nix-mode |
||||
(tab-width . 2))) |
@ -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-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> |
@ -0,0 +1,564 @@ |
||||
<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 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> |
||||
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' /> |
||||
#!${stdenv.shell} |
||||
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 list images</command>, the newly created images will be |
||||
listed like this: |
||||
</para> |
||||
<screen><![CDATA[ |
||||
$ docker image list |
||||
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 image list |
||||
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>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[ |
||||
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 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' /> |
||||
finalImageTag = "1.11"; <co xml:id='ex-dockerTools-pullImage-3' /> |
||||
sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-4' /> |
||||
os = "linux"; <co xml:id='ex-dockerTools-pullImage-5' /> |
||||
arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' /> |
||||
} |
||||
</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. Skopeo can be used to get the digest of an image, with its |
||||
<varname>inspect</varname> subcommand. Since a given |
||||
<varname>imageName</varname> may transparently refer to a manifest list of |
||||
images which support multiple architectures and/or operating systems, |
||||
supply the `--override-os` and `--override-arch` 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. |
||||
<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'" |
||||
sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b |
||||
</programlisting> |
||||
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> |
||||
</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 = '' |
||||
#!${stdenv.shell} |
||||
${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> are necessary for shadow-utils to |
||||
manipulate users and groups. |
||||
</para> |
||||
</section> |
||||
</section> |
@ -0,0 +1,142 @@ |
||||
<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> |
@ -0,0 +1,15 @@ |
||||
<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" /> |
||||
</section> |
@ -0,0 +1,117 @@ |
||||
<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> |
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,212 @@ |
||||
<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> |
@ -0,0 +1,26 @@ |
||||
<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> |
@ -0,0 +1,85 @@ |
||||
{ pkgs ? (import ./.. { }), nixpkgs ? { }}: |
||||
let |
||||
revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master"); |
||||
|
||||
libDefPos = set: |
||||
builtins.map |
||||
(name: { |
||||
name = name; |
||||
location = builtins.unsafeGetAttrPos name set; |
||||
}) |
||||
(builtins.attrNames set); |
||||
|
||||
libset = toplib: |
||||
builtins.map |
||||
(subsetname: { |
||||
subsetname = subsetname; |
||||
functions = libDefPos toplib."${subsetname}"; |
||||
}) |
||||
(builtins.filter |
||||
(name: builtins.isAttrs toplib."${name}") |
||||
(builtins.attrNames toplib)); |
||||
|
||||
nixpkgsLib = pkgs.lib; |
||||
|
||||
flattenedLibSubset = { subsetname, functions }: |
||||
builtins.map |
||||
(fn: { |
||||
name = "lib.${subsetname}.${fn.name}"; |
||||
value = fn.location; |
||||
}) |
||||
functions; |
||||
|
||||
locatedlibsets = libs: builtins.map flattenedLibSubset (libset libs); |
||||
removeFilenamePrefix = prefix: filename: |
||||
let |
||||
prefixLen = (builtins.stringLength prefix) + 1; # +1 to remove the leading / |
||||
filenameLen = builtins.stringLength filename; |
||||
substr = builtins.substring prefixLen filenameLen filename; |
||||
in substr; |
||||
|
||||
removeNixpkgs = removeFilenamePrefix (builtins.toString pkgs.path); |
||||
|
||||
liblocations = |
||||
builtins.filter |
||||
(elem: elem.value != null) |
||||
(nixpkgsLib.lists.flatten |
||||
(locatedlibsets nixpkgsLib)); |
||||
|
||||
fnLocationRelative = { name, value }: |
||||
{ |
||||
inherit name; |
||||
value = value // { file = removeNixpkgs value.file; }; |
||||
}; |
||||
|
||||
relativeLocs = (builtins.map fnLocationRelative liblocations); |
||||
sanitizeId = builtins.replaceStrings |
||||
[ "'" ] |
||||
[ "-prime" ]; |
||||
|
||||
urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}"; |
||||
xmlstrings = (nixpkgsLib.strings.concatMapStrings |
||||
({ name, value }: |
||||
'' |
||||
<section><title>${name}</title> |
||||
<para xml:id="${sanitizeId name}"> |
||||
Located at |
||||
<link |
||||
xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link> |
||||
in <literal><nixpkgs></literal>. |
||||
</para> |
||||
</section> |
||||
'') |
||||
relativeLocs); |
||||
|
||||
in pkgs.writeText |
||||
"locations.xml" |
||||
'' |
||||
<section xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
version="5"> |
||||
<title>All the locations for every lib function</title> |
||||
<para>This file is only for inclusion by other files.</para> |
||||
${xmlstrings} |
||||
</section> |
||||
'' |
@ -1,5 +1,5 @@ |
||||
{ pkgs ? import ../. {} }: |
||||
(import ./default.nix).overrideAttrs (x: { |
||||
(import ./default.nix {}).overrideAttrs (x: { |
||||
buildInputs = x.buildInputs ++ [ pkgs.xmloscopy pkgs.ruby ]; |
||||
|
||||
}) |
||||
|
@ -1,22 +0,0 @@ |
||||
--- |
||||
title: pkgs.mkShell |
||||
author: zimbatm |
||||
date: 2017-10-30 |
||||
--- |
||||
|
||||
# mkShell |
||||
|
||||
pkgs.mkShell is a special kind of derivation that is only useful when using |
||||
it combined with nix-shell. It will in fact fail to instantiate when invoked |
||||
with nix-build. |
||||
|
||||
## Usage |
||||
|
||||
```nix |
||||
{ 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 ]; |
||||
} |
||||
``` |
@ -0,0 +1,44 @@ |
||||
{ lib }: |
||||
|
||||
rec { |
||||
|
||||
/* Print a trace message if pred is false. |
||||
Intended to be used to augment asserts with helpful error messages. |
||||
|
||||
Example: |
||||
assertMsg false "nope" |
||||
=> false |
||||
stderr> trace: nope |
||||
|
||||
assert (assertMsg ("foo" == "bar") "foo is not bar, silly"); "" |
||||
stderr> trace: foo is not bar, silly |
||||
stderr> assert failed at … |
||||
|
||||
Type: |
||||
assertMsg :: Bool -> String -> Bool |
||||
*/ |
||||
# TODO(Profpatsch): add tests that check stderr |
||||
assertMsg = pred: msg: |
||||
if pred |
||||
then true |
||||
else builtins.trace msg false; |
||||
|
||||
/* Specialized `assertMsg` for checking if val is one of the elements |
||||
of a list. Useful for checking enums. |
||||
|
||||
Example: |
||||
let sslLibrary = "libressl" |
||||
in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ] |
||||
=> false |
||||
stderr> trace: sslLibrary must be one of "openssl", "bearssl", but is: "libressl" |
||||
|
||||
Type: |
||||
assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool |
||||
*/ |
||||
assertOneOf = name: val: xs: assertMsg |
||||
(lib.elem val xs) |
||||
"${name} must be one of ${ |
||||
lib.generators.toPretty {} xs}, but is: ${ |
||||
lib.generators.toPretty {} val}"; |
||||
|
||||
} |
@ -0,0 +1,7 @@ |
||||
# Throws an error if any of our lib tests fail. |
||||
|
||||
let tests = [ "misc" "systems" ]; |
||||
all = builtins.concatLists (map (f: import (./. + "/${f}.nix")) tests); |
||||
in if all == [] |
||||
then null |
||||
else throw (builtins.toJSON all) |
@ -0,0 +1,37 @@ |
||||
<section xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
xmlns:xi="http://www.w3.org/2001/XInclude" |
||||
version="5.0" |
||||
xml:id="sec-debugging-nixos-tests"> |
||||
<title>Debugging NixOS tests</title> |
||||
|
||||
<para> |
||||
Tests may fail and infrastructure offers access to inspect machine state. |
||||
</para> |
||||
|
||||
<para> |
||||
To prevent test from stopping and cleaning up, insert a sleep command: |
||||
</para> |
||||
|
||||
<programlisting> |
||||
$machine->succeed("sleep 84000"); |
||||
</programlisting> |
||||
|
||||
<para> |
||||
As soon as machine starts run as root: |
||||
</para> |
||||
|
||||
<programlisting> |
||||
nix-shell -p socat --run "socat STDIO,raw,echo=0,escape=0x11 UNIX:/tmp/nix-build-vm-test-run-*.drv-0/vm-state-machine/backdoor" |
||||
</programlisting> |
||||
|
||||
<para> |
||||
You may need to find the correct path, replacing <literal>/tmp</literal>, |
||||
<literal>*</literal> or <literal>machine</literal>. |
||||
</para> |
||||
|
||||
<para> |
||||
Press "enter" to open up console and login as "root". After you're done, |
||||
press "ctrl-q" to exit the console. |
||||
</para> |
||||
</section> |
@ -0,0 +1,115 @@ |
||||
<?xml version="1.0"?> |
||||
|
||||
<xsl:stylesheet version="1.0" |
||||
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" |
||||
xmlns:str="http://exslt.org/strings" |
||||
xmlns:exsl="http://exslt.org/common" |
||||
xmlns:db="http://docbook.org/ns/docbook" |
||||
xmlns:nixos="tag:nixos.org" |
||||
extension-element-prefixes="str exsl"> |
||||
<xsl:output method='xml' encoding="UTF-8" /> |
||||
|
||||
<xsl:template match="@*|node()"> |
||||
<xsl:copy> |
||||
<xsl:apply-templates select="@*|node()" /> |
||||
</xsl:copy> |
||||
</xsl:template> |
||||
|
||||
<xsl:template name="break-up-description"> |
||||
<xsl:param name="input" /> |
||||
<xsl:param name="buffer" /> |
||||
|
||||
<!-- Every time we have two newlines following each other, we want to |
||||
break it into </para><para>. --> |
||||
<xsl:variable name="parbreak" select="'

'" /> |
||||
|
||||
<!-- Similar to "(head:tail) = input" in Haskell. --> |
||||
<xsl:variable name="head" select="$input[1]" /> |
||||
<xsl:variable name="tail" select="$input[position() > 1]" /> |
||||
|
||||
<xsl:choose> |
||||
<xsl:when test="$head/self::text() and contains($head, $parbreak)"> |
||||
<!-- If the haystack provided to str:split() directly starts or |
||||
ends with $parbreak, it doesn't generate a <token/> for that, |
||||
so we are doing this here. --> |
||||
<xsl:variable name="splitted-raw"> |
||||
<xsl:if test="starts-with($head, $parbreak)"><token /></xsl:if> |
||||
<xsl:for-each select="str:split($head, $parbreak)"> |
||||
<token><xsl:value-of select="node()" /></token> |
||||
</xsl:for-each> |
||||
<!-- Something like ends-with($head, $parbreak), but there is |
||||
no ends-with() in XSLT, so we need to use substring(). --> |
||||
<xsl:if test=" |
||||
substring($head, string-length($head) - |
||||
string-length($parbreak) + 1) = $parbreak |
||||
"><token /></xsl:if> |
||||
</xsl:variable> |
||||
<xsl:variable name="splitted" |
||||
select="exsl:node-set($splitted-raw)/token" /> |
||||
<!-- The buffer we had so far didn't contain any text nodes that |
||||
contain a $parbreak, so we can put the buffer along with the |
||||
first token of $splitted into a para element. --> |
||||
<para xmlns="http://docbook.org/ns/docbook"> |
||||
<xsl:apply-templates select="exsl:node-set($buffer)" /> |
||||
<xsl:apply-templates select="$splitted[1]/node()" /> |
||||
</para> |
||||
<!-- We have already emitted the first splitted result, so the |
||||
last result is going to be set as the new $buffer later |
||||
because its contents may not be directly followed up by a |
||||
$parbreak. --> |
||||
<xsl:for-each select="$splitted[position() > 1 |
||||
and position() < last()]"> |
||||
<para xmlns="http://docbook.org/ns/docbook"> |
||||
<xsl:apply-templates select="node()" /> |
||||
</para> |
||||
</xsl:for-each> |
||||
<xsl:call-template name="break-up-description"> |
||||
<xsl:with-param name="input" select="$tail" /> |
||||
<xsl:with-param name="buffer" select="$splitted[last()]/node()" /> |
||||
</xsl:call-template> |
||||
</xsl:when> |
||||
<!-- Either non-text node or one without $parbreak, which we just |
||||
want to buffer and continue recursing. --> |
||||
<xsl:when test="$input"> |
||||
<xsl:call-template name="break-up-description"> |
||||
<xsl:with-param name="input" select="$tail" /> |
||||
<!-- This essentially appends $head to $buffer. --> |
||||
<xsl:with-param name="buffer"> |
||||
<xsl:if test="$buffer"> |
||||
<xsl:for-each select="exsl:node-set($buffer)"> |
||||
<xsl:apply-templates select="." /> |
||||
</xsl:for-each> |
||||
</xsl:if> |
||||
<xsl:apply-templates select="$head" /> |
||||
</xsl:with-param> |
||||
</xsl:call-template> |
||||
</xsl:when> |
||||
<!-- No more $input, just put the remaining $buffer in a para. --> |
||||
<xsl:otherwise> |
||||
<para xmlns="http://docbook.org/ns/docbook"> |
||||
<xsl:apply-templates select="exsl:node-set($buffer)" /> |
||||
</para> |
||||
</xsl:otherwise> |
||||
</xsl:choose> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="nixos:option-description"> |
||||
<xsl:choose> |
||||
<!-- |
||||
Only process nodes that are comprised of a single <para/> element, |
||||
because if that's not the case the description already contains |
||||
</para><para> in between and we need no further processing. |
||||
--> |
||||
<xsl:when test="count(db:para) > 1"> |
||||
<xsl:apply-templates select="node()" /> |
||||
</xsl:when> |
||||
<xsl:otherwise> |
||||
<xsl:call-template name="break-up-description"> |
||||
<xsl:with-param name="input" |
||||
select="exsl:node-set(db:para/node())" /> |
||||
</xsl:call-template> |
||||
</xsl:otherwise> |
||||
</xsl:choose> |
||||
</xsl:template> |
||||
|
||||
</xsl:stylesheet> |
@ -0,0 +1,204 @@ |
||||
<section xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
xmlns:xi="http://www.w3.org/2001/XInclude" |
||||
version="5.0" |
||||
xml:id="sec-release-19.03"> |
||||
<title>Release 19.03 (“Koi”, 2019/03/??)</title> |
||||
|
||||
<section xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
xmlns:xi="http://www.w3.org/2001/XInclude" |
||||
version="5.0" |
||||
xml:id="sec-release-19.03-highlights"> |
||||
<title>Highlights</title> |
||||
|
||||
<para> |
||||
In addition to numerous new and upgraded packages, this release has the |
||||
following highlights: |
||||
</para> |
||||
|
||||
<itemizedlist> |
||||
<listitem> |
||||
<para /> |
||||
</listitem> |
||||
</itemizedlist> |
||||
</section> |
||||
|
||||
<section xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
xmlns:xi="http://www.w3.org/2001/XInclude" |
||||
version="5.0" |
||||
xml:id="sec-release-19.03-new-services"> |
||||
<title>New Services</title> |
||||
|
||||
<para> |
||||
The following new services were added since the last release: |
||||
</para> |
||||
|
||||
<itemizedlist> |
||||
<listitem> |
||||
<para /> |
||||
</listitem> |
||||
</itemizedlist> |
||||
</section> |
||||
|
||||
<section xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
xmlns:xi="http://www.w3.org/2001/XInclude" |
||||
version="5.0" |
||||
xml:id="sec-release-19.03-incompatibilities"> |
||||
<title>Backward Incompatibilities</title> |
||||
|
||||
<para> |
||||
When upgrading from a previous release, please be aware of the following |
||||
incompatible changes: |
||||
</para> |
||||
|
||||
<itemizedlist> |
||||
<listitem> |
||||
<para> |
||||
The minimum version of Nix required to evaluate Nixpkgs is now 2.0. |
||||
</para> |
||||
<itemizedlist> |
||||
<listitem> |
||||
<para> |
||||
For users of NixOS 18.03 and 19.03, NixOS defaults to Nix 2.0, but |
||||
supports using Nix 1.11 by setting <literal>nix.package = |
||||
pkgs.nix1;</literal>. If this option is set to a Nix 1.11 package, you |
||||
will need to either unset the option or upgrade it to Nix 2.0. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
For users of NixOS 17.09, you will first need to upgrade Nix by setting |
||||
<literal>nix.package = pkgs.nixStable2;</literal> and run |
||||
<command>nixos-rebuild switch</command> as the <literal>root</literal> |
||||
user. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
For users of a daemon-less Nix installation on Linux or macOS, you can |
||||
upgrade Nix by running <command>curl https://nixos.org/nix/install | |
||||
sh</command>, or prior to doing a channel update, running |
||||
<command>nix-env -iA nix</command>. |
||||
</para> |
||||
<para> |
||||
If you have already run a channel update and Nix is no longer able to |
||||
evaluate Nixpkgs, the error message printed should provide adequate |
||||
directions for upgrading Nix. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
For users of the Nix daemon on macOS, you can upgrade Nix by running |
||||
<command>sudo -i sh -c 'nix-channel --update && nix-env -iA |
||||
nixpkgs.nix'; sudo launchctl stop org.nixos.nix-daemon; sudo launchctl |
||||
start org.nixos.nix-daemon</command>. |
||||
</para> |
||||
</listitem> |
||||
</itemizedlist> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Package <varname>rabbitmq_server</varname> is renamed to |
||||
<varname>rabbitmq-server</varname>. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
The <literal>light</literal> module no longer uses setuid binaries, but |
||||
udev rules. As a consequence users of that module have to belong to the |
||||
<literal>video</literal> group in order to use the executable (i.e. |
||||
<literal>users.users.yourusername.extraGroups = ["video"];</literal>). |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Buildbot now supports Python 3 and its packages have been moved to |
||||
<literal>pythonPackages</literal>. The options |
||||
<option>services.buildbot-master.package</option> and |
||||
<option>services.buildbot-worker.package</option> can be used to select |
||||
the Python 2 or 3 version of the package. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Options |
||||
<literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.userName</literal> and |
||||
<literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.modulePackages</literal> |
||||
were removed. They were never used for anything and can therefore safely be removed. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Package <literal>wasm</literal> has been renamed <literal>proglodyte-wasm</literal>. The package |
||||
<literal>wasm</literal> will be pointed to <literal>ocamlPackages.wasm</literal> in 19.09, so |
||||
make sure to update your configuration if you want to keep <literal>proglodyte-wasm</literal> |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
OpenSMTPD has been upgraded to version 6.4.0p1. This release makes |
||||
backwards-incompatible changes to the configuration file format. See |
||||
<command>man smtpd.conf</command> for more information on the new file |
||||
format. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
The versioned <varname>postgresql</varname> have been renamed to use |
||||
underscore number seperators. For example, <varname>postgresql96</varname> |
||||
has been renamed to <varname>postgresql_9_6</varname>. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Slurm introduces the new option |
||||
<literal>services.slurm.stateSaveLocation</literal>, |
||||
which is now set to <literal>/var/spool/slurm</literal> by default |
||||
(instead of <literal>/var/spool</literal>). |
||||
Make sure to move all files to the new directory or to set the option accordingly. |
||||
</para> |
||||
<para> |
||||
The slurmctld now runs as user <literal>slurm</literal> instead of <literal>root</literal>. |
||||
If you want to keep slurmctld running as <literal>root</literal>, set |
||||
<literal>services.slurm.user = root</literal>. |
||||
</para> |
||||
<para> |
||||
The options <literal>services.slurm.nodeName</literal> and |
||||
<literal>services.slurm.partitionName</literal> are now sets of |
||||
strings to correctly reflect that fact that each of these |
||||
options can occour more than once in the configuration. |
||||
</para> |
||||
</listitem> |
||||
</itemizedlist> |
||||
</section> |
||||
|
||||
<section xmlns="http://docbook.org/ns/docbook" |
||||
xmlns:xlink="http://www.w3.org/1999/xlink" |
||||
xmlns:xi="http://www.w3.org/2001/XInclude" |
||||
version="5.0" |
||||
xml:id="sec-release-19.03-notable-changes"> |
||||
<title>Other Notable Changes</title> |
||||
|
||||
<itemizedlist> |
||||
<listitem> |
||||
<para> |
||||
The <option>services.matomo</option> module gained the option |
||||
<option>services.matomo.package</option> which determines the used |
||||
Matomo version. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
The deprecated <literal>truecrypt</literal> package has been removed |
||||
and <literal>truecrypt</literal> attribute is now an alias for |
||||
<literal>veracrypt</literal>. VeraCrypt is backward-compatible with |
||||
TrueCrypt volumes. Note that <literal>cryptsetup</literal> also |
||||
supports loading TrueCrypt volumes. |
||||
</para> |
||||
</listitem> |
||||
</itemizedlist> |
||||
</section> |
||||
</section> |
@ -0,0 +1,25 @@ |
||||
{ config, lib, pkgs, ... }: |
||||
|
||||
with lib; |
||||
|
||||
let |
||||
|
||||
cfg = config.hardware.steam-hardware; |
||||
|
||||
in |
||||
|
||||
{ |
||||
options.hardware.steam-hardware = { |
||||
enable = mkOption { |
||||
type = types.bool; |
||||
default = false; |
||||
description = "Enable udev rules for Steam hardware such as the Steam Controller, other supported controllers and the HTC Vive"; |
||||
}; |
||||
}; |
||||
|
||||
config = mkIf cfg.enable { |
||||
services.udev.packages = [ |
||||
pkgs.steamPackages.steam |
||||
]; |
||||
}; |
||||
} |
@ -0,0 +1,49 @@ |
||||
# This module contains the basic configuration for building a graphical NixOS |
||||
# installation CD. |
||||
|
||||
{ config, lib, pkgs, ... }: |
||||
|
||||
with lib; |
||||
|
||||
{ |
||||
imports = [ ./installation-cd-base.nix ]; |
||||
|
||||
services.xserver = { |
||||
enable = true; |
||||
|
||||
# Don't start the X server by default. |
||||
autorun = mkForce false; |
||||
|
||||
# Automatically login as root. |
||||
displayManager.slim = { |
||||
enable = true; |
||||
defaultUser = "root"; |
||||
autoLogin = true; |
||||
}; |
||||
|
||||
}; |
||||
|
||||
# Provide networkmanager for easy wireless configuration. |
||||
networking.networkmanager.enable = true; |
||||
networking.wireless.enable = mkForce false; |
||||
|
||||
# KDE complains if power management is disabled (to be precise, if |
||||
# there is no power management backend such as upower). |
||||
powerManagement.enable = true; |
||||
|
||||
environment.systemPackages = [ |
||||
# Include gparted for partitioning disks. |
||||
pkgs.gparted |
||||
|
||||
# Include some editors. |
||||
pkgs.vim |
||||
pkgs.bvi # binary editor |
||||
pkgs.joe |
||||
|
||||
# Firefox for reading the manual. |
||||
pkgs.firefox |
||||
|
||||
pkgs.glxinfo |
||||
]; |
||||
|
||||
} |
@ -1,6 +1,6 @@ |
||||
{ |
||||
x86_64-linux = "/nix/store/0d60i73mcv8z1m8d2m74yfn84980gfsa-nix-2.0.4"; |
||||
i686-linux = "/nix/store/6ssafj2s5a2g9x28yld7b70vwd6vw6lb-nix-2.0.4"; |
||||
aarch64-linux = "/nix/store/3wwch7bp7n7xsl8apgy2a4b16yzyij1z-nix-2.0.4"; |
||||
x86_64-darwin = "/nix/store/771l8i0mz4c8kry8cz3sz8rr3alalckg-nix-2.0.4"; |
||||
x86_64-linux = "/nix/store/cdcia67siabmj6li7vyffgv2cry86fq8-nix-2.1.3"; |
||||
i686-linux = "/nix/store/6q3xi6y5qnsv7d62b8n00hqfxi8rs2xs-nix-2.1.3"; |
||||
aarch64-linux = "/nix/store/2v93d0vimlm28jg0ms6v1i6lc0fq13pn-nix-2.1.3"; |
||||
x86_64-darwin = "/nix/store/dkjlfkrknmxbjmpfk3dg4q3nmb7m3zvk-nix-2.1.3"; |
||||
} |
||||
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue