diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/coding-conventions.xml | 5 | ||||
| -rw-r--r-- | doc/functions/overrides.xml | 13 | ||||
| -rw-r--r-- | doc/languages-frameworks/coq.xml | 4 | ||||
| -rw-r--r-- | doc/languages-frameworks/python.section.md | 2 | ||||
| -rw-r--r-- | doc/languages-frameworks/vim.section.md | 4 | ||||
| -rw-r--r-- | doc/overlays.xml | 191 | ||||
| -rw-r--r-- | doc/stdenv.xml | 38 |
7 files changed, 163 insertions, 94 deletions
diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index b3f7f093835c..3e8a0ea4a703 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -842,9 +842,12 @@ src = fetchFromGitHub { owner = "NixOS"; repo = "nix"; rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae"; - sha256 = "04yri911rj9j19qqqn6m82266fl05pz98inasni0vxr1cf1gdgv9"; + sha256 = "1i2yxndxb6yc9l6c99pypbd92lfq5aac4klq7y2v93c9qvx2cgpc"; } </programlisting> + Find the value to put as <literal>sha256</literal> by running + <literal>nix run -f '<nixpkgs>' nix-prefetch-github -c nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix</literal> + or <literal>nix-prefetch-url --unpack https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>. </para> </listitem> </itemizedlist> diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml index 021c4b41c360..1bd90d2a0c76 100644 --- a/doc/functions/overrides.xml +++ b/doc/functions/overrides.xml @@ -6,8 +6,14 @@ <para> Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g. - derivation attributes, the results of derivations or even the whole package - set. + derivation attributes, the results of derivations. + </para> + + <para> + These functions are used to make changes to packages, returning only single + packages. <link xlink:href="#chap-overlays">Overlays</link>, on the other + hand, can be used to combine the overridden packages across the entire + package set of Nixpkgs. </para> <section xml:id="sec-pkg-override"> @@ -25,6 +31,9 @@ <para> Example usages: <programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting> +<!-- TODO: move below programlisting to a new section about extending and overlays + and reference it + --> <programlisting> import pkgs.path { overlays = [ (self: super: { foo = super.foo.override { barSupport = true ; }; diff --git a/doc/languages-frameworks/coq.xml b/doc/languages-frameworks/coq.xml index 640b04c7da9d..4314df5c9df2 100644 --- a/doc/languages-frameworks/coq.xml +++ b/doc/languages-frameworks/coq.xml @@ -12,8 +12,8 @@ <para> Some extensions (plugins) might require OCaml and sometimes other OCaml - packages. The <literal>coq.ocamlPackages</literal> attribute can be used - to depend on the same package set Coq was built against. + packages. The <literal>coq.ocamlPackages</literal> attribute can be used to + depend on the same package set Coq was built against. </para> <para> diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index b52b79c62d91..e6c8ab37d68a 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -670,7 +670,7 @@ python3Packages.buildPythonApplication rec { sha256 = "035w8gqql36zlan0xjrzz9j4lh9hs0qrsgnbyw07qs7lnkvbdv9x"; }; - propagatedBuildInputs = with python3Packages; [ tornado_4 pythondaemon ]; + propagatedBuildInputs = with python3Packages; [ tornado_4 python-daemon ]; meta = with lib; { ... diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md index 1b235dbb52f6..2cec1543a249 100644 --- a/doc/languages-frameworks/vim.section.md +++ b/doc/languages-frameworks/vim.section.md @@ -23,6 +23,7 @@ Adding custom .vimrc lines can be done using the following code: ``` vim_configurable.customize { + # `name` specifies the name of the executable and package name = "vim-with-plugins"; vimrcConfig.customRC = '' @@ -31,6 +32,8 @@ vim_configurable.customize { } ``` +This configuration is used when vim is invoked with the command specified as name, in this case `vim-with-plugins`. + For Neovim the `configure` argument can be overridden to achieve the same: ``` @@ -83,6 +86,7 @@ The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.n { packageOverrides = pkgs: with pkgs; { myVim = vim_configurable.customize { + # `name` specifies the name of the executable and package name = "vim-with-plugins"; # add here code from the example section }; diff --git a/doc/overlays.xml b/doc/overlays.xml index 2decf9febe80..90dd163072d3 100644 --- a/doc/overlays.xml +++ b/doc/overlays.xml @@ -17,91 +17,122 @@ <title>Installing overlays</title> <para> - The list of overlays is determined as follows. + The list of overlays can be set either explicitly in a Nix expression, or + through <literal><nixpkgs-overlays></literal> or user configuration + files. </para> - <para> - If the <varname>overlays</varname> argument is not provided explicitly, we - look for overlays in a path. The path is determined as follows: - <orderedlist> - <listitem> - <para> - First, if an <varname>overlays</varname> argument to the nixpkgs function - itself is given, then that is used. - </para> - <para> - This can be passed explicitly when importing nipxkgs, for example - <literal>import <nixpkgs> { overlays = [ overlay1 overlay2 ]; - }</literal>. - </para> - </listitem> - <listitem> - <para> - Otherwise, if the Nix path entry <literal><nixpkgs-overlays></literal> - exists, we look for overlays at that path, as described below. - </para> - <para> - See the section on <literal>NIX_PATH</literal> in the Nix manual for more - details on how to set a value for - <literal><nixpkgs-overlays>.</literal> - </para> - </listitem> - <listitem> - <para> - If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and - <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look for - overlays at that path, as described below. It is an error if both exist. - </para> - </listitem> - </orderedlist> - </para> + <section xml:id="sec-overlays-argument"> + <title>Set overlays in NixOS or Nix expressions</title> - <para> - If we are looking for overlays at a path, then there are two cases: - <itemizedlist> - <listitem> - <para> - If the path is a file, then the file is imported as a Nix expression and - used as the list of overlays. - </para> - </listitem> - <listitem> - <para> - If the path is a directory, then we take the content of the directory, - order it lexicographically, and attempt to interpret each as an overlay - by: - <itemizedlist> - <listitem> - <para> - Importing the file, if it is a <literal>.nix</literal> file. - </para> - </listitem> - <listitem> - <para> - Importing a top-level <filename>default.nix</filename> file, if it is - a directory. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </itemizedlist> - </para> + <para> + On a NixOS system the value of the <literal>nixpkgs.overlays</literal> + option, if present, is passed to the system Nixpkgs directly as an + argument. Note that this does not affect the overlays for non-NixOS + operations (e.g. <literal>nix-env</literal>), which are + <link xlink:href="#sec-overlays-lookup">looked</link> up independently. + </para> - <para> - On a NixOS system the value of the <literal>nixpkgs.overlays</literal> - option, if present, is passed to the system Nixpkgs directly as an argument. - Note that this does not affect the overlays for non-NixOS operations (e.g. - <literal>nix-env</literal>), which are looked up independently. - </para> + <para> + The list of overlays can be passed explicitly when importing nixpkgs, for + example <literal>import <nixpkgs> { overlays = [ overlay1 overlay2 ]; + }</literal>. + </para> - <para> - The <filename>overlays.nix</filename> option therefore provides a convenient - way to use the same overlays for a NixOS system configuration and user - configuration: the same file can be used as - <filename>overlays.nix</filename> and imported as the value of - <literal>nixpkgs.overlays</literal>. - </para> + <para> + Further overlays can be added by calling the <literal>pkgs.extend</literal> + or <literal>pkgs.appendOverlays</literal>, although it is often preferable + to avoid these functions, because they recompute the Nixpkgs fixpoint, + which is somewhat expensive to do. + </para> + </section> + + <section xml:id="sec-overlays-lookup"> + <title>Install overlays via configuration lookup</title> + + <para> + The list of overlays is determined as follows. + </para> + + <para> + <orderedlist> + <listitem> + <para> + First, if an + <link xlink:href="#sec-overlays-argument"><varname>overlays</varname> + argument</link> to the nixpkgs function itself is given, then that is + used and no path lookup will be performed. + </para> + </listitem> + <listitem> + <para> + Otherwise, if the Nix path entry + <literal><nixpkgs-overlays></literal> exists, we look for overlays at + that path, as described below. + </para> + <para> + See the section on <literal>NIX_PATH</literal> in the Nix manual for + more details on how to set a value for + <literal><nixpkgs-overlays>.</literal> + </para> + </listitem> + <listitem> + <para> + If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and + <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look + for overlays at that path, as described below. It is an error if both + exist. + </para> + </listitem> + </orderedlist> + </para> + + <para> + If we are looking for overlays at a path, then there are two cases: + <itemizedlist> + <listitem> + <para> + If the path is a file, then the file is imported as a Nix expression and + used as the list of overlays. + </para> + </listitem> + <listitem> + <para> + If the path is a directory, then we take the content of the directory, + order it lexicographically, and attempt to interpret each as an overlay + by: + <itemizedlist> + <listitem> + <para> + Importing the file, if it is a <literal>.nix</literal> file. + </para> + </listitem> + <listitem> + <para> + Importing a top-level <filename>default.nix</filename> file, if it is + a directory. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + + <para> + Because overlays that are set in NixOS configuration do not affect + non-NixOS operations such as <literal>nix-env</literal>, the + <filename>overlays.nix</filename> option provides a convenient way to use + the same overlays for a NixOS system configuration and user configuration: + the same file can be used as <filename>overlays.nix</filename> and imported + as the value of <literal>nixpkgs.overlays</literal>. + </para> + +<!-- TODO: Example of sharing overlays between NixOS configuration + and configuration lookup. Also reference the example + from the sec-overlays-argument paragraph about NixOS. + --> + </section> </section> <!--============================================================--> <section xml:id="sec-overlays-definition"> diff --git a/doc/stdenv.xml b/doc/stdenv.xml index cc0c13c54471..b2f30bf08db1 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -372,7 +372,7 @@ let f(h, h + 1, i) = i + h They are programs/libraries used at build time that furthermore produce programs/libraries also used at build time. If the dependency doesn't care about the target platform (i.e. isn't a compiler or similar tool), - put it in <varname>nativeBuildInputs</varname>instead. The most common + put it in <varname>nativeBuildInputs</varname> instead. The most common use for this <literal>buildPackages.stdenv.cc</literal>, the default C compiler for this role. That example crops up more than one might think in old commonly used C libraries. @@ -2099,13 +2099,13 @@ someVar=$(stripHash $name) </para> <para> - In order to alleviate this burden, the <firstterm>setup - hook></firstterm>mechanism was written, where any package can include a - shell script that [by convention rather than enforcement by Nix], any - downstream reverse-dependency will source as part of its build process. That - allows the downstream dependency to merely specify its dependencies, and - lets those dependencies effectively initialize themselves. No boilerplate - mirroring the list of dependencies is needed. + In order to alleviate this burden, the <firstterm>setup hook</firstterm> + mechanism was written, where any package can include a shell script that [by + convention rather than enforcement by Nix], any downstream + reverse-dependency will source as part of its build process. That allows the + downstream dependency to merely specify its dependencies, and lets those + dependencies effectively initialize themselves. No boilerplate mirroring the + list of dependencies is needed. </para> <para> @@ -2445,6 +2445,28 @@ addEnvHooks "$hostOffset" myBashFunction </para> </listitem> </varlistentry> + <varlistentry> + <term> + breakpointHook + </term> + <listitem> + <para> + This hook will make a build pause instead of stopping when a failure + happen. It prevents nix to cleanup the build environment immediatly and + allows the user to attach to a build environment using the + <command>cntr</command> command. On build error it will print the + instruction that are neccessary for <command>cntr</command>. Installing + cntr and running the command will provide shell access to the build + sandbox of failed build. At <filename>/var/lib/cntr</filename> the + sandbox filesystem is mounted. All commands and files of the system are + still accessible within the shell. To execute commands from the sandbox + use the cntr exec subcommand. Note that <command>cntr</command> also + needs to be executed on the machine that is doing the build, which might + be not the case when remote builders are enabled. + <command>cntr</command> is only supported on linux based platforms. + </para> + </listitem> + </varlistentry> </variablelist> </para> </section> |