From f200a322c4f55c853d6543e47ebdbe7457262a61 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 13:52:21 -0400 Subject: [PATCH 1/9] nixpkgs docs: move overrides to its own file --- doc/functions.xml | 202 +---------------------------------- doc/functions/overrides.xml | 205 ++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+), 201 deletions(-) create mode 100644 doc/functions/overrides.xml diff --git a/doc/functions.xml b/doc/functions.xml index 8223a8b0531c..754159bff4f1 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -7,208 +7,8 @@ The nixpkgs repository has several utility functions to manipulate Nix expressions. -
- Overriding - - Sometimes one wants to override parts of nixpkgs, e.g. - derivation attributes, the results of derivations or even the whole package - set. - - -
- <pkg>.override - - - The function override is usually available for all the - derivations in the nixpkgs expression (pkgs). - - - - It is used to override the arguments passed to a function. - - - - Example usages: -pkgs.foo.override { arg1 = val1; arg2 = val2; ... } - -import pkgs.path { overlays = [ (self: super: { - foo = super.foo.override { barSupport = true ; }; - })]}; - - -mypkg = pkgs.callPackage ./mypkg.nix { - mydep = pkgs.mydep.override { ... }; - } - - - - - In the first example, pkgs.foo is the result of a - function call with some default arguments, usually a derivation. Using - pkgs.foo.override will call the same function with the - given new arguments. - -
- -
- <pkg>.overrideAttrs - - - The function overrideAttrs allows overriding the - attribute set passed to a stdenv.mkDerivation call, - producing a new derivation based on the original one. This function is - available on all derivations produced by the - stdenv.mkDerivation function, which is most packages in - the nixpkgs expression pkgs. - - - - Example usage: - -helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec { - separateDebugInfo = true; -}); - - - - - In the above example, the separateDebugInfo attribute is - overridden to be true, thus building debug info for - helloWithDebug, while all other attributes will be - retained from the original hello package. - - - - The argument oldAttrs is conventionally used to refer to - the attr set originally passed to stdenv.mkDerivation. - - - - - Note that separateDebugInfo is processed only by the - stdenv.mkDerivation function, not the generated, raw - Nix derivation. Thus, using overrideDerivation will not - work in this case, as it overrides only the attributes of the final - derivation. It is for this reason that overrideAttrs - should be preferred in (almost) all cases to - overrideDerivation, i.e. to allow using - sdenv.mkDerivation to process input arguments, as well - as the fact that it is easier to use (you can use the same attribute names - you see in your Nix code, instead of the ones generated (e.g. - buildInputs vs nativeBuildInputs, - and involves less typing. - - -
- -
- <pkg>.overrideDerivation - - - - You should prefer overrideAttrs in almost all cases, - see its documentation for the reasons why. - overrideDerivation is not deprecated and will continue - to work, but is less nice to use and does not have as many abilities as - overrideAttrs. - - - - - - Do not use this function in Nixpkgs as it evaluates a Derivation before - modifying it, which breaks package abstraction and removes error-checking - of function arguments. In addition, this evaluation-per-function - application incurs a performance penalty, which can become a problem if - many overrides are used. It is only intended for ad-hoc customisation, - such as in ~/.config/nixpkgs/config.nix. - - - - - The function overrideDerivation creates a new derivation - based on an existing one by overriding the original's attributes with the - attribute set produced by the specified function. This function is - available on all derivations defined using the - makeOverridable function. Most standard - derivation-producing functions, such as - stdenv.mkDerivation, are defined using this function, - which means most packages in the nixpkgs expression, - pkgs, have this function. - - - - Example usage: - -mySed = pkgs.gnused.overrideDerivation (oldAttrs: { - name = "sed-4.2.2-pre"; - src = fetchurl { - url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2; - sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k"; - }; - patches = []; -}); - - - - - In the above example, the name, src, - and patches of the derivation will be overridden, while - all other attributes will be retained from the original derivation. - - - - The argument oldAttrs is used to refer to the attribute - set of the original derivation. - - - - - A package's attributes are evaluated *before* being modified by the - overrideDerivation function. For example, the - name attribute reference in url = - "mirror://gnu/hello/${name}.tar.gz"; is filled-in *before* the - overrideDerivation function modifies the attribute set. - This means that overriding the name attribute, in this - example, *will not* change the value of the url - attribute. Instead, we need to override both the name - *and* url attributes. - - -
- -
- lib.makeOverridable - - - The function lib.makeOverridable is used to make the - result of a function easily customizable. This utility only makes sense for - functions that accept an argument set and return an attribute set. - - - - Example usage: - -f = { a, b }: { result = a+b; }; -c = lib.makeOverridable f { a = 1; b = 2; }; - - - - - The variable c is the value of the f - function applied with some default arguments. Hence the value of - c.result is 3, in this example. - - - - The variable c however also has some additional - functions, like c.override which - can be used to override the default arguments. In this example the value of - (c.override { a = 4; }).result is 6. - -
-
+
Generators diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml new file mode 100644 index 000000000000..dc81e3795065 --- /dev/null +++ b/doc/functions/overrides.xml @@ -0,0 +1,205 @@ +
+ Overriding + + + Sometimes one wants to override parts of nixpkgs, e.g. + derivation attributes, the results of derivations or even the whole package + set. + + +
+ <pkg>.override + + + The function override is usually available for all the + derivations in the nixpkgs expression (pkgs). + + + + It is used to override the arguments passed to a function. + + + + Example usages: +pkgs.foo.override { arg1 = val1; arg2 = val2; ... } + +import pkgs.path { overlays = [ (self: super: { + foo = super.foo.override { barSupport = true ; }; + })]}; + + +mypkg = pkgs.callPackage ./mypkg.nix { + mydep = pkgs.mydep.override { ... }; + } + + + + + In the first example, pkgs.foo is the result of a + function call with some default arguments, usually a derivation. Using + pkgs.foo.override will call the same function with the + given new arguments. + +
+ +
+ <pkg>.overrideAttrs + + + The function overrideAttrs allows overriding the + attribute set passed to a stdenv.mkDerivation call, + producing a new derivation based on the original one. This function is + available on all derivations produced by the + stdenv.mkDerivation function, which is most packages in + the nixpkgs expression pkgs. + + + + Example usage: + +helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec { + separateDebugInfo = true; +}); + + + + + In the above example, the separateDebugInfo attribute is + overridden to be true, thus building debug info for + helloWithDebug, while all other attributes will be + retained from the original hello package. + + + + The argument oldAttrs is conventionally used to refer to + the attr set originally passed to stdenv.mkDerivation. + + + + + Note that separateDebugInfo is processed only by the + stdenv.mkDerivation function, not the generated, raw + Nix derivation. Thus, using overrideDerivation will not + work in this case, as it overrides only the attributes of the final + derivation. It is for this reason that overrideAttrs + should be preferred in (almost) all cases to + overrideDerivation, i.e. to allow using + sdenv.mkDerivation to process input arguments, as well + as the fact that it is easier to use (you can use the same attribute names + you see in your Nix code, instead of the ones generated (e.g. + buildInputs vs nativeBuildInputs, + and involves less typing. + + +
+ +
+ <pkg>.overrideDerivation + + + + You should prefer overrideAttrs in almost all cases, + see its documentation for the reasons why. + overrideDerivation is not deprecated and will continue + to work, but is less nice to use and does not have as many abilities as + overrideAttrs. + + + + + + Do not use this function in Nixpkgs as it evaluates a Derivation before + modifying it, which breaks package abstraction and removes error-checking + of function arguments. In addition, this evaluation-per-function + application incurs a performance penalty, which can become a problem if + many overrides are used. It is only intended for ad-hoc customisation, + such as in ~/.config/nixpkgs/config.nix. + + + + + The function overrideDerivation creates a new derivation + based on an existing one by overriding the original's attributes with the + attribute set produced by the specified function. This function is + available on all derivations defined using the + makeOverridable function. Most standard + derivation-producing functions, such as + stdenv.mkDerivation, are defined using this function, + which means most packages in the nixpkgs expression, + pkgs, have this function. + + + + Example usage: + +mySed = pkgs.gnused.overrideDerivation (oldAttrs: { + name = "sed-4.2.2-pre"; + src = fetchurl { + url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2; + sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k"; + }; + patches = []; +}); + + + + + In the above example, the name, src, + and patches of the derivation will be overridden, while + all other attributes will be retained from the original derivation. + + + + The argument oldAttrs is used to refer to the attribute + set of the original derivation. + + + + + A package's attributes are evaluated *before* being modified by the + overrideDerivation function. For example, the + name attribute reference in url = + "mirror://gnu/hello/${name}.tar.gz"; is filled-in *before* the + overrideDerivation function modifies the attribute set. + This means that overriding the name attribute, in this + example, *will not* change the value of the url + attribute. Instead, we need to override both the name + *and* url attributes. + + +
+ +
+ lib.makeOverridable + + + The function lib.makeOverridable is used to make the + result of a function easily customizable. This utility only makes sense for + functions that accept an argument set and return an attribute set. + + + + Example usage: + +f = { a, b }: { result = a+b; }; +c = lib.makeOverridable f { a = 1; b = 2; }; + + + + + The variable c is the value of the f + function applied with some default arguments. Hence the value of + c.result is 3, in this example. + + + + The variable c however also has some additional + functions, like c.override which + can be used to override the default arguments. In this example the value of + (c.override { a = 4; }).result is 6. + +
+
From 9ae39b3553146b3ae72fc5ac26654e1930baba3d Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 14:03:59 -0400 Subject: [PATCH 2/9] nixpkgs docs: move generators to its own file --- doc/functions.xml | 88 +---------------------------------- doc/functions/generators.xml | 90 ++++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+), 87 deletions(-) create mode 100644 doc/functions/generators.xml diff --git a/doc/functions.xml b/doc/functions.xml index 754159bff4f1..333ed65986b1 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -9,93 +9,7 @@ -
- Generators - - - Generators are functions that create file formats from nix data structures, - e. g. for configuration files. There are generators available for: - INI, JSON and YAML - - - - All generators follow a similar call interface: generatorName - configFunctions data, where configFunctions is an - attrset of user-defined functions that format nested parts of the content. - They each have common defaults, so often they do not need to be set - manually. An example is mkSectionName ? (name: libStr.escape [ "[" "]" - ] name) from the INI generator. It receives the - name of a section and sanitizes it. The default - mkSectionName escapes [ and - ] with a backslash. - - - - Generators can be fine-tuned to produce exactly the file format required by - your application/service. One example is an INI-file format which uses - : as separator, the strings - "yes"/"no" as boolean values and - requires all string values to be quoted: - - - -with lib; -let - customToINI = generators.toINI { - # specifies how to format a key/value pair - mkKeyValue = generators.mkKeyValueDefault { - # specifies the generated string for a subset of nix values - mkValueString = v: - if v == true then ''"yes"'' - else if v == false then ''"no"'' - else if isString v then ''"${v}"'' - # and delegats all other values to the default generator - else generators.mkValueStringDefault {} v; - } ":"; - }; - -# the INI file can now be given as plain old nix values -in customToINI { - main = { - pushinfo = true; - autopush = false; - host = "localhost"; - port = 42; - }; - mergetool = { - merge = "diff3"; - }; -} - - - - This will produce the following INI file as nix string: - - - -[main] -autopush:"no" -host:"localhost" -port:42 -pushinfo:"yes" -str\:ange:"very::strange" - -[mergetool] -merge:"diff3" - - - - - Nix store paths can be converted to strings by enclosing a derivation - attribute like so: "${drv}". - - - - - Detailed documentation for each generator can be found in - lib/generators.nix. - -
+
Debugging Nix Expressions diff --git a/doc/functions/generators.xml b/doc/functions/generators.xml new file mode 100644 index 000000000000..0a9c346145f9 --- /dev/null +++ b/doc/functions/generators.xml @@ -0,0 +1,90 @@ +
+ Generators + + + Generators are functions that create file formats from nix data structures, + e. g. for configuration files. There are generators available for: + INI, JSON and YAML + + + + All generators follow a similar call interface: generatorName + configFunctions data, where configFunctions is an + attrset of user-defined functions that format nested parts of the content. + They each have common defaults, so often they do not need to be set + manually. An example is mkSectionName ? (name: libStr.escape [ "[" "]" + ] name) from the INI generator. It receives the + name of a section and sanitizes it. The default + mkSectionName escapes [ and + ] with a backslash. + + + + Generators can be fine-tuned to produce exactly the file format required by + your application/service. One example is an INI-file format which uses + : as separator, the strings + "yes"/"no" as boolean values and + requires all string values to be quoted: + + + +with lib; +let + customToINI = generators.toINI { + # specifies how to format a key/value pair + mkKeyValue = generators.mkKeyValueDefault { + # specifies the generated string for a subset of nix values + mkValueString = v: + if v == true then ''"yes"'' + else if v == false then ''"no"'' + else if isString v then ''"${v}"'' + # and delegats all other values to the default generator + else generators.mkValueStringDefault {} v; + } ":"; + }; + +# the INI file can now be given as plain old nix values +in customToINI { + main = { + pushinfo = true; + autopush = false; + host = "localhost"; + port = 42; + }; + mergetool = { + merge = "diff3"; + }; +} + + + + This will produce the following INI file as nix string: + + + +[main] +autopush:"no" +host:"localhost" +port:42 +pushinfo:"yes" +str\:ange:"very::strange" + +[mergetool] +merge:"diff3" + + + + + Nix store paths can be converted to strings by enclosing a derivation + attribute like so: "${drv}". + + + + + Detailed documentation for each generator can be found in + lib/generators.nix. + +
From 3ac79c89b7da1f674c742f6a30385d37454e7f62 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 14:07:06 -0400 Subject: [PATCH 3/9] nixpkgs docs: move debug to its own file --- doc/functions.xml | 19 +------------------ doc/functions/debug.xml | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+), 18 deletions(-) create mode 100644 doc/functions/debug.xml diff --git a/doc/functions.xml b/doc/functions.xml index 333ed65986b1..b710d30e1081 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -10,24 +10,7 @@ -
- Debugging Nix Expressions - - - Nix is a unityped, dynamic language, this means every value can potentially - appear anywhere. Since it is also non-strict, evaluation order and what - ultimately is evaluated might surprise you. Therefore it is important to be - able to debug nix expressions. - - - - In the lib/debug.nix file you will find a number of - functions that help (pretty-)printing values while evaluation is runnnig. - You can even specify how deep these values should be printed recursively, - and transform them on the fly. Please consult the docstrings in - lib/debug.nix for usage information. - -
+
buildFHSUserEnv diff --git a/doc/functions/debug.xml b/doc/functions/debug.xml new file mode 100644 index 000000000000..272bdf55513f --- /dev/null +++ b/doc/functions/debug.xml @@ -0,0 +1,21 @@ +
+ Debugging Nix Expressions + + + Nix is a unityped, dynamic language, this means every value can potentially + appear anywhere. Since it is also non-strict, evaluation order and what + ultimately is evaluated might surprise you. Therefore it is important to be + able to debug nix expressions. + + + + In the lib/debug.nix file you will find a number of + functions that help (pretty-)printing values while evaluation is runnnig. + You can even specify how deep these values should be printed recursively, + and transform them on the fly. Please consult the docstrings in + lib/debug.nix for usage information. + +
From 0856d5c4add0abe92c1a8d15f95003ce5a2b828d Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 14:08:36 -0400 Subject: [PATCH 4/9] nixpkgs docs: move fhs-environments to its own file --- doc/functions.xml | 142 +--------------------------- doc/functions/fhs-environments.xml | 144 +++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+), 141 deletions(-) create mode 100644 doc/functions/fhs-environments.xml diff --git a/doc/functions.xml b/doc/functions.xml index b710d30e1081..ac75c4fc10e4 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -11,147 +11,7 @@ -
- 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. - -
+
pkgs.dockerTools diff --git a/doc/functions/fhs-environments.xml b/doc/functions/fhs-environments.xml new file mode 100644 index 000000000000..bfe0db522a1d --- /dev/null +++ b/doc/functions/fhs-environments.xml @@ -0,0 +1,144 @@ +
+ 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. + +
From 8bf342ffb86eedf8a9749420b4019ab1e4c21629 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 14:13:12 -0400 Subject: [PATCH 5/9] nixpkgs docs: move dockertool to its own file --- doc/functions.xml | 564 +-------------------------------- doc/functions/dockertools.xml | 566 ++++++++++++++++++++++++++++++++++ 2 files changed, 567 insertions(+), 563 deletions(-) create mode 100644 doc/functions/dockertools.xml diff --git a/doc/functions.xml b/doc/functions.xml index ac75c4fc10e4..4fc387f0fbd6 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -13,567 +13,5 @@ -
- pkgs.dockerTools - - - pkgs.dockerTools is a set of functions for creating and - manipulating Docker images according to the - - Docker Image Specification v1.2.0 . Docker itself is not used to - perform any of the operations done by these functions. - - - - - The dockerTools API is unstable and may be subject to - backwards-incompatible changes in the future. - - - -
- buildImage - - - This function is analogous to the docker build command, - in that can used to build a Docker-compatible repository tarball containing - a single image with one or multiple layers. As such, the result is suitable - for being loaded in Docker with docker load. - - - - The parameters of buildImage with relative example - values are described below: - - - - Docker build - -buildImage { - name = "redis"; - tag = "latest"; - - fromImage = someBaseImage; - fromImageName = null; - fromImageTag = "latest"; - - contents = pkgs.redis; - runAsRoot = '' - #!${stdenv.shell} - mkdir -p /data - ''; - - config = { - Cmd = [ "/bin/redis-server" ]; - WorkingDir = "/data"; - Volumes = { - "/data" = {}; - }; - }; -} - - - - - The above example will build a Docker image redis/latest - from the given base image. Loading and running this image in Docker results - in redis-server being started automatically. - - - - - - name specifies the name of the resulting image. This - is the only required argument for buildImage. - - - - - tag specifies the tag of the resulting image. By - default it's null, which indicates that the nix output - hash will be used as tag. - - - - - fromImage is the repository tarball containing the - base image. It must be a valid Docker image, such as exported by - docker save. By default it's null, - which can be seen as equivalent to FROM scratch of a - Dockerfile. - - - - - fromImageName can be used to further specify the base - image within the repository, in case it contains multiple images. By - default it's null, in which case - buildImage will peek the first image available in the - repository. - - - - - fromImageTag can be used to further specify the tag of - the base image within the repository, in case an image contains multiple - tags. By default it's null, in which case - buildImage will peek the first tag available for the - base image. - - - - - contents is a derivation that will be copied in the - new layer of the resulting image. This can be similarly seen as - ADD contents/ / in a Dockerfile. - By default it's null. - - - - - runAsRoot is a bash script that will run as root in an - environment that overlays the existing layers of the base image with the - new resulting layer, including the previously copied - contents derivation. This can be similarly seen as - RUN ... in a Dockerfile. - - - Using this parameter requires the kvm device to be - available. - - - - - - - config is used to specify the configuration of the - containers that will be started off the built image in Docker. The - available options are listed in the - - Docker Image Specification v1.2.0 . - - - - - - After the new layer has been created, its closure (to which - contents, config and - runAsRoot contribute) will be copied in the layer - itself. Only new dependencies that are not already in the existing layers - will be copied. - - - - At the end of the process, only one new single layer will be produced and - added to the resulting image. - - - - The resulting repository will only list the single image - image/tag. In the case of - it would be - redis/latest. - - - - It is possible to inspect the arguments with which an image was built using - its buildArgs attribute. - - - - - If you see errors similar to getProtocolByName: does not exist - (no such protocol name: tcp) you may need to add - pkgs.iana-etc to contents. - - - - - - If you see errors similar to Error_Protocol ("certificate has - unknown CA",True,UnknownCa) you may need to add - pkgs.cacert to contents. - - - - - Impurely Defining a Docker Layer's Creation Date - - By default buildImage will use a static - date of one second past the UNIX Epoch. This allows - buildImage to produce binary reproducible - images. When listing images with docker list - images, the newly created images will be listed like - this: - - - - You can break binary reproducibility but have a sorted, - meaningful CREATED column by setting - created to now. - - - - and now the Docker CLI will display a reasonable date and - sort the images as expected: - - however, the produced images will not be binary reproducible. - - -
- -
- buildLayeredImage - - - Create a Docker image with many of the store paths being on their own layer - to improve sharing between images. - - - - - - name - - - - The name of the resulting image. - - - - - - tag optional - - - - Tag of the generated image. - - - Default: the output path's hash - - - - - - contents optional - - - - Top level paths in the container. Either a single derivation, or a list - of derivations. - - - Default: [] - - - - - - config optional - - - - Run-time configuration of the container. A full list of the options are - available at in the - - Docker Image Specification v1.2.0 . - - - Default: {} - - - - - - created optional - - - - Date and time the layers were created. Follows the same - now exception supported by - buildImage. - - - Default: 1970-01-01T00:00:01Z - - - - - - maxLayers optional - - - - Maximum number of layers to create. - - - Default: 24 - - - - - -
- Behavior of <varname>contents</varname> in the final image - - - Each path directly listed in contents will have a - symlink in the root of the image. - - - - For example: - - will create symlinks for all the paths in the hello - package: - /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello -/share/info/hello.info -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/info/hello.info -/share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo -]]> - -
- -
- Automatic inclusion of <varname>config</varname> references - - - The closure of config is automatically included in the - closure of the final image. - - - - This allows you to make very simple Docker images with very little code. - This container will start up and run hello: - - -
- -
- Adjusting <varname>maxLayers</varname> - - - Increasing the maxLayers increases the number of layers - which have a chance to be shared between different images. - - - - Modern Docker installations support up to 128 layers, however older - versions support as few as 42. - - - - If the produced image will not be extended by other Docker builds, it is - safe to set maxLayers to 128. - However it will be impossible to extend the image further. - - - - The first (maxLayers-2) most "popular" paths will have - their own individual layers, then layer #maxLayers-1 - will contain all the remaining "unpopular" paths, and finally layer - #maxLayers will contain the Image configuration. - - - - Docker's Layers are not inherently ordered, they are content-addressable - and are not explicitly layered until they are composed in to an Image. - -
-
- -
- pullImage - - - This function is analogous to the docker pull command, - in that can be used to pull a Docker image from a Docker registry. By - default Docker Hub is - used to pull images. - - - - Its parameters are described in the example below: - - - - Docker pull - -pullImage { - imageName = "nixos/nix"; - imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; - finalImageTag = "1.11"; - sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; - os = "linux"; - arch = "x86_64"; -} - - - - - - - imageName specifies the name of the image to be - downloaded, which can also include the registry namespace (e.g. - nixos). This argument is required. - - - - - imageDigest specifies the digest of the image to be - downloaded. Skopeo can be used to get the digest of an image, with its - inspect subcommand. Since a given - imageName may transparently refer to a manifest list - of images which support multiple architectures and/or operating systems, - supply the `--override-os` and `--override-arch` arguments to specify - exactly which image you want. By default it will match the OS and - architecture of the host the command is run on. - -$ 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'" -sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b - - This argument is required. - - - - - finalImageTag, if specified, this is the tag of the - image to be created. Note it is never used to fetch the image since we - prefer to rely on the immutable digest ID. By default it's - latest. - - - - - sha256 is the checksum of the whole fetched image. - This argument is required. - - - - - os, if specified, is the operating system of the - fetched image. By default it's linux. - - - - - arch, if specified, is the cpu architecture of the - fetched image. By default it's x86_64. - - - -
- -
- exportImage - - - This function is analogous to the docker export command, - in that can used to flatten a Docker image that contains multiple layers. - It is in fact the result of the merge of all the layers of the image. As - such, the result is suitable for being imported in Docker with - docker import. - - - - - Using this function requires the kvm device to be - available. - - - - - The parameters of exportImage are the following: - - - - Docker export - -exportImage { - fromImage = someLayeredImage; - fromImageName = null; - fromImageTag = null; - - name = someLayeredImage.name; -} - - - - - The parameters relative to the base image have the same synopsis as - described in , except - that fromImage is the only required argument in this - case. - - - - The name argument is the name of the derivation output, - which defaults to fromImage.name. - -
- -
- shadowSetup - - - This constant string is a helper for setting up the base files for managing - users and groups, only if such files don't exist already. It is suitable - for being used in a runAsRoot - script for cases like - in the example below: - - - - Shadow base files - -buildImage { - name = "shadow-basic"; - - runAsRoot = '' - #!${stdenv.shell} - ${shadowSetup} - groupadd -r redis - useradd -r -g redis redis - mkdir /data - chown redis:redis /data - ''; -} - - - - - Creating base files like /etc/passwd or - /etc/login.defs are necessary for shadow-utils to - manipulate users and groups. - -
-
+ diff --git a/doc/functions/dockertools.xml b/doc/functions/dockertools.xml new file mode 100644 index 000000000000..8bfdb3c68d7a --- /dev/null +++ b/doc/functions/dockertools.xml @@ -0,0 +1,566 @@ +
+ pkgs.dockerTools + + + pkgs.dockerTools is a set of functions for creating and + manipulating Docker images according to the + + Docker Image Specification v1.2.0 . Docker itself is not used to + perform any of the operations done by these functions. + + + + + The dockerTools API is unstable and may be subject to + backwards-incompatible changes in the future. + + + +
+ buildImage + + + This function is analogous to the docker build command, + in that can used to build a Docker-compatible repository tarball containing + a single image with one or multiple layers. As such, the result is suitable + for being loaded in Docker with docker load. + + + + The parameters of buildImage with relative example + values are described below: + + + + Docker build + +buildImage { + name = "redis"; + tag = "latest"; + + fromImage = someBaseImage; + fromImageName = null; + fromImageTag = "latest"; + + contents = pkgs.redis; + runAsRoot = '' + #!${stdenv.shell} + mkdir -p /data + ''; + + config = { + Cmd = [ "/bin/redis-server" ]; + WorkingDir = "/data"; + Volumes = { + "/data" = {}; + }; + }; +} + + + + + The above example will build a Docker image redis/latest + from the given base image. Loading and running this image in Docker results + in redis-server being started automatically. + + + + + + name specifies the name of the resulting image. This + is the only required argument for buildImage. + + + + + tag specifies the tag of the resulting image. By + default it's null, which indicates that the nix output + hash will be used as tag. + + + + + fromImage is the repository tarball containing the + base image. It must be a valid Docker image, such as exported by + docker save. By default it's null, + which can be seen as equivalent to FROM scratch of a + Dockerfile. + + + + + fromImageName can be used to further specify the base + image within the repository, in case it contains multiple images. By + default it's null, in which case + buildImage will peek the first image available in the + repository. + + + + + fromImageTag can be used to further specify the tag of + the base image within the repository, in case an image contains multiple + tags. By default it's null, in which case + buildImage will peek the first tag available for the + base image. + + + + + contents is a derivation that will be copied in the + new layer of the resulting image. This can be similarly seen as + ADD contents/ / in a Dockerfile. + By default it's null. + + + + + runAsRoot is a bash script that will run as root in an + environment that overlays the existing layers of the base image with the + new resulting layer, including the previously copied + contents derivation. This can be similarly seen as + RUN ... in a Dockerfile. + + + Using this parameter requires the kvm device to be + available. + + + + + + + config is used to specify the configuration of the + containers that will be started off the built image in Docker. The + available options are listed in the + + Docker Image Specification v1.2.0 . + + + + + + After the new layer has been created, its closure (to which + contents, config and + runAsRoot contribute) will be copied in the layer + itself. Only new dependencies that are not already in the existing layers + will be copied. + + + + At the end of the process, only one new single layer will be produced and + added to the resulting image. + + + + The resulting repository will only list the single image + image/tag. In the case of + it would be + redis/latest. + + + + It is possible to inspect the arguments with which an image was built using + its buildArgs attribute. + + + + + If you see errors similar to getProtocolByName: does not exist + (no such protocol name: tcp) you may need to add + pkgs.iana-etc to contents. + + + + + + If you see errors similar to Error_Protocol ("certificate has + unknown CA",True,UnknownCa) you may need to add + pkgs.cacert to contents. + + + + + Impurely Defining a Docker Layer's Creation Date + + By default buildImage will use a static + date of one second past the UNIX Epoch. This allows + buildImage to produce binary reproducible + images. When listing images with docker list + images, the newly created images will be listed like + this: + + + + You can break binary reproducibility but have a sorted, + meaningful CREATED column by setting + created to now. + + + + and now the Docker CLI will display a reasonable date and + sort the images as expected: + + however, the produced images will not be binary reproducible. + + +
+ +
+ buildLayeredImage + + + Create a Docker image with many of the store paths being on their own layer + to improve sharing between images. + + + + + + name + + + + The name of the resulting image. + + + + + + tag optional + + + + Tag of the generated image. + + + Default: the output path's hash + + + + + + contents optional + + + + Top level paths in the container. Either a single derivation, or a list + of derivations. + + + Default: [] + + + + + + config optional + + + + Run-time configuration of the container. A full list of the options are + available at in the + + Docker Image Specification v1.2.0 . + + + Default: {} + + + + + + created optional + + + + Date and time the layers were created. Follows the same + now exception supported by + buildImage. + + + Default: 1970-01-01T00:00:01Z + + + + + + maxLayers optional + + + + Maximum number of layers to create. + + + Default: 24 + + + + + +
+ Behavior of <varname>contents</varname> in the final image + + + Each path directly listed in contents will have a + symlink in the root of the image. + + + + For example: + + will create symlinks for all the paths in the hello + package: + /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello +/share/info/hello.info -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/info/hello.info +/share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo +]]> + +
+ +
+ Automatic inclusion of <varname>config</varname> references + + + The closure of config is automatically included in the + closure of the final image. + + + + This allows you to make very simple Docker images with very little code. + This container will start up and run hello: + + +
+ +
+ Adjusting <varname>maxLayers</varname> + + + Increasing the maxLayers increases the number of layers + which have a chance to be shared between different images. + + + + Modern Docker installations support up to 128 layers, however older + versions support as few as 42. + + + + If the produced image will not be extended by other Docker builds, it is + safe to set maxLayers to 128. + However it will be impossible to extend the image further. + + + + The first (maxLayers-2) most "popular" paths will have + their own individual layers, then layer #maxLayers-1 + will contain all the remaining "unpopular" paths, and finally layer + #maxLayers will contain the Image configuration. + + + + Docker's Layers are not inherently ordered, they are content-addressable + and are not explicitly layered until they are composed in to an Image. + +
+
+ +
+ pullImage + + + This function is analogous to the docker pull command, + in that can be used to pull a Docker image from a Docker registry. By + default Docker Hub is + used to pull images. + + + + Its parameters are described in the example below: + + + + Docker pull + +pullImage { + imageName = "nixos/nix"; + imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; + finalImageTag = "1.11"; + sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; + os = "linux"; + arch = "x86_64"; +} + + + + + + + imageName specifies the name of the image to be + downloaded, which can also include the registry namespace (e.g. + nixos). This argument is required. + + + + + imageDigest specifies the digest of the image to be + downloaded. Skopeo can be used to get the digest of an image, with its + inspect subcommand. Since a given + imageName may transparently refer to a manifest list + of images which support multiple architectures and/or operating systems, + supply the `--override-os` and `--override-arch` arguments to specify + exactly which image you want. By default it will match the OS and + architecture of the host the command is run on. + +$ 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'" +sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b + + This argument is required. + + + + + finalImageTag, if specified, this is the tag of the + image to be created. Note it is never used to fetch the image since we + prefer to rely on the immutable digest ID. By default it's + latest. + + + + + sha256 is the checksum of the whole fetched image. + This argument is required. + + + + + os, if specified, is the operating system of the + fetched image. By default it's linux. + + + + + arch, if specified, is the cpu architecture of the + fetched image. By default it's x86_64. + + + +
+ +
+ exportImage + + + This function is analogous to the docker export command, + in that can used to flatten a Docker image that contains multiple layers. + It is in fact the result of the merge of all the layers of the image. As + such, the result is suitable for being imported in Docker with + docker import. + + + + + Using this function requires the kvm device to be + available. + + + + + The parameters of exportImage are the following: + + + + Docker export + +exportImage { + fromImage = someLayeredImage; + fromImageName = null; + fromImageTag = null; + + name = someLayeredImage.name; +} + + + + + The parameters relative to the base image have the same synopsis as + described in , except + that fromImage is the only required argument in this + case. + + + + The name argument is the name of the derivation output, + which defaults to fromImage.name. + +
+ +
+ shadowSetup + + + This constant string is a helper for setting up the base files for managing + users and groups, only if such files don't exist already. It is suitable + for being used in a runAsRoot + script for cases like + in the example below: + + + + Shadow base files + +buildImage { + name = "shadow-basic"; + + runAsRoot = '' + #!${stdenv.shell} + ${shadowSetup} + groupadd -r redis + useradd -r -g redis redis + mkdir /data + chown redis:redis /data + ''; +} + + + + + Creating base files like /etc/passwd or + /etc/login.defs are necessary for shadow-utils to + manipulate users and groups. + +
+
From 507a63c88557f8afa06a3e507fe3d055fc55a815 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 14:13:42 -0400 Subject: [PATCH 6/9] nixpkgs docs: move shell section to its own file --- doc/functions.xml | 2 +- doc/{ => functions}/shell.section.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename doc/{ => functions}/shell.section.md (100%) diff --git a/doc/functions.xml b/doc/functions.xml index 4fc387f0fbd6..ee73c46ad4d3 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -12,6 +12,6 @@ - + diff --git a/doc/shell.section.md b/doc/functions/shell.section.md similarity index 100% rename from doc/shell.section.md rename to doc/functions/shell.section.md From c3125498fd7d0398f50e2b53a9e274b7c1e2db67 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 14:16:27 -0400 Subject: [PATCH 7/9] shell functions: rewrite as xml --- doc/functions.xml | 2 +- doc/functions/shell.section.md | 22 ---------------------- doc/functions/shell.xml | 27 +++++++++++++++++++++++++++ 3 files changed, 28 insertions(+), 23 deletions(-) delete mode 100644 doc/functions/shell.section.md create mode 100644 doc/functions/shell.xml diff --git a/doc/functions.xml b/doc/functions.xml index ee73c46ad4d3..88011061ae6e 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -12,6 +12,6 @@ - + diff --git a/doc/functions/shell.section.md b/doc/functions/shell.section.md deleted file mode 100644 index cb8832a814fc..000000000000 --- a/doc/functions/shell.section.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: pkgs.mkShell -author: zimbatm -date: 2017-10-30 ---- - -# 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 - -```nix -{ pkgs ? import {} }: -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 ]; -} -``` diff --git a/doc/functions/shell.xml b/doc/functions/shell.xml new file mode 100644 index 000000000000..a8d2a30cb508 --- /dev/null +++ b/doc/functions/shell.xml @@ -0,0 +1,27 @@ +
+ 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 ]; +} +]]> +
+
From 444e04b98571ad65269c8a988c4a9f772ca616a2 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 15:59:00 -0400 Subject: [PATCH 8/9] nixpkgs docs: Rebuild manual-full if nested XML docs change --- doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index ba77be6678c4..173e1c0b19ee 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -69,7 +69,7 @@ highlightjs: cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/ -manual-full.xml: ${MD_TARGETS} .version *.xml +manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml .version: From c07ba7c8560250d1b184698e6453b6d5ca11846f Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 15:59:59 -0400 Subject: [PATCH 9/9] nixpkgs docs: Reformat --- doc/cross-compilation.xml | 7 +- doc/functions/debug.xml | 30 +- doc/functions/dockertools.xml | 826 ++++++++++++++--------------- doc/functions/fhs-environments.xml | 228 ++++---- doc/functions/generators.xml | 73 ++- doc/functions/overrides.xml | 286 +++++----- doc/functions/shell.xml | 21 +- doc/package-notes.xml | 74 ++- 8 files changed, 778 insertions(+), 767 deletions(-) diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml index c7187d86d1b3..da664394f262 100644 --- a/doc/cross-compilation.xml +++ b/doc/cross-compilation.xml @@ -47,9 +47,10 @@ In Nixpkgs, these three platforms are defined as attribute sets under the - names buildPlatform, hostPlatform, and - targetPlatform. They are always defined as attributes in - the standard environment. That means one can access them like: + names buildPlatform, hostPlatform, + and targetPlatform. They are always defined as + attributes in the standard environment. That means one can access them + like: { stdenv, fooDep, barDep, .. }: ...stdenv.buildPlatform... . diff --git a/doc/functions/debug.xml b/doc/functions/debug.xml index 272bdf55513f..c6b3611eea53 100644 --- a/doc/functions/debug.xml +++ b/doc/functions/debug.xml @@ -2,20 +2,20 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-debug"> - Debugging Nix Expressions + Debugging Nix Expressions - - Nix is a unityped, dynamic language, this means every value can potentially - appear anywhere. Since it is also non-strict, evaluation order and what - ultimately is evaluated might surprise you. Therefore it is important to be - able to debug nix expressions. - + + Nix is a unityped, dynamic language, this means every value can potentially + appear anywhere. Since it is also non-strict, evaluation order and what + ultimately is evaluated might surprise you. Therefore it is important to be + able to debug nix expressions. + - - In the lib/debug.nix file you will find a number of - functions that help (pretty-)printing values while evaluation is runnnig. - You can even specify how deep these values should be printed recursively, - and transform them on the fly. Please consult the docstrings in - lib/debug.nix for usage information. - -
+ + In the lib/debug.nix file you will find a number of + functions that help (pretty-)printing values while evaluation is runnnig. You + can even specify how deep these values should be printed recursively, and + transform them on the fly. Please consult the docstrings in + lib/debug.nix for usage information. + +
diff --git a/doc/functions/dockertools.xml b/doc/functions/dockertools.xml index 8bfdb3c68d7a..501f46a967c3 100644 --- a/doc/functions/dockertools.xml +++ b/doc/functions/dockertools.xml @@ -2,40 +2,40 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-pkgs-dockerTools"> - pkgs.dockerTools + pkgs.dockerTools + + pkgs.dockerTools is a set of functions for creating and + manipulating Docker images according to the + + Docker Image Specification v1.2.0 . Docker itself is not used to + perform any of the operations done by these functions. + + + - pkgs.dockerTools is a set of functions for creating and - manipulating Docker images according to the - - Docker Image Specification v1.2.0 . Docker itself is not used to - perform any of the operations done by these functions. + The dockerTools API is unstable and may be subject to + backwards-incompatible changes in the future. + - - - The dockerTools API is unstable and may be subject to - backwards-incompatible changes in the future. - - - -
- buildImage +
+ buildImage - - This function is analogous to the docker build command, - in that can used to build a Docker-compatible repository tarball containing - a single image with one or multiple layers. As such, the result is suitable - for being loaded in Docker with docker load. - + + This function is analogous to the docker build command, + in that can used to build a Docker-compatible repository tarball containing + a single image with one or multiple layers. As such, the result is suitable + for being loaded in Docker with docker load. + - - The parameters of buildImage with relative example - values are described below: - + + The parameters of buildImage with relative example values + are described below: + - - Docker build + + Docker build buildImage { name = "redis"; @@ -60,151 +60,150 @@ buildImage { }; } - + - - The above example will build a Docker image redis/latest - from the given base image. Loading and running this image in Docker results - in redis-server being started automatically. - + + The above example will build a Docker image redis/latest + from the given base image. Loading and running this image in Docker results + in redis-server being started automatically. + - - - - name specifies the name of the resulting image. This - is the only required argument for buildImage. - - - - - tag specifies the tag of the resulting image. By - default it's null, which indicates that the nix output - hash will be used as tag. - - - - - fromImage is the repository tarball containing the - base image. It must be a valid Docker image, such as exported by - docker save. By default it's null, - which can be seen as equivalent to FROM scratch of a - Dockerfile. - - - - - fromImageName can be used to further specify the base - image within the repository, in case it contains multiple images. By - default it's null, in which case - buildImage will peek the first image available in the - repository. - - - - - fromImageTag can be used to further specify the tag of - the base image within the repository, in case an image contains multiple - tags. By default it's null, in which case - buildImage will peek the first tag available for the - base image. - - - - - contents is a derivation that will be copied in the - new layer of the resulting image. This can be similarly seen as - ADD contents/ / in a Dockerfile. - By default it's null. - - - - - runAsRoot is a bash script that will run as root in an - environment that overlays the existing layers of the base image with the - new resulting layer, including the previously copied - contents derivation. This can be similarly seen as - RUN ... in a Dockerfile. - - - Using this parameter requires the kvm device to be - available. - - - - - - - config is used to specify the configuration of the - containers that will be started off the built image in Docker. The - available options are listed in the - - Docker Image Specification v1.2.0 . - - - + + + + name specifies the name of the resulting image. This is + the only required argument for buildImage. + + + + + tag specifies the tag of the resulting image. By + default it's null, which indicates that the nix output + hash will be used as tag. + + + + + fromImage is the repository tarball containing the base + image. It must be a valid Docker image, such as exported by + docker save. By default it's null, + which can be seen as equivalent to FROM scratch of a + Dockerfile. + + + + + fromImageName can be used to further specify the base + image within the repository, in case it contains multiple images. By + default it's null, in which case + buildImage will peek the first image available in the + repository. + + + + + fromImageTag can be used to further specify the tag of + the base image within the repository, in case an image contains multiple + tags. By default it's null, in which case + buildImage will peek the first tag available for the + base image. + + + + + contents is a derivation that will be copied in the new + layer of the resulting image. This can be similarly seen as ADD + contents/ / in a Dockerfile. By default + it's null. + + + + + runAsRoot is a bash script that will run as root in an + environment that overlays the existing layers of the base image with the + new resulting layer, including the previously copied + contents derivation. This can be similarly seen as + RUN ... in a Dockerfile. + + + Using this parameter requires the kvm device to be + available. + + + + + + + config is used to specify the configuration of the + containers that will be started off the built image in Docker. The + available options are listed in the + + Docker Image Specification v1.2.0 . + + + - - After the new layer has been created, its closure (to which - contents, config and - runAsRoot contribute) will be copied in the layer - itself. Only new dependencies that are not already in the existing layers - will be copied. - + + After the new layer has been created, its closure (to which + contents, config and + runAsRoot contribute) will be copied in the layer itself. + Only new dependencies that are not already in the existing layers will be + copied. + + + + At the end of the process, only one new single layer will be produced and + added to the resulting image. + + + + The resulting repository will only list the single image + image/tag. In the case of + it would be + redis/latest. + + + + It is possible to inspect the arguments with which an image was built using + its buildArgs attribute. + + - At the end of the process, only one new single layer will be produced and - added to the resulting image. + If you see errors similar to getProtocolByName: does not exist (no + such protocol name: tcp) you may need to add + pkgs.iana-etc to contents. + + - The resulting repository will only list the single image - image/tag. In the case of - it would be - redis/latest. + If you see errors similar to Error_Protocol ("certificate has + unknown CA",True,UnknownCa) you may need to add + pkgs.cacert to contents. + + + Impurely Defining a Docker Layer's Creation Date - It is possible to inspect the arguments with which an image was built using - its buildArgs attribute. + By default buildImage will use a static date of one + second past the UNIX Epoch. This allows buildImage to + produce binary reproducible images. When listing images with + docker list images, the newly created images will be + listed like this: - - - - If you see errors similar to getProtocolByName: does not exist - (no such protocol name: tcp) you may need to add - pkgs.iana-etc to contents. - - - - - - If you see errors similar to Error_Protocol ("certificate has - unknown CA",True,UnknownCa) you may need to add - pkgs.cacert to contents. - - - - - Impurely Defining a Docker Layer's Creation Date - - By default buildImage will use a static - date of one second past the UNIX Epoch. This allows - buildImage to produce binary reproducible - images. When listing images with docker list - images, the newly created images will be listed like - this: - - - - You can break binary reproducibility but have a sorted, - meaningful CREATED column by setting - created to now. - - + You can break binary reproducibility but have a sorted, meaningful + CREATED column by setting created to + now. + + - - and now the Docker CLI will display a reasonable date and - sort the images as expected: - + and now the Docker CLI will display a reasonable date and sort the images + as expected: + - however, the produced images will not be binary reproducible. - - -
+ however, the produced images will not be binary reproducible. + + +
-
- buildLayeredImage +
+ buildLayeredImage - - Create a Docker image with many of the store paths being on their own layer - to improve sharing between images. - + + Create a Docker image with many of the store paths being on their own layer + to improve sharing between images. + - - - - name - - - - The name of the resulting image. - - - - - - tag optional - - - - Tag of the generated image. - - - Default: the output path's hash - - - - - - contents optional - - - - Top level paths in the container. Either a single derivation, or a list - of derivations. - - - Default: [] - - - - - - config optional - - - - Run-time configuration of the container. A full list of the options are - available at in the - - Docker Image Specification v1.2.0 . - - - Default: {} - - - - - - created optional - - - - Date and time the layers were created. Follows the same - now exception supported by - buildImage. - - - Default: 1970-01-01T00:00:01Z - - - - - - maxLayers optional - - - - Maximum number of layers to create. - - - Default: 24 - - - - + + + + name + + + + The name of the resulting image. + + + + + + tag optional + + + + Tag of the generated image. + + + Default: the output path's hash + + + + + + contents optional + + + + Top level paths in the container. Either a single derivation, or a list + of derivations. + + + Default: [] + + + + + + config optional + + + + Run-time configuration of the container. A full list of the options are + available at in the + + Docker Image Specification v1.2.0 . + + + Default: {} + + + + + + created optional + + + + Date and time the layers were created. Follows the same + now exception supported by + buildImage. + + + Default: 1970-01-01T00:00:01Z + + + + + + maxLayers optional + + + + Maximum number of layers to create. + + + Default: 24 + + + + -
- Behavior of <varname>contents</varname> in the final image +
+ Behavior of <varname>contents</varname> in the final image - - Each path directly listed in contents will have a - symlink in the root of the image. - + + Each path directly listed in contents will have a + symlink in the root of the image. + - - For example: + + For example: - will create symlinks for all the paths in the hello - package: + will create symlinks for all the paths in the hello + package: /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello /share/info/hello.info -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/info/hello.info /share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo ]]> - -
+ +
-
- Automatic inclusion of <varname>config</varname> references +
+ Automatic inclusion of <varname>config</varname> references - - The closure of config is automatically included in the - closure of the final image. - + + The closure of config is automatically included in the + closure of the final image. + - - This allows you to make very simple Docker images with very little code. - This container will start up and run hello: + + This allows you to make very simple Docker images with very little code. + This container will start up and run hello: - -
- -
- Adjusting <varname>maxLayers</varname> - - - Increasing the maxLayers increases the number of layers - which have a chance to be shared between different images. - - - - Modern Docker installations support up to 128 layers, however older - versions support as few as 42. - + +
- - If the produced image will not be extended by other Docker builds, it is - safe to set maxLayers to 128. - However it will be impossible to extend the image further. - +
+ Adjusting <varname>maxLayers</varname> - - The first (maxLayers-2) most "popular" paths will have - their own individual layers, then layer #maxLayers-1 - will contain all the remaining "unpopular" paths, and finally layer - #maxLayers will contain the Image configuration. - + + Increasing the maxLayers increases the number of layers + which have a chance to be shared between different images. + - - Docker's Layers are not inherently ordered, they are content-addressable - and are not explicitly layered until they are composed in to an Image. - -
-
+ + Modern Docker installations support up to 128 layers, however older + versions support as few as 42. + -
- pullImage + + If the produced image will not be extended by other Docker builds, it is + safe to set maxLayers to 128. However + it will be impossible to extend the image further. + - This function is analogous to the docker pull command, - in that can be used to pull a Docker image from a Docker registry. By - default Docker Hub is - used to pull images. + The first (maxLayers-2) most "popular" paths will have + their own individual layers, then layer #maxLayers-1 + will contain all the remaining "unpopular" paths, and finally layer + #maxLayers will contain the Image configuration. - Its parameters are described in the example below: + Docker's Layers are not inherently ordered, they are content-addressable + and are not explicitly layered until they are composed in to an Image. +
+
- - Docker pull +
+ pullImage + + + This function is analogous to the docker pull command, in + that can be used to pull a Docker image from a Docker registry. By default + Docker Hub is used to pull + images. + + + + Its parameters are described in the example below: + + + + Docker pull pullImage { imageName = "nixos/nix"; @@ -424,86 +423,86 @@ pullImage { arch = "x86_64"; } - + - - - - imageName specifies the name of the image to be - downloaded, which can also include the registry namespace (e.g. - nixos). This argument is required. - - - - - imageDigest specifies the digest of the image to be - downloaded. Skopeo can be used to get the digest of an image, with its - inspect subcommand. Since a given - imageName may transparently refer to a manifest list - of images which support multiple architectures and/or operating systems, - supply the `--override-os` and `--override-arch` arguments to specify - exactly which image you want. By default it will match the OS and - architecture of the host the command is run on. + + + + imageName specifies the name of the image to be + downloaded, which can also include the registry namespace (e.g. + nixos). This argument is required. + + + + + imageDigest specifies the digest of the image to be + downloaded. Skopeo can be used to get the digest of an image, with its + inspect subcommand. Since a given + imageName may transparently refer to a manifest list of + images which support multiple architectures and/or operating systems, + supply the `--override-os` and `--override-arch` arguments to specify + exactly which image you want. By default it will match the OS and + architecture of the host the command is run on. $ 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'" sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b - This argument is required. - - - - - finalImageTag, if specified, this is the tag of the - image to be created. Note it is never used to fetch the image since we - prefer to rely on the immutable digest ID. By default it's - latest. - - - - - sha256 is the checksum of the whole fetched image. - This argument is required. - - - - - os, if specified, is the operating system of the - fetched image. By default it's linux. - - - - - arch, if specified, is the cpu architecture of the - fetched image. By default it's x86_64. - - - -
- -
- exportImage - - - This function is analogous to the docker export command, - in that can used to flatten a Docker image that contains multiple layers. - It is in fact the result of the merge of all the layers of the image. As - such, the result is suitable for being imported in Docker with - docker import. - - - + This argument is required. + + + + + finalImageTag, if specified, this is the tag of the + image to be created. Note it is never used to fetch the image since we + prefer to rely on the immutable digest ID. By default it's + latest. + + + + + sha256 is the checksum of the whole fetched image. This + argument is required. + + + - Using this function requires the kvm device to be - available. + os, if specified, is the operating system of the + fetched image. By default it's linux. - + + + + arch, if specified, is the cpu architecture of the + fetched image. By default it's x86_64. + + + +
+ +
+ exportImage + + This function is analogous to the docker export command, + in that can used to flatten a Docker image that contains multiple layers. It + is in fact the result of the merge of all the layers of the image. As such, + the result is suitable for being imported in Docker with docker + import. + + + - The parameters of exportImage are the following: + Using this function requires the kvm device to be + available. + - - Docker export + + The parameters of exportImage are the following: + + + + Docker export exportImage { fromImage = someLayeredImage; @@ -513,34 +512,33 @@ exportImage { name = someLayeredImage.name; } - + - - The parameters relative to the base image have the same synopsis as - described in , except - that fromImage is the only required argument in this - case. - + + The parameters relative to the base image have the same synopsis as + described in , except that + fromImage is the only required argument in this case. + - - The name argument is the name of the derivation output, - which defaults to fromImage.name. - -
+ + The name argument is the name of the derivation output, + which defaults to fromImage.name. + +
-
- shadowSetup +
+ shadowSetup - - This constant string is a helper for setting up the base files for managing - users and groups, only if such files don't exist already. It is suitable - for being used in a runAsRoot - script for cases like - in the example below: - + + This constant string is a helper for setting up the base files for managing + users and groups, only if such files don't exist already. It is suitable for + being used in a runAsRoot + script for cases like + in the example below: + - - Shadow base files + + Shadow base files buildImage { name = "shadow-basic"; @@ -555,12 +553,12 @@ buildImage { ''; } - + - - Creating base files like /etc/passwd or - /etc/login.defs are necessary for shadow-utils to - manipulate users and groups. - -
+ + Creating base files like /etc/passwd or + /etc/login.defs are necessary for shadow-utils to + manipulate users and groups. +
+
diff --git a/doc/functions/fhs-environments.xml b/doc/functions/fhs-environments.xml index bfe0db522a1d..79682080be31 100644 --- a/doc/functions/fhs-environments.xml +++ b/doc/functions/fhs-environments.xml @@ -2,116 +2,114 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-fhs-environments"> - buildFHSUserEnv + 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: - + + 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. - - - - + + + + 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: - + + One can create a simple environment using a shell.nix like + that: + {} }: @@ -134,11 +132,11 @@ }).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. - -
+ + 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/functions/generators.xml b/doc/functions/generators.xml index 0a9c346145f9..e860b10e8979 100644 --- a/doc/functions/generators.xml +++ b/doc/functions/generators.xml @@ -2,33 +2,32 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-generators"> - Generators + Generators - - Generators are functions that create file formats from nix data structures, - e. g. for configuration files. There are generators available for: - INI, JSON and YAML - + + Generators are functions that create file formats from nix data structures, + e. g. for configuration files. There are generators available for: + INI, JSON and YAML + - - All generators follow a similar call interface: generatorName - configFunctions data, where configFunctions is an - attrset of user-defined functions that format nested parts of the content. - They each have common defaults, so often they do not need to be set - manually. An example is mkSectionName ? (name: libStr.escape [ "[" "]" - ] name) from the INI generator. It receives the - name of a section and sanitizes it. The default - mkSectionName escapes [ and - ] with a backslash. - + + All generators follow a similar call interface: generatorName + configFunctions data, where configFunctions is an + attrset of user-defined functions that format nested parts of the content. + They each have common defaults, so often they do not need to be set manually. + An example is mkSectionName ? (name: libStr.escape [ "[" "]" ] + name) from the INI generator. It receives the name + of a section and sanitizes it. The default mkSectionName + escapes [ and ] with a backslash. + - - Generators can be fine-tuned to produce exactly the file format required by - your application/service. One example is an INI-file format which uses - : as separator, the strings - "yes"/"no" as boolean values and - requires all string values to be quoted: - + + Generators can be fine-tuned to produce exactly the file format required by + your application/service. One example is an INI-file format which uses + : as separator, the strings + "yes"/"no" as boolean values and + requires all string values to be quoted: + with lib; @@ -60,9 +59,9 @@ in customToINI { } - - This will produce the following INI file as nix string: - + + This will produce the following INI file as nix string: + [main] @@ -76,15 +75,15 @@ str\:ange:"very::strange" merge:"diff3" - - - Nix store paths can be converted to strings by enclosing a derivation - attribute like so: "${drv}". - - - + - Detailed documentation for each generator can be found in - lib/generators.nix. + Nix store paths can be converted to strings by enclosing a derivation + attribute like so: "${drv}". - + + + + Detailed documentation for each generator can be found in + lib/generators.nix. + + diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml index dc81e3795065..99e2a63631a7 100644 --- a/doc/functions/overrides.xml +++ b/doc/functions/overrides.xml @@ -2,28 +2,28 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-overrides"> - Overriding + Overriding - - Sometimes one wants to override parts of nixpkgs, e.g. - derivation attributes, the results of derivations or even the whole package - set. - + + Sometimes one wants to override parts of nixpkgs, e.g. + derivation attributes, the results of derivations or even the whole package + set. + -
- <pkg>.override +
+ <pkg>.override - - The function override is usually available for all the - derivations in the nixpkgs expression (pkgs). - + + The function override is usually available for all the + derivations in the nixpkgs expression (pkgs). + - - It is used to override the arguments passed to a function. - + + It is used to override the arguments passed to a function. + - - Example usages: + + Example usages: pkgs.foo.override { arg1 = val1; arg2 = val2; ... } import pkgs.path { overlays = [ (self: super: { @@ -35,105 +35,103 @@ mypkg = pkgs.callPackage ./mypkg.nix { mydep = pkgs.mydep.override { ... }; } - + - - In the first example, pkgs.foo is the result of a - function call with some default arguments, usually a derivation. Using - pkgs.foo.override will call the same function with the - given new arguments. - -
+ + In the first example, pkgs.foo is the result of a + function call with some default arguments, usually a derivation. Using + pkgs.foo.override will call the same function with the + given new arguments. + +
-
- <pkg>.overrideAttrs +
+ <pkg>.overrideAttrs - - The function overrideAttrs allows overriding the - attribute set passed to a stdenv.mkDerivation call, - producing a new derivation based on the original one. This function is - available on all derivations produced by the - stdenv.mkDerivation function, which is most packages in - the nixpkgs expression pkgs. - + + The function overrideAttrs allows overriding the + attribute set passed to a stdenv.mkDerivation call, + producing a new derivation based on the original one. This function is + available on all derivations produced by the + stdenv.mkDerivation function, which is most packages in + the nixpkgs expression pkgs. + - - Example usage: + + Example usage: helloWithDebug = pkgs.hello.overrideAttrs (oldAttrs: rec { separateDebugInfo = true; }); - + - - In the above example, the separateDebugInfo attribute is - overridden to be true, thus building debug info for - helloWithDebug, while all other attributes will be - retained from the original hello package. - + + In the above example, the separateDebugInfo attribute is + overridden to be true, thus building debug info for + helloWithDebug, while all other attributes will be + retained from the original hello package. + - - The argument oldAttrs is conventionally used to refer to - the attr set originally passed to stdenv.mkDerivation. - + + The argument oldAttrs is conventionally used to refer to + the attr set originally passed to stdenv.mkDerivation. + - - - Note that separateDebugInfo is processed only by the - stdenv.mkDerivation function, not the generated, raw - Nix derivation. Thus, using overrideDerivation will not - work in this case, as it overrides only the attributes of the final - derivation. It is for this reason that overrideAttrs - should be preferred in (almost) all cases to - overrideDerivation, i.e. to allow using - sdenv.mkDerivation to process input arguments, as well - as the fact that it is easier to use (you can use the same attribute names - you see in your Nix code, instead of the ones generated (e.g. - buildInputs vs nativeBuildInputs, - and involves less typing. - - -
- -
- <pkg>.overrideDerivation - - - - You should prefer overrideAttrs in almost all cases, - see its documentation for the reasons why. - overrideDerivation is not deprecated and will continue - to work, but is less nice to use and does not have as many abilities as - overrideAttrs. - - - - - - Do not use this function in Nixpkgs as it evaluates a Derivation before - modifying it, which breaks package abstraction and removes error-checking - of function arguments. In addition, this evaluation-per-function - application incurs a performance penalty, which can become a problem if - many overrides are used. It is only intended for ad-hoc customisation, - such as in ~/.config/nixpkgs/config.nix. - - + + + Note that separateDebugInfo is processed only by the + stdenv.mkDerivation function, not the generated, raw Nix + derivation. Thus, using overrideDerivation will not work + in this case, as it overrides only the attributes of the final derivation. + It is for this reason that overrideAttrs should be + preferred in (almost) all cases to overrideDerivation, + i.e. to allow using sdenv.mkDerivation to process input + arguments, as well as the fact that it is easier to use (you can use the + same attribute names you see in your Nix code, instead of the ones + generated (e.g. buildInputs vs + nativeBuildInputs, and involves less typing. + + +
+ +
+ <pkg>.overrideDerivation + - The function overrideDerivation creates a new derivation - based on an existing one by overriding the original's attributes with the - attribute set produced by the specified function. This function is - available on all derivations defined using the - makeOverridable function. Most standard - derivation-producing functions, such as - stdenv.mkDerivation, are defined using this function, - which means most packages in the nixpkgs expression, - pkgs, have this function. + You should prefer overrideAttrs in almost all cases, see + its documentation for the reasons why. + overrideDerivation is not deprecated and will continue + to work, but is less nice to use and does not have as many abilities as + overrideAttrs. + + - Example usage: + Do not use this function in Nixpkgs as it evaluates a Derivation before + modifying it, which breaks package abstraction and removes error-checking + of function arguments. In addition, this evaluation-per-function + application incurs a performance penalty, which can become a problem if + many overrides are used. It is only intended for ad-hoc customisation, such + as in ~/.config/nixpkgs/config.nix. + + + + + The function overrideDerivation creates a new derivation + based on an existing one by overriding the original's attributes with the + attribute set produced by the specified function. This function is available + on all derivations defined using the makeOverridable + function. Most standard derivation-producing functions, such as + stdenv.mkDerivation, are defined using this function, + which means most packages in the nixpkgs expression, + pkgs, have this function. + + + + Example usage: mySed = pkgs.gnused.overrideDerivation (oldAttrs: { name = "sed-4.2.2-pre"; @@ -144,62 +142,62 @@ mySed = pkgs.gnused.overrideDerivation (oldAttrs: { patches = []; }); - + - - In the above example, the name, src, - and patches of the derivation will be overridden, while - all other attributes will be retained from the original derivation. - + + In the above example, the name, src, + and patches of the derivation will be overridden, while + all other attributes will be retained from the original derivation. + + + + The argument oldAttrs is used to refer to the attribute + set of the original derivation. + + - The argument oldAttrs is used to refer to the attribute - set of the original derivation. + A package's attributes are evaluated *before* being modified by the + overrideDerivation function. For example, the + name attribute reference in url = + "mirror://gnu/hello/${name}.tar.gz"; is filled-in *before* the + overrideDerivation function modifies the attribute set. + This means that overriding the name attribute, in this + example, *will not* change the value of the url + attribute. Instead, we need to override both the name + *and* url attributes. + +
- - - A package's attributes are evaluated *before* being modified by the - overrideDerivation function. For example, the - name attribute reference in url = - "mirror://gnu/hello/${name}.tar.gz"; is filled-in *before* the - overrideDerivation function modifies the attribute set. - This means that overriding the name attribute, in this - example, *will not* change the value of the url - attribute. Instead, we need to override both the name - *and* url attributes. - - -
- -
- lib.makeOverridable +
+ lib.makeOverridable - - The function lib.makeOverridable is used to make the - result of a function easily customizable. This utility only makes sense for - functions that accept an argument set and return an attribute set. - + + The function lib.makeOverridable is used to make the + result of a function easily customizable. This utility only makes sense for + functions that accept an argument set and return an attribute set. + - - Example usage: + + Example usage: f = { a, b }: { result = a+b; }; c = lib.makeOverridable f { a = 1; b = 2; }; - + - - The variable c is the value of the f - function applied with some default arguments. Hence the value of - c.result is 3, in this example. - + + The variable c is the value of the f + function applied with some default arguments. Hence the value of + c.result is 3, in this example. + - - The variable c however also has some additional - functions, like c.override which - can be used to override the default arguments. In this example the value of - (c.override { a = 4; }).result is 6. - -
+ + The variable c however also has some additional + functions, like c.override which can + be used to override the default arguments. In this example the value of + (c.override { a = 4; }).result is 6. +
+ diff --git a/doc/functions/shell.xml b/doc/functions/shell.xml index a8d2a30cb508..e5031c9463c0 100644 --- a/doc/functions/shell.xml +++ b/doc/functions/shell.xml @@ -2,19 +2,18 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-pkgs-mkShell"> - pkgs.mkShell + 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. - + + 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 +
+ Usage - {} }: pkgs.mkShell { # this will make all the build inputs from hello and gnutar @@ -23,5 +22,5 @@ pkgs.mkShell { buildInputs = [ pkgs.gnumake ]; } ]]> -
+
diff --git a/doc/package-notes.xml b/doc/package-notes.xml index d8f55ef0a856..5a13d18aa595 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -671,8 +671,9 @@ overrides = self: super: rec { plugins = with availablePlugins; [ python perl ]; } } - If the configure function returns an attrset without the plugins - attribute, availablePlugins will be used automatically. + If the configure function returns an attrset without the + plugins attribute, availablePlugins + will be used automatically. @@ -706,9 +707,11 @@ overrides = self: super: rec { }; } + - WeeChat allows to set defaults on startup using the --run-command. - The configure method can be used to pass commands to the program: + WeeChat allows to set defaults on startup using the + --run-command. The configure method + can be used to pass commands to the program: weechat.override { configure = { availablePlugins, ... }: { init = '' @@ -717,12 +720,14 @@ overrides = self: super: rec { ''; }; } - Further values can be added to the list of commands when running - weechat --run-command "your-commands". + Further values can be added to the list of commands when running + weechat --run-command "your-commands". + - Additionally it's possible to specify scripts to be loaded when starting weechat. - These will be loaded before the commands from init: + Additionally it's possible to specify scripts to be loaded when starting + weechat. These will be loaded before the commands from + init: weechat.override { configure = { availablePlugins, ... }: { scripts = with pkgs.weechatScripts; [ @@ -734,11 +739,13 @@ overrides = self: super: rec { }; } + - In nixpkgs there's a subpackage which contains derivations for - WeeChat scripts. Such derivations expect a passthru.scripts attribute - which contains a list of all scripts inside the store path. Furthermore all scripts - have to live in $out/share. An exemplary derivation looks like this: + In nixpkgs there's a subpackage which contains + derivations for WeeChat scripts. Such derivations expect a + passthru.scripts attribute which contains a list of all + scripts inside the store path. Furthermore all scripts have to live in + $out/share. An exemplary derivation looks like this: { stdenv, fetchurl }: stdenv.mkDerivation { @@ -817,20 +824,26 @@ citrix_receiver.override {
ibus-engines.typing-booster - This package is an ibus-based completion method to speed up typing. + + This package is an ibus-based completion method to speed up typing. +
Activating the engine - IBus needs to be configured accordingly to activate typing-booster. The configuration - depends on the desktop manager in use. For detailed instructions, please refer to the - upstream docs. + IBus needs to be configured accordingly to activate + typing-booster. The configuration depends on the desktop + manager in use. For detailed instructions, please refer to the + upstream + docs. + - On NixOS you need to explicitly enable ibus with given engines - before customizing your desktop to use typing-booster. This can be achieved - using the ibus module: + On NixOS you need to explicitly enable ibus with given + engines before customizing your desktop to use + typing-booster. This can be achieved using the + ibus module: { pkgs, ... }: { i18n.inputMethod = { enabled = "ibus"; @@ -844,17 +857,20 @@ citrix_receiver.override { Using custom hunspell dictionaries - The IBus engine is based on hunspell to support completion in many languages. - By default the dictionaries de-de, en-us, es-es, - it-it, sv-se and sv-fi - are in use. To add another dictionary, the package can be overridden like this: + The IBus engine is based on hunspell to support + completion in many languages. By default the dictionaries + de-de, en-us, + es-es, it-it, + sv-se and sv-fi are in use. To add + another dictionary, the package can be overridden like this: ibus-engines.typing-booster.override { langs = [ "de-at" "en-gb" ]; } + - Note: each language passed to langs must be an attribute name in - pkgs.hunspellDicts. + Note: each language passed to langs must be an + attribute name in pkgs.hunspellDicts.
@@ -862,10 +878,12 @@ citrix_receiver.override { Built-in emoji picker - The ibus-engines.typing-booster package contains a program - named emoji-picker. To display all emojis correctly, - a special font such as noto-fonts-emoji is needed: + The ibus-engines.typing-booster package contains a + program named emoji-picker. To display all emojis + correctly, a special font such as noto-fonts-emoji is + needed: + On NixOS it can be installed using the following expression: { pkgs, ... }: {