pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 xml:id="chap-functions">
5 <title>Functions reference</title>
6 <para>
7 The nixpkgs repository has several utility functions to manipulate Nix
8 expressions.
9 </para>
10 <section xml:id="sec-overrides">
11 <title>Overriding</title>
12
13 <para>
14 Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g.
15 derivation attributes, the results of derivations or even the whole package
16 set.
17 </para>
18
19 <section xml:id="sec-pkg-override">
20 <title><pkg>.override</title>
21
22 <para>
23 The function <varname>override</varname> is usually available for all the
24 derivations in the nixpkgs expression (<varname>pkgs</varname>).
25 </para>
26
27 <para>
28 It is used to override the arguments passed to a function.
29 </para>
30
31 <para>
32 Example usages:
33<programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting>
34<programlisting>import pkgs.path { overlays = [ (self: super: {
35 foo = super.foo.override { barSupport = true ; };
36 })]};</programlisting>
37<programlisting>mypkg = pkgs.callPackage ./mypkg.nix {
38 mydep = pkgs.mydep.override { ... };
39 }</programlisting>
40 </para>
41
42 <para>
43 In the first example, <varname>pkgs.foo</varname> is the result of a
44 function call with some default arguments, usually a derivation. Using
45 <varname>pkgs.foo.override</varname> will call the same function with the
46 given new arguments.
47 </para>
48 </section>
49
50 <section xml:id="sec-pkg-overrideAttrs">
51 <title><pkg>.overrideAttrs</title>
52
53 <para>
54 The function <varname>overrideAttrs</varname> allows overriding the
55 attribute set passed to a <varname>stdenv.mkDerivation</varname> call,
56 producing a new derivation based on the original one. This function is
57 available on all derivations produced by the
58 <varname>stdenv.mkDerivation</varname> function, which is most packages in
59 the nixpkgs expression <varname>pkgs</varname>.
60 </para>
61
62 <para>
63 Example usage:
64<programlisting>helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec {
65 separateDebugInfo = true;
66 });</programlisting>
67 </para>
68
69 <para>
70 In the above example, the <varname>separateDebugInfo</varname> attribute is
71 overridden to be true, thus building debug info for
72 <varname>helloWithDebug</varname>, while all other attributes will be
73 retained from the original <varname>hello</varname> package.
74 </para>
75
76 <para>
77 The argument <varname>oldAttrs</varname> is conventionally used to refer to
78 the attr set originally passed to <varname>stdenv.mkDerivation</varname>.
79 </para>
80
81 <note>
82 <para>
83 Note that <varname>separateDebugInfo</varname> is processed only by the
84 <varname>stdenv.mkDerivation</varname> function, not the generated, raw
85 Nix derivation. Thus, using <varname>overrideDerivation</varname> will not
86 work in this case, as it overrides only the attributes of the final
87 derivation. It is for this reason that <varname>overrideAttrs</varname>
88 should be preferred in (almost) all cases to
89 <varname>overrideDerivation</varname>, i.e. to allow using
90 <varname>sdenv.mkDerivation</varname> to process input arguments, as well
91 as the fact that it is easier to use (you can use the same attribute names
92 you see in your Nix code, instead of the ones generated (e.g.
93 <varname>buildInputs</varname> vs <varname>nativeBuildInputs</varname>,
94 and involves less typing.
95 </para>
96 </note>
97 </section>
98
99 <section xml:id="sec-pkg-overrideDerivation">
100 <title><pkg>.overrideDerivation</title>
101
102 <warning>
103 <para>
104 You should prefer <varname>overrideAttrs</varname> in almost all cases,
105 see its documentation for the reasons why.
106 <varname>overrideDerivation</varname> is not deprecated and will continue
107 to work, but is less nice to use and does not have as many abilities as
108 <varname>overrideAttrs</varname>.
109 </para>
110 </warning>
111
112 <warning>
113 <para>
114 Do not use this function in Nixpkgs as it evaluates a Derivation before
115 modifying it, which breaks package abstraction and removes error-checking
116 of function arguments. In addition, this evaluation-per-function
117 application incurs a performance penalty, which can become a problem if
118 many overrides are used. It is only intended for ad-hoc customisation,
119 such as in <filename>~/.config/nixpkgs/config.nix</filename>.
120 </para>
121 </warning>
122
123 <para>
124 The function <varname>overrideDerivation</varname> creates a new derivation
125 based on an existing one by overriding the original's attributes with the
126 attribute set produced by the specified function. This function is
127 available on all derivations defined using the
128 <varname>makeOverridable</varname> function. Most standard
129 derivation-producing functions, such as
130 <varname>stdenv.mkDerivation</varname>, are defined using this function,
131 which means most packages in the nixpkgs expression,
132 <varname>pkgs</varname>, have this function.
133 </para>
134
135 <para>
136 Example usage:
137<programlisting>mySed = pkgs.gnused.overrideDerivation (oldAttrs: {
138 name = "sed-4.2.2-pre";
139 src = fetchurl {
140 url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;
141 sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k";
142 };
143 patches = [];
144 });</programlisting>
145 </para>
146
147 <para>
148 In the above example, the <varname>name</varname>, <varname>src</varname>,
149 and <varname>patches</varname> of the derivation will be overridden, while
150 all other attributes will be retained from the original derivation.
151 </para>
152
153 <para>
154 The argument <varname>oldAttrs</varname> is used to refer to the attribute
155 set of the original derivation.
156 </para>
157
158 <note>
159 <para>
160 A package's attributes are evaluated *before* being modified by the
161 <varname>overrideDerivation</varname> function. For example, the
162 <varname>name</varname> attribute reference in <varname>url =
163 "mirror://gnu/hello/${name}.tar.gz";</varname> is filled-in *before* the
164 <varname>overrideDerivation</varname> function modifies the attribute set.
165 This means that overriding the <varname>name</varname> attribute, in this
166 example, *will not* change the value of the <varname>url</varname>
167 attribute. Instead, we need to override both the <varname>name</varname>
168 *and* <varname>url</varname> attributes.
169 </para>
170 </note>
171 </section>
172
173 <section xml:id="sec-lib-makeOverridable">
174 <title>lib.makeOverridable</title>
175
176 <para>
177 The function <varname>lib.makeOverridable</varname> is used to make the
178 result of a function easily customizable. This utility only makes sense for
179 functions that accept an argument set and return an attribute set.
180 </para>
181
182 <para>
183 Example usage:
184<programlisting>f = { a, b }: { result = a+b; }
185 c = lib.makeOverridable f { a = 1; b = 2; }</programlisting>
186 </para>
187
188 <para>
189 The variable <varname>c</varname> is the value of the <varname>f</varname>
190 function applied with some default arguments. Hence the value of
191 <varname>c.result</varname> is <literal>3</literal>, in this example.
192 </para>
193
194 <para>
195 The variable <varname>c</varname> however also has some additional
196 functions, like <link linkend="sec-pkg-override">c.override</link> which
197 can be used to override the default arguments. In this example the value of
198 <varname>(c.override { a = 4; }).result</varname> is 6.
199 </para>
200 </section>
201 </section>
202 <section xml:id="sec-generators">
203 <title>Generators</title>
204
205 <para>
206 Generators are functions that create file formats from nix data structures,
207 e. g. for configuration files. There are generators available for:
208 <literal>INI</literal>, <literal>JSON</literal> and <literal>YAML</literal>
209 </para>
210
211 <para>
212 All generators follow a similar call interface: <code>generatorName
213 configFunctions data</code>, where <literal>configFunctions</literal> is an
214 attrset of user-defined functions that format nested parts of the content.
215 They each have common defaults, so often they do not need to be set
216 manually. An example is <code>mkSectionName ? (name: libStr.escape [ "[" "]"
217 ] name)</code> from the <literal>INI</literal> generator. It receives the
218 name of a section and sanitizes it. The default
219 <literal>mkSectionName</literal> escapes <literal>[</literal> and
220 <literal>]</literal> with a backslash.
221 </para>
222
223 <para>
224 Generators can be fine-tuned to produce exactly the file format required by
225 your application/service. One example is an INI-file format which uses
226 <literal>: </literal> as separator, the strings
227 <literal>"yes"</literal>/<literal>"no"</literal> as boolean values and
228 requires all string values to be quoted:
229 </para>
230
231<programlisting>
232with lib;
233let
234 customToINI = generators.toINI {
235 # specifies how to format a key/value pair
236 mkKeyValue = generators.mkKeyValueDefault {
237 # specifies the generated string for a subset of nix values
238 mkValueString = v:
239 if v == true then ''"yes"''
240 else if v == false then ''"no"''
241 else if isString v then ''"${v}"''
242 # and delegats all other values to the default generator
243 else generators.mkValueStringDefault {} v;
244 } ":";
245 };
246
247# the INI file can now be given as plain old nix values
248in customToINI {
249 main = {
250 pushinfo = true;
251 autopush = false;
252 host = "localhost";
253 port = 42;
254 };
255 mergetool = {
256 merge = "diff3";
257 };
258}
259</programlisting>
260
261 <para>
262 This will produce the following INI file as nix string:
263 </para>
264
265<programlisting>
266[main]
267autopush:"no"
268host:"localhost"
269port:42
270pushinfo:"yes"
271str\:ange:"very::strange"
272
273[mergetool]
274merge:"diff3"
275</programlisting>
276
277 <note>
278 <para>
279 Nix store paths can be converted to strings by enclosing a derivation
280 attribute like so: <code>"${drv}"</code>.
281 </para>
282 </note>
283
284 <para>
285 Detailed documentation for each generator can be found in
286 <literal>lib/generators.nix</literal>.
287 </para>
288 </section>
289 <section xml:id="sec-debug">
290 <title>Debugging Nix Expressions</title>
291
292 <para>
293 Nix is a unityped, dynamic language, this means every value can potentially
294 appear anywhere. Since it is also non-strict, evaluation order and what
295 ultimately is evaluated might surprise you. Therefore it is important to be
296 able to debug nix expressions.
297 </para>
298
299 <para>
300 In the <literal>lib/debug.nix</literal> file you will find a number of
301 functions that help (pretty-)printing values while evaluation is runnnig.
302 You can even specify how deep these values should be printed recursively,
303 and transform them on the fly. Please consult the docstrings in
304 <literal>lib/debug.nix</literal> for usage information.
305 </para>
306 </section>
307 <section xml:id="sec-fhs-environments">
308 <title>buildFHSUserEnv</title>
309
310 <para>
311 <function>buildFHSUserEnv</function> provides a way to build and run
312 FHS-compatible lightweight sandboxes. It creates an isolated root with bound
313 <filename>/nix/store</filename>, so its footprint in terms of disk space
314 needed is quite small. This allows one to run software which is hard or
315 unfeasible to patch for NixOS -- 3rd-party source trees with FHS
316 assumptions, games distributed as tarballs, software with integrity checking
317 and/or external self-updated binaries. It uses Linux namespaces feature to
318 create temporary lightweight environments which are destroyed after all
319 child processes exit, without root user rights requirement. Accepted
320 arguments are:
321 </para>
322
323 <variablelist>
324 <varlistentry>
325 <term>
326 <literal>name</literal>
327 </term>
328 <listitem>
329 <para>
330 Environment name.
331 </para>
332 </listitem>
333 </varlistentry>
334 <varlistentry>
335 <term>
336 <literal>targetPkgs</literal>
337 </term>
338 <listitem>
339 <para>
340 Packages to be installed for the main host's architecture (i.e. x86_64 on
341 x86_64 installations). Along with libraries binaries are also installed.
342 </para>
343 </listitem>
344 </varlistentry>
345 <varlistentry>
346 <term>
347 <literal>multiPkgs</literal>
348 </term>
349 <listitem>
350 <para>
351 Packages to be installed for all architectures supported by a host (i.e.
352 i686 and x86_64 on x86_64 installations). Only libraries are installed by
353 default.
354 </para>
355 </listitem>
356 </varlistentry>
357 <varlistentry>
358 <term>
359 <literal>extraBuildCommands</literal>
360 </term>
361 <listitem>
362 <para>
363 Additional commands to be executed for finalizing the directory
364 structure.
365 </para>
366 </listitem>
367 </varlistentry>
368 <varlistentry>
369 <term>
370 <literal>extraBuildCommandsMulti</literal>
371 </term>
372 <listitem>
373 <para>
374 Like <literal>extraBuildCommands</literal>, but executed only on multilib
375 architectures.
376 </para>
377 </listitem>
378 </varlistentry>
379 <varlistentry>
380 <term>
381 <literal>extraOutputsToInstall</literal>
382 </term>
383 <listitem>
384 <para>
385 Additional derivation outputs to be linked for both target and
386 multi-architecture packages.
387 </para>
388 </listitem>
389 </varlistentry>
390 <varlistentry>
391 <term>
392 <literal>extraInstallCommands</literal>
393 </term>
394 <listitem>
395 <para>
396 Additional commands to be executed for finalizing the derivation with
397 runner script.
398 </para>
399 </listitem>
400 </varlistentry>
401 <varlistentry>
402 <term>
403 <literal>runScript</literal>
404 </term>
405 <listitem>
406 <para>
407 A command that would be executed inside the sandbox and passed all the
408 command line arguments. It defaults to <literal>bash</literal>.
409 </para>
410 </listitem>
411 </varlistentry>
412 </variablelist>
413
414 <para>
415 One can create a simple environment using a <literal>shell.nix</literal>
416 like that:
417 </para>
418
419<programlisting><![CDATA[
420{ pkgs ? import <nixpkgs> {} }:
421
422(pkgs.buildFHSUserEnv {
423 name = "simple-x11-env";
424 targetPkgs = pkgs: (with pkgs;
425 [ udev
426 alsaLib
427 ]) ++ (with pkgs.xorg;
428 [ libX11
429 libXcursor
430 libXrandr
431 ]);
432 multiPkgs = pkgs: (with pkgs;
433 [ udev
434 alsaLib
435 ]);
436 runScript = "bash";
437}).env
438]]></programlisting>
439
440 <para>
441 Running <literal>nix-shell</literal> would then drop you into a shell with
442 these libraries and binaries available. You can use this to run
443 closed-source applications which expect FHS structure without hassles:
444 simply change <literal>runScript</literal> to the application path, e.g.
445 <filename>./bin/start.sh</filename> -- relative paths are supported.
446 </para>
447 </section>
448 <xi:include href="shell.section.xml" />
449 <section xml:id="sec-pkgs-dockerTools">
450 <title>pkgs.dockerTools</title>
451
452 <para>
453 <varname>pkgs.dockerTools</varname> is a set of functions for creating and
454 manipulating Docker images according to the
455 <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#docker-image-specification-v120">
456 Docker Image Specification v1.2.0 </link>. Docker itself is not used to
457 perform any of the operations done by these functions.
458 </para>
459
460 <warning>
461 <para>
462 The <varname>dockerTools</varname> API is unstable and may be subject to
463 backwards-incompatible changes in the future.
464 </para>
465 </warning>
466
467 <section xml:id="ssec-pkgs-dockerTools-buildImage">
468 <title>buildImage</title>
469
470 <para>
471 This function is analogous to the <command>docker build</command> command,
472 in that can used to build a Docker-compatible repository tarball containing
473 a single image with one or multiple layers. As such, the result is suitable
474 for being loaded in Docker with <command>docker load</command>.
475 </para>
476
477 <para>
478 The parameters of <varname>buildImage</varname> with relative example
479 values are described below:
480 </para>
481
482 <example xml:id='ex-dockerTools-buildImage'>
483 <title>Docker build</title>
484<programlisting>
485 buildImage {
486 name = "redis"; <co xml:id='ex-dockerTools-buildImage-1' />
487 tag = "latest"; <co xml:id='ex-dockerTools-buildImage-2' />
488
489 fromImage = someBaseImage; <co xml:id='ex-dockerTools-buildImage-3' />
490 fromImageName = null; <co xml:id='ex-dockerTools-buildImage-4' />
491 fromImageTag = "latest"; <co xml:id='ex-dockerTools-buildImage-5' />
492
493 contents = pkgs.redis; <co xml:id='ex-dockerTools-buildImage-6' />
494 runAsRoot = '' <co xml:id='ex-dockerTools-buildImage-runAsRoot' />
495 #!${stdenv.shell}
496 mkdir -p /data
497 '';
498
499 config = { <co xml:id='ex-dockerTools-buildImage-8' />
500 Cmd = [ "/bin/redis-server" ];
501 WorkingDir = "/data";
502 Volumes = {
503 "/data" = {};
504 };
505 };
506 }
507 </programlisting>
508 </example>
509
510 <para>
511 The above example will build a Docker image <literal>redis/latest</literal>
512 from the given base image. Loading and running this image in Docker results
513 in <literal>redis-server</literal> being started automatically.
514 </para>
515
516 <calloutlist>
517 <callout arearefs='ex-dockerTools-buildImage-1'>
518 <para>
519 <varname>name</varname> specifies the name of the resulting image. This
520 is the only required argument for <varname>buildImage</varname>.
521 </para>
522 </callout>
523 <callout arearefs='ex-dockerTools-buildImage-2'>
524 <para>
525 <varname>tag</varname> specifies the tag of the resulting image. By
526 default it's <literal>null</literal>, which indicates that the nix output
527 hash will be used as tag.
528 </para>
529 </callout>
530 <callout arearefs='ex-dockerTools-buildImage-3'>
531 <para>
532 <varname>fromImage</varname> is the repository tarball containing the
533 base image. It must be a valid Docker image, such as exported by
534 <command>docker save</command>. By default it's <literal>null</literal>,
535 which can be seen as equivalent to <literal>FROM scratch</literal> of a
536 <filename>Dockerfile</filename>.
537 </para>
538 </callout>
539 <callout arearefs='ex-dockerTools-buildImage-4'>
540 <para>
541 <varname>fromImageName</varname> can be used to further specify the base
542 image within the repository, in case it contains multiple images. By
543 default it's <literal>null</literal>, in which case
544 <varname>buildImage</varname> will peek the first image available in the
545 repository.
546 </para>
547 </callout>
548 <callout arearefs='ex-dockerTools-buildImage-5'>
549 <para>
550 <varname>fromImageTag</varname> can be used to further specify the tag of
551 the base image within the repository, in case an image contains multiple
552 tags. By default it's <literal>null</literal>, in which case
553 <varname>buildImage</varname> will peek the first tag available for the
554 base image.
555 </para>
556 </callout>
557 <callout arearefs='ex-dockerTools-buildImage-6'>
558 <para>
559 <varname>contents</varname> is a derivation that will be copied in the
560 new layer of the resulting image. This can be similarly seen as
561 <command>ADD contents/ /</command> in a <filename>Dockerfile</filename>.
562 By default it's <literal>null</literal>.
563 </para>
564 </callout>
565 <callout arearefs='ex-dockerTools-buildImage-runAsRoot'>
566 <para>
567 <varname>runAsRoot</varname> is a bash script that will run as root in an
568 environment that overlays the existing layers of the base image with the
569 new resulting layer, including the previously copied
570 <varname>contents</varname> derivation. This can be similarly seen as
571 <command>RUN ...</command> in a <filename>Dockerfile</filename>.
572 <note>
573 <para>
574 Using this parameter requires the <literal>kvm</literal> device to be
575 available.
576 </para>
577 </note>
578 </para>
579 </callout>
580 <callout arearefs='ex-dockerTools-buildImage-8'>
581 <para>
582 <varname>config</varname> is used to specify the configuration of the
583 containers that will be started off the built image in Docker. The
584 available options are listed in the
585 <link xlink:href="https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions">
586 Docker Image Specification v1.2.0 </link>.
587 </para>
588 </callout>
589 </calloutlist>
590
591 <para>
592 After the new layer has been created, its closure (to which
593 <varname>contents</varname>, <varname>config</varname> and
594 <varname>runAsRoot</varname> contribute) will be copied in the layer
595 itself. Only new dependencies that are not already in the existing layers
596 will be copied.
597 </para>
598
599 <para>
600 At the end of the process, only one new single layer will be produced and
601 added to the resulting image.
602 </para>
603
604 <para>
605 The resulting repository will only list the single image
606 <varname>image/tag</varname>. In the case of
607 <xref linkend='ex-dockerTools-buildImage'/> it would be
608 <varname>redis/latest</varname>.
609 </para>
610
611 <para>
612 It is possible to inspect the arguments with which an image was built using
613 its <varname>buildArgs</varname> attribute.
614 </para>
615
616 <note>
617 <para>
618 If you see errors similar to <literal>getProtocolByName: does not exist
619 (no such protocol name: tcp)</literal> you may need to add
620 <literal>pkgs.iana-etc</literal> to <varname>contents</varname>.
621 </para>
622 </note>
623
624 <note>
625 <para>
626 If you see errors similar to <literal>Error_Protocol ("certificate has
627 unknown CA",True,UnknownCa)</literal> you may need to add
628 <literal>pkgs.cacert</literal> to <varname>contents</varname>.
629 </para>
630 </note>
631 </section>
632
633 <section xml:id="ssec-pkgs-dockerTools-fetchFromRegistry">
634 <title>pullImage</title>
635
636 <para>
637 This function is analogous to the <command>docker pull</command> command,
638 in that can be used to pull a Docker image from a Docker registry. By
639 default <link xlink:href="https://hub.docker.com/">Docker Hub</link> is
640 used to pull images.
641 </para>
642
643 <para>
644 Its parameters are described in the example below:
645 </para>
646
647 <example xml:id='ex-dockerTools-pullImage'>
648 <title>Docker pull</title>
649<programlisting>
650 pullImage {
651 imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' />
652 imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; <co xml:id='ex-dockerTools-pullImage-2' />
653 finalImageTag = "1.11"; <co xml:id='ex-dockerTools-pullImage-3' />
654 sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-4' />
655 os = "linux"; <co xml:id='ex-dockerTools-pullImage-5' />
656 arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' />
657 }
658 </programlisting>
659 </example>
660
661 <calloutlist>
662 <callout arearefs='ex-dockerTools-pullImage-1'>
663 <para>
664 <varname>imageName</varname> specifies the name of the image to be
665 downloaded, which can also include the registry namespace (e.g.
666 <literal>nixos</literal>). This argument is required.
667 </para>
668 </callout>
669 <callout arearefs='ex-dockerTools-pullImage-2'>
670 <para>
671 <varname>imageDigest</varname> specifies the digest of the image to be
672 downloaded. Skopeo can be used to get the digest of an image, with its
673 <varname>inspect</varname> subcommand. Since a given
674 <varname>imageName</varname> may transparently refer to a manifest list
675 of images which support multiple architectures and/or operating systems,
676 supply the `--override-os` and `--override-arch` arguments to specify
677 exactly which image you want. By default it will match the OS and
678 architecture of the host the command is run on.
679<programlisting>
680 $ 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'"
681 sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
682 </programlisting>
683 This argument is required.
684 </para>
685 </callout>
686 <callout arearefs='ex-dockerTools-pullImage-3'>
687 <para>
688 <varname>finalImageTag</varname>, if specified, this is the tag of the
689 image to be created. Note it is never used to fetch the image since we
690 prefer to rely on the immutable digest ID. By default it's
691 <literal>latest</literal>.
692 </para>
693 </callout>
694 <callout arearefs='ex-dockerTools-pullImage-4'>
695 <para>
696 <varname>sha256</varname> is the checksum of the whole fetched image.
697 This argument is required.
698 </para>
699 </callout>
700 <callout arearefs='ex-dockerTools-pullImage-5'>
701 <para>
702 <varname>os</varname>, if specified, is the operating system of the
703 fetched image. By default it's <literal>linux</literal>.
704 </para>
705 </callout>
706 <callout arearefs='ex-dockerTools-pullImage-6'>
707 <para>
708 <varname>arch</varname>, if specified, is the cpu architecture of the
709 fetched image. By default it's <literal>x86_64</literal>.
710 </para>
711 </callout>
712 </calloutlist>
713 </section>
714
715 <section xml:id="ssec-pkgs-dockerTools-exportImage">
716 <title>exportImage</title>
717
718 <para>
719 This function is analogous to the <command>docker export</command> command,
720 in that can used to flatten a Docker image that contains multiple layers.
721 It is in fact the result of the merge of all the layers of the image. As
722 such, the result is suitable for being imported in Docker with
723 <command>docker import</command>.
724 </para>
725
726 <note>
727 <para>
728 Using this function requires the <literal>kvm</literal> device to be
729 available.
730 </para>
731 </note>
732
733 <para>
734 The parameters of <varname>exportImage</varname> are the following:
735 </para>
736
737 <example xml:id='ex-dockerTools-exportImage'>
738 <title>Docker export</title>
739<programlisting>
740 exportImage {
741 fromImage = someLayeredImage;
742 fromImageName = null;
743 fromImageTag = null;
744
745 name = someLayeredImage.name;
746 }
747 </programlisting>
748 </example>
749
750 <para>
751 The parameters relative to the base image have the same synopsis as
752 described in <xref linkend='ssec-pkgs-dockerTools-buildImage'/>, except
753 that <varname>fromImage</varname> is the only required argument in this
754 case.
755 </para>
756
757 <para>
758 The <varname>name</varname> argument is the name of the derivation output,
759 which defaults to <varname>fromImage.name</varname>.
760 </para>
761 </section>
762
763 <section xml:id="ssec-pkgs-dockerTools-shadowSetup">
764 <title>shadowSetup</title>
765
766 <para>
767 This constant string is a helper for setting up the base files for managing
768 users and groups, only if such files don't exist already. It is suitable
769 for being used in a <varname>runAsRoot</varname>
770 <xref linkend='ex-dockerTools-buildImage-runAsRoot'/> script for cases like
771 in the example below:
772 </para>
773
774 <example xml:id='ex-dockerTools-shadowSetup'>
775 <title>Shadow base files</title>
776<programlisting>
777 buildImage {
778 name = "shadow-basic";
779
780 runAsRoot = ''
781 #!${stdenv.shell}
782 ${shadowSetup}
783 groupadd -r redis
784 useradd -r -g redis redis
785 mkdir /data
786 chown redis:redis /data
787 '';
788 }
789 </programlisting>
790 </example>
791
792 <para>
793 Creating base files like <literal>/etc/passwd</literal> or
794 <literal>/etc/login.defs</literal> are necessary for shadow-utils to
795 manipulate users and groups.
796 </para>
797 </section>
798 </section>
799</chapter>