diff options
author | Jan Tojnar <jtojnar@gmail.com> | 2019-09-06 03:20:09 +0200 |
---|---|---|
committer | Jan Tojnar <jtojnar@gmail.com> | 2019-09-06 03:20:09 +0200 |
commit | cdf426488b5dc3a7c051d7ad1c90c07dc0c3a89f (patch) | |
tree | 3fdd8ed1c086fb0ddf93941114bb1cbbb4659af9 /doc | |
parent | e7cccdbb139ccf2f9f170500f40c04a6237a2da1 (diff) | |
parent | ed54a5b51dc9542df94f70b25a13d86d1f494e64 (diff) |
Merge branch 'master' into staging-next
Fixed trivial conflicts caused by removing rec.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/functions.xml | 1 | ||||
-rw-r--r-- | doc/functions/ocitools.xml | 76 | ||||
-rw-r--r-- | doc/stdenv.xml | 43 |
3 files changed, 120 insertions, 0 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index 3b60f46d81da..96bd95958eae 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -20,4 +20,5 @@ <xi:include href="functions/appimagetools.xml" /> <xi:include href="functions/prefer-remote-fetch.xml" /> <xi:include href="functions/nix-gitignore.xml" /> + <xi:include href="functions/ocitools.xml" /> </chapter> diff --git a/doc/functions/ocitools.xml b/doc/functions/ocitools.xml new file mode 100644 index 000000000000..4500c41a34ae --- /dev/null +++ b/doc/functions/ocitools.xml @@ -0,0 +1,76 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-pkgs-ociTools"> + <title>pkgs.ociTools</title> + + <para> + <varname>pkgs.ociTools</varname> is a set of functions for creating + containers according to the + <link xlink:href="https://github.com/opencontainers/runtime-spec">OCI + container specification v1.0.0</link>. Beyond that it makes no assumptions + about the container runner you choose to use to run the created container. + </para> + + <section xml:id="ssec-pkgs-ociTools-buildContainer"> + <title>buildContainer</title> + + <para> + This function creates a simple OCI container that runs a single command + inside of it. An OCI container consists of a <varname>config.json</varname> + and a rootfs directory.The nix store of the container will contain all + referenced dependencies of the given command. + </para> + + <para> + The parameters of <varname>buildContainer</varname> with an example value + are described below: + </para> + + <example xml:id='ex-ociTools-buildContainer'> + <title>Build Container</title> +<programlisting> +buildContainer { + cmd = with pkgs; writeScript "run.sh" '' + #!${bash}/bin/bash + ${coreutils}/bin/exec ${bash}/bin/bash + ''; <co xml:id='ex-ociTools-buildContainer-1' /> + + mounts = { + "/data" = { + type = "none"; + source = "/var/lib/mydata"; + options = [ "bind" ]; + }; + };<co xml:id='ex-ociTools-buildContainer-2' /> + + readonly = false; <co xml:id='ex-ociTools-buildContainer-3' /> +} + + </programlisting> + <calloutlist> + <callout arearefs='ex-ociTools-buildContainer-1'> + <para> + <varname>cmd</varname> specifies the program to run inside the container. + This is the only required argument for <varname>buildContainer</varname>. + All referenced packages inside the derivation will be made available + inside the container + </para> + </callout> + <callout arearefs='ex-ociTools-buildContainer-2'> + <para> + <varname>mounts</varname> specifies additional mount points chosen by the + user. By default only a minimal set of necessary filesystems are mounted + into the container (e.g procfs, cgroupfs) + </para> + </callout> + <callout arearefs='ex-ociTools-buildContainer-3'> + <para> + <varname>readonly</varname> makes the container's rootfs read-only if it is set to true. + The default value is false <literal>false</literal>. + </para> + </callout> + </calloutlist> + </example> + </section> +</section> diff --git a/doc/stdenv.xml b/doc/stdenv.xml index fe5929656565..15a13ba49e8e 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -2716,6 +2716,49 @@ nativeBuildInputs = [ breakpointHook ]; </varlistentry> <varlistentry> <term> + installShellFiles + </term> + <listitem> + <para> + This hook helps with installing manpages and shell completion files. It + exposes 2 shell functions <literal>installManPage</literal> and + <literal>installShellCompletion</literal> that can be used from your + <literal>postInstall</literal> hook. + </para> + <para> + The <literal>installManPage</literal> function takes one or more paths + to manpages to install. The manpages must have a section suffix, and may + optionally be compressed (with <literal>.gz</literal> suffix). This + function will place them into the correct directory. + </para> + <para> + The <literal>installShellCompletion</literal> function takes one or more + paths to shell completion files. By default it will autodetect the shell + type from the completion file extension, but you may also specify it by + passing one of <literal>--bash</literal>, <literal>--fish</literal>, or + <literal>--zsh</literal>. These flags apply to all paths listed after + them (up until another shell flag is given). Each path may also have a + custom installation name provided by providing a flag <literal>--name + NAME</literal> before the path. If this flag is not provided, zsh + completions will be renamed automatically such that + <literal>foobar.zsh</literal> becomes <literal>_foobar</literal>. +<programlisting> +nativeBuildInputs = [ installShellFiles ]; +postInstall = '' + installManPage doc/foobar.1 doc/barfoo.3 + # explicit behavior + installShellCompletion --bash --name foobar.bash share/completions.bash + installShellCompletion --fish --name foobar.fish share/completions.fish + installShellCompletion --zsh --name _foobar share/completions.zsh + # implicit behavior + installShellCompletion share/completions/foobar.{bash,fish,zsh} +''; +</programlisting> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> libiconv, libintl </term> <listitem> |