diff options
author | Nikolay Amiantov <ab@fmap.me> | 2016-06-09 18:20:56 +0300 |
---|---|---|
committer | Nikolay Amiantov <ab@fmap.me> | 2016-06-09 18:20:56 +0300 |
commit | 75ea0523c41372cea4450f748c5ef59b0d01702e (patch) | |
tree | 55d02981b501202bc158a19b0b5ce7c6c63ad9d5 | |
parent | 3d8664ee42d43218bdec1cc9b1075998ad66082f (diff) |
doc: update buildFHSUserEnv documentation
-rw-r--r-- | doc/functions.xml | 84 |
1 files changed, 33 insertions, 51 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index e6bb6b7deefbe..73b178b061f95 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -171,42 +171,18 @@ c = lib.makeOverridable f { a = 1; b = 2; }</programlisting> <section xml:id="sec-fhs-environments"> - <title>buildFHSChrootEnv/buildFHSUserEnv</title> + <title>buildFHSUserEnv</title> <para> - <function>buildFHSChrootEnv</function> and - <function>buildFHSUserEnv</function> provide a way to build and run - FHS-compatible lightweight sandboxes. They get their own isolated root with - binded <filename>/nix/store</filename>, so their footprint in terms of disk + <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. - </para> - - <para> - <function>buildFHSChrootEnv</function> allows to create persistent - environments, which can be constructed, deconstructed and entered by - multiple users at once. A downside is that it requires - <literal>root</literal> access for both those who create and destroy and - those who enter it. It can be useful to create environments for daemons that - one can enter and observe. - </para> - - <para> - <function>buildFHSUserEnv</function> uses Linux namespaces feature to create + self-updated binaries. It uses Linux namespaces feature to create temporary lightweight environments which are destroyed after all child - processes exit. It does not require root access, and can be useful to create - sandboxes and wrap applications. - </para> - - <para> - Those functions both rely on <function>buildFHSEnv</function>, which creates - an actual directory structure given a list of necessary packages and extra - build commands. - <function>buildFHSChrootEnv</function> and <function>buildFHSUserEnv</function> - both accept those arguments which are passed to - <function>buildFHSEnv</function>: + processes exit, without root user rights requirement. Accepted arguments are: </para> <variablelist> @@ -220,14 +196,16 @@ c = lib.makeOverridable f { a = 1; b = 2; }</programlisting> <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).</para></listitem> + (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).</para></listitem> + a host (i.e. i686 and x86_64 on x86_64 installations). Only libraries are + installed by default.</para></listitem> </varlistentry> <varlistentry> @@ -240,30 +218,34 @@ c = lib.makeOverridable f { a = 1; b = 2; }</programlisting> <varlistentry> <term><literal>extraBuildCommandsMulti</literal></term> - <listitem><para>Like <literal>extraBuildCommandsMulti</literal>, but + <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> - Additionally, <function>buildFHSUserEnv</function> accepts - <literal>runScript</literal> parameter, which is a command that would be - executed inside the sandbox and passed all the command line arguments. It - default to <literal>bash</literal>. - </para> - <para> - It also uses <literal>CHROOTENV_EXTRA_BINDS</literal> environment variable - for binding extra directories in the sandbox to outside places. The format of - the variable is <literal>/mnt=test-mnt:/data</literal>, where - <literal>/mnt</literal> would be mounted as <literal>/test-mnt</literal> - and <literal>/data</literal> would be mounted as <literal>/data</literal>. - <literal>extraBindMounts</literal> array argument to - <function>buildFHSUserEnv</function> function is prepended to this variable. - Latter entries take priority if defined several times -- i.e. in case of - <literal>/data=data1:/data=data2</literal> the actual bind path would be - <literal>/data2</literal>. - </para> - <para> One can create a simple environment using a <literal>shell.nix</literal> like that: </para> |