From 2b9713c2815aafaa410acca8600da5dbf7ca6821 Mon Sep 17 00:00:00 2001 From: Frederik Rietdijk Date: Mon, 21 Oct 2019 11:39:46 +0200 Subject: doc: move fhs and mkShell under builders/special In my opinion Functions should only contain pure functions. These are both meant to provide derivations so I put them under Builders. Don't know exactly *where* to put them so "special" it is... --- doc/builders/special.xml | 12 +++ doc/builders/special/fhs-environments.xml | 122 ++++++++++++++++++++++++++++++ doc/builders/special/mkshell.xml | 24 ++++++ 3 files changed, 158 insertions(+) create mode 100644 doc/builders/special.xml create mode 100644 doc/builders/special/fhs-environments.xml create mode 100644 doc/builders/special/mkshell.xml (limited to 'doc/builders') diff --git a/doc/builders/special.xml b/doc/builders/special.xml new file mode 100644 index 00000000000..56d98f02527 --- /dev/null +++ b/doc/builders/special.xml @@ -0,0 +1,12 @@ + + Special builders + + This chapter describes several special builders. + + + + + + diff --git a/doc/builders/special/fhs-environments.xml b/doc/builders/special/fhs-environments.xml new file mode 100644 index 00000000000..e7b81e97a23 --- /dev/null +++ b/doc/builders/special/fhs-environments.xml @@ -0,0 +1,122 @@ +
+ buildFHSUserEnv + + + buildFHSUserEnv provides a way to build and run FHS-compatible lightweight sandboxes. It creates an isolated root with bound /nix/store, 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: + + + + + + name + + + + Environment name. + + + + + + targetPkgs + + + + 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. + + + + + + multiPkgs + + + + 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. + + + + + + extraBuildCommands + + + + Additional commands to be executed for finalizing the directory structure. + + + + + + extraBuildCommandsMulti + + + + Like extraBuildCommands, but executed only on multilib architectures. + + + + + + extraOutputsToInstall + + + + Additional derivation outputs to be linked for both target and multi-architecture packages. + + + + + + extraInstallCommands + + + + Additional commands to be executed for finalizing the derivation with runner script. + + + + + + runScript + + + + A command that would be executed inside the sandbox and passed all the command line arguments. It defaults to bash. + + + + + + + One can create a simple environment using a shell.nix like that: + + + {} }: + +(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 +]]> + + + Running nix-shell 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 runScript to the application path, e.g. ./bin/start.sh -- relative paths are supported. + +
diff --git a/doc/builders/special/mkshell.xml b/doc/builders/special/mkshell.xml new file mode 100644 index 00000000000..cef65d06b88 --- /dev/null +++ b/doc/builders/special/mkshell.xml @@ -0,0 +1,24 @@ +
+ pkgs.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 + + {} }: +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 ]; +} +]]> +
+
-- cgit 1.4.1