diff options
author | Nicolas B. Pierron <nicolas.b.pierron@nbp.name> | 2017-01-15 15:07:29 +0000 |
---|---|---|
committer | Nicolas B. Pierron <nicolas.b.pierron@gmail.com> | 2017-01-16 01:17:33 +0100 |
commit | 2d6532b3302af212e7f3fa09f43844e9984219b4 (patch) | |
tree | 700f6d02c162173351e69dfafe71fe9a2064e763 /doc | |
parent | ae7e893de1c03564b40f8e6d1d9591bbc1082cc9 (diff) |
Update overlay documentation by following nits from aneeshusa.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/overlays.xml | 80 |
1 files changed, 40 insertions, 40 deletions
diff --git a/doc/overlays.xml b/doc/overlays.xml index 4ad2764f33f9..c921289fd6c3 100644 --- a/doc/overlays.xml +++ b/doc/overlays.xml @@ -4,56 +4,53 @@ <title>Overlays</title> -<para>This chapter describes how to extend and change Nixpkgs content using -overlays. Overlays are used to add layers in the fix-point used by Nixpkgs -to bind the dependencies of all packages.</para> +<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> <!--============================================================--> <section xml:id="sec-overlays-install"> <title>Installing Overlays</title> -<para>The set of overlays are looked for in the following order, only the +<para>The set of overlays is looked for in the following places. The first one present is considered, and all the rest are ignored: <orderedlist> <listitem> - <para>As argument of the imported attribute set. When importing Nixpkgs, + <para>As an argument of the imported attribute set. When importing Nixpkgs, the <varname>overlays</varname> attribute argument can be set to a list of - functions, which would be describe in <xref linkend="sec-overlays-layout"/>.</para> + functions, which is described in <xref linkend="sec-overlays-layout"/>.</para> </listitem> <listitem> - <para>As a directory pointed by the environment variable named -<varname>NIXPKGS_OVERLAYS</varname>. This directory can contain symbolic -links to Nix expressions. - + <para>In the directory pointed by the environment variable +<varname>NIXPKGS_OVERLAYS</varname>. </listitem> <listitem> - <para>As the directory located at -<filename>~/.nixpkgs/overlays/</filename>. This directory can contain -symbolic links to Nix expressions. - + <para>In the directory <filename>~/.nixpkgs/overlays/</filename>. </listitem> </orderedlist> </para> -<para>For the second and third option, the directory contains either -directories providing a default.nix expression, or files, or symbolic links -to the entry Nix expression of the overlay. These Nix expressions are -following the syntax described in <xref -linkend="sec-overlays-layout"/>.</para> +<para>For the second and third option, the directory should contain Nix expressions defining the +overlays. Each overlay can be a file, a directory containing a +<filename>default.nix</filename>, or a symlink to one of those. The expressions should follow +the syntax described in <xref linkend="sec-overlays-layout"/>.</para> -<para>To install an overlay, using the last option. Clone the repository of -the overlay, and add a symbolic link to it in the -<filename>~/.nixpkgs/overlays/</filename> directory.</para> +<para>The order of the overlay layers can influence the recipe of packages if multiple layers override +the same recipe. In the case where overlays are loaded from a directory, these are loaded in +alphabetical order.</para> + +<para>To install an overlay using the last option, you can clone the overlay's repository and add +a symbolic link to in the <filename>~/.nixpkgs/overlays/</filename> directory.</para> </section> @@ -62,37 +59,40 @@ the overlay, and add a symbolic link to it in the <section xml:id="sec-overlays-layout"> <title>Overlays Layout</title> -<para>An overlay is a Nix expression, which is a function which accepts 2 -arguments.</para> +<para>Overlays are expressed as Nix functions which accept 2 arguments and return a set of +packages</para> <programlisting> self: super: { - foo = super.foo.override { ... }; - bar = import ./pkgs/bar { - inherit (self) stdenv fetchurl; - inherit (self) ninja crawl dwarf-fortress; + boost = super.boost.override { + python = self.python3; + }; + rr = super.callPackage ./pkgs/rr { + stdenv = self.stdenv_32bit; }; } </programlisting> -<para>The first argument, usualy named <varname>self</varname>, corresponds -to the final package set. You should use this set to inherit all the -dependencies needed by your package expression.</para> +<para>The first argument, usually named <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 overriden dependencies used in the +<varname>boost</varname> override.</para> -<para>The second argument, usualy named <varname>super</varname>, +<para>The second argument, usually named <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 is used in to override -existing packages, either by changing their dependencies or their -recipes.</para> +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>, which contains either -extra packages defined by the overlay, or which overwrite Nixpkgs packages -with other custom defaults. This is similar to <xref -linkend="sec-modify-via-packageOverrides"/>.</para> +<filename>pkgs/top-level/all-packages.nix</filename>, which contains +overridden and/or new packages.</para> </section> |