diff options
Diffstat (limited to 'doc/overlays.xml')
| -rw-r--r-- | doc/overlays.xml | 256 |
1 files changed, 143 insertions, 113 deletions
diff --git a/doc/overlays.xml b/doc/overlays.xml index cc0aef447d2d..2decf9febe80 100644 --- a/doc/overlays.xml +++ b/doc/overlays.xml @@ -1,95 +1,117 @@ <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chap-overlays"> - -<title>Overlays</title> - -<para>This chapter describes how to extend and change Nixpkgs packages using -overlays. Overlays are used to add layers in the fix-point used by Nixpkgs -to compose the set of all packages.</para> - -<para>Nixpkgs can be configured with a list of overlays, which are -applied in order. This means that the order of the overlays can be significant -if multiple layers override the same package.</para> - + <title>Overlays</title> + <para> + This chapter describes how to extend and change Nixpkgs packages using + overlays. Overlays are used to add layers in the fix-point used by Nixpkgs to + compose the set of all packages. + </para> + <para> + Nixpkgs can be configured with a list of overlays, which are applied in + order. This means that the order of the overlays can be significant if + multiple layers override the same package. + </para> <!--============================================================--> - -<section xml:id="sec-overlays-install"> -<title>Installing overlays</title> - -<para>The list of overlays is determined as follows.</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> - -<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 looked up independently.</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> - -</section> - + <section xml:id="sec-overlays-install"> + <title>Installing overlays</title> + + <para> + The list of overlays is determined as follows. + </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> + + <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 looked up independently. + </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> + </section> <!--============================================================--> + <section xml:id="sec-overlays-definition"> + <title>Defining overlays</title> -<section xml:id="sec-overlays-definition"> -<title>Defining overlays</title> - -<para>Overlays are Nix functions which accept two arguments, -conventionally called <varname>self</varname> and <varname>super</varname>, -and return a set of packages. For example, the following is a valid overlay.</para> + <para> + Overlays are Nix functions which accept two arguments, conventionally called + <varname>self</varname> and <varname>super</varname>, and return a set of + packages. For example, the following is a valid overlay. + </para> <programlisting> self: super: @@ -104,31 +126,39 @@ self: super: } </programlisting> -<para>The first argument (<varname>self</varname>) corresponds to the final package -set. You should use this set for the dependencies of all packages specified in your -overlay. For example, all the dependencies of <varname>rr</varname> in the example above come -from <varname>self</varname>, as well as the overridden dependencies used in the -<varname>boost</varname> override.</para> - -<para>The second argument (<varname>super</varname>) -corresponds to the result of the evaluation of the previous stages of -Nixpkgs. It does not contain any of the packages added by the current -overlay, nor any of the following overlays. This set should be used either -to refer to packages you wish to override, or to access functions defined -in Nixpkgs. For example, the original recipe of <varname>boost</varname> -in the above example, comes from <varname>super</varname>, as well as the -<varname>callPackage</varname> function.</para> - -<para>The value returned by this function should be a set similar to -<filename>pkgs/top-level/all-packages.nix</filename>, containing -overridden and/or new packages.</para> - -<para>Overlays are similar to other methods for customizing Nixpkgs, in particular -the <literal>packageOverrides</literal> attribute described in <xref linkend="sec-modify-via-packageOverrides"/>. -Indeed, <literal>packageOverrides</literal> acts as an overlay with only the -<varname>super</varname> argument. It is therefore appropriate for basic use, -but overlays are more powerful and easier to distribute.</para> - -</section> - + <para> + The first argument (<varname>self</varname>) corresponds to the final + package set. You should use this set for the dependencies of all packages + specified in your overlay. For example, all the dependencies of + <varname>rr</varname> in the example above come from + <varname>self</varname>, as well as the overridden dependencies used in the + <varname>boost</varname> override. + </para> + + <para> + The second argument (<varname>super</varname>) corresponds to the result of + the evaluation of the previous stages of Nixpkgs. It does not contain any of + the packages added by the current overlay, nor any of the following + overlays. This set should be used either to refer to packages you wish to + override, or to access functions defined in Nixpkgs. For example, the + original recipe of <varname>boost</varname> in the above example, comes from + <varname>super</varname>, as well as the <varname>callPackage</varname> + function. + </para> + + <para> + The value returned by this function should be a set similar to + <filename>pkgs/top-level/all-packages.nix</filename>, containing overridden + and/or new packages. + </para> + + <para> + Overlays are similar to other methods for customizing Nixpkgs, in particular + the <literal>packageOverrides</literal> attribute described in + <xref linkend="sec-modify-via-packageOverrides"/>. Indeed, + <literal>packageOverrides</literal> acts as an overlay with only the + <varname>super</varname> argument. It is therefore appropriate for basic + use, but overlays are more powerful and easier to distribute. + </para> + </section> </chapter> |