diff options
author | Graham Christensen <graham@grahamc.com> | 2018-10-02 14:08:36 -0400 |
---|---|---|
committer | Graham Christensen <graham@grahamc.com> | 2018-10-02 14:08:36 -0400 |
commit | 0856d5c4add0abe92c1a8d15f95003ce5a2b828d (patch) | |
tree | e7421db7829c5786df7cde30d31f5c92613aa65a /doc/functions/fhs-environments.xml | |
parent | 3ac79c89b7da1f674c742f6a30385d37454e7f62 (diff) |
nixpkgs docs: move fhs-environments to its own file
Diffstat (limited to 'doc/functions/fhs-environments.xml')
-rw-r--r-- | doc/functions/fhs-environments.xml | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/doc/functions/fhs-environments.xml b/doc/functions/fhs-environments.xml new file mode 100644 index 0000000000000..bfe0db522a1df --- /dev/null +++ b/doc/functions/fhs-environments.xml @@ -0,0 +1,144 @@ +<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> |