diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/functions.xml | 64 | ||||
| -rw-r--r-- | doc/languages-frameworks/python.md | 6 | ||||
| -rw-r--r-- | doc/manual.xml | 1 | ||||
| -rw-r--r-- | doc/overlays.xml | 99 |
4 files changed, 105 insertions, 65 deletions
diff --git a/doc/functions.xml b/doc/functions.xml index f6a0a4352f63c..6374c15ddf2b5 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -17,66 +17,6 @@ derivations or even the whole package set. </para> - <section xml:id="sec-pkgs-overridePackages"> - <title>pkgs.overridePackages</title> - - <para> - This function inside the nixpkgs expression (<varname>pkgs</varname>) - can be used to override the set of packages itself. - </para> - <para> - Warning: this function is expensive and must not be used from within - the nixpkgs repository. - </para> - <para> - Example usage: - - <programlisting>let - pkgs = import <nixpkgs> {}; - newpkgs = pkgs.overridePackages (self: super: { - foo = super.foo.override { ... }; - }); - in ...</programlisting> - </para> - - <para> - The resulting <varname>newpkgs</varname> will have the new <varname>foo</varname> - expression, and all other expressions depending on <varname>foo</varname> will also - use the new <varname>foo</varname> expression. - </para> - - <para> - The behavior of this function is similar to <link - linkend="sec-modify-via-packageOverrides">config.packageOverrides</link>. - </para> - - <para> - The <varname>self</varname> parameter refers to the final package set with the - applied overrides. Using this parameter may lead to infinite recursion if not - used consciously. - </para> - - <para> - The <varname>super</varname> parameter refers to the old package set. - It's equivalent to <varname>pkgs</varname> in the above example. - </para> - - <para> - Note that in previous versions of nixpkgs, this method replaced any changes from <link - linkend="sec-modify-via-packageOverrides">config.packageOverrides</link>, - along with that from previous calls if this function was called repeatedly. - Now those previous changes will be preserved so this function can be "chained" meaningfully. - To recover the old behavior, make sure <varname>config.packageOverrides</varname> is unset, - and call this only once off a "freshly" imported nixpkgs: - - <programlisting>let - pkgs = import <nixpkgs> { config: {}; }; - newpkgs = pkgs.overridePackages ...; - in ...</programlisting> - </para> - - </section> - <section xml:id="sec-pkg-override"> <title><pkg>.override</title> @@ -91,9 +31,9 @@ Example usages: <programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting> - <programlisting>pkgs.overridePackages (self: super: { + <programlisting>import pkgs.path { overlays = [ (self: super: { foo = super.foo.override { barSupport = true ; }; - })</programlisting> + })]};</programlisting> <programlisting>mypkg = pkgs.callPackage ./mypkg.nix { mydep = pkgs.mydep.override { ... }; }</programlisting> diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.md index 82aeb112c93ed..48d9e0a0952f9 100644 --- a/doc/languages-frameworks/python.md +++ b/doc/languages-frameworks/python.md @@ -737,18 +737,18 @@ in (pkgs.python35.override {inherit packageOverrides;}).withPackages (ps: [ps.bl ``` The requested package `blaze` depends on `pandas` which itself depends on `scipy`. -If you want the whole of Nixpkgs to use your modifications, then you can use `pkgs.overridePackages` +If you want the whole of Nixpkgs to use your modifications, then you can use `overlays` as explained in this manual. In the following example we build a `inkscape` using a different version of `numpy`. ``` let pkgs = import <nixpkgs> {}; - newpkgs = pkgs.overridePackages ( pkgsself: pkgssuper: { + newpkgs = import pkgs.path { overlays = [ (pkgsself: pkgssuper: { python27 = let packageOverrides = self: super: { numpy = super.numpy_1_10; }; in pkgssuper.python27.override {inherit packageOverrides;}; - } ); + } ) ]; }; in newpkgs.inkscape ``` diff --git a/doc/manual.xml b/doc/manual.xml index 6ad66d486525d..1c0dac6e4df77 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -18,6 +18,7 @@ <xi:include href="meta.xml" /> <xi:include href="languages-frameworks/index.xml" /> <xi:include href="package-notes.xml" /> + <xi:include href="overlays.xml" /> <xi:include href="coding-conventions.xml" /> <xi:include href="submitting-changes.xml" /> <xi:include href="reviewing-contributions.xml" /> diff --git a/doc/overlays.xml b/doc/overlays.xml new file mode 100644 index 0000000000000..d194c6bfc8920 --- /dev/null +++ b/doc/overlays.xml @@ -0,0 +1,99 @@ +<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 content using +overlays. Overlays are used to add phases in the fix-point used by Nixpkgs +to bind the dependencies of all packages.</para> + +<!--============================================================--> + +<section xml:id="sec-overlays-install"> +<title>Installing Overlays</title> + +<para>Overlays are looked for in the following order, the first valid one is +considered, and all the rest are ignored: + +<orderedlist> + + <listitem> + + <para>As 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> + + </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. + + </listitem> + + <listitem> + + <para>As the directory located at +<filename>~/.nixpkgs/overlays/</filename>. This directory can contain +symbolic links to Nix expressions. + + </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>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> + +</section> + +<!--============================================================--> + +<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> + +<programlisting> +self: super: + +{ + foo = super.foo.override { ... }; + bar = import ./pkgs/bar { + inherit (self) stdenv fetchurl; + inherit (self) ninja crawl dwarf-fortress; + }; +} +</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 second argument, usualy 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> + +<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> + +</section> + +</chapter> |