public
/
nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve overrideDerivation docs. (#16867) 

* Improve overrideDerivation docs.

Explain how antiquotation in a package's attribute behaves when overriding the package.

* Edit antiquotation note. Fix closing-element.
This commit is contained in:
Alex Berg 2016-07-12 00:57:26 -07:00 committed by Domen Kožar
parent 71ad2ed226
commit b5a95b1812
1 changed files with 33 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
doc/functions.xml
View File

@ -89,26 +89,26 @@ in ...</programlisting>
<title>&lt;pkg&gt;.overrideDerivation</title> <title>&lt;pkg&gt;.overrideDerivation</title>
<warning> <warning>
<para>Do not use this function in Nixpkgs. Because it breaks <para>Do not use this function in Nixpkgs as it evaluates a Derivation
package abstraction and doesn’t provide error checking for before modifying it, which breaks package abstraction and removes
function arguments, it is only intended for ad-hoc customisation error-checking of function arguments. In addition, this
(such as in <filename>~/.nixpkgs/config.nix</filename>). evaluation-per-function application incurs a performance penalty,
</para> which can become a problem if many overrides are used.
It is only intended for ad-hoc customisation, such as in
<para> <filename>~/.nixpkgs/config.nix</filename>.
Additionally, <varname>overrideDerivation</varname> forces an evaluation
of the Derivation which can be quite a performance penalty if there are many
overrides used.
</para> </para>
</warning> </warning>
<para> <para>
The function <varname>overrideDerivation</varname> is usually available for all the The function <varname>overrideDerivation</varname> creates a new derivation
derivations in the nixpkgs expression (<varname>pkgs</varname>). based on an existing one by overriding the original's attributes with
</para> the attribute set produced by the specified function.
<para> This function is available on all
It is used to create a new derivation by overriding the attributes of derivations defined using the <varname>makeOverridable</varname> function.
the original derivation according to the given function. Most standard derivation-producing functions, such as
<varname>stdenv.mkDerivation</varname>, are defined using this
function, which means most packages in the nixpkgs expression,
<varname>pkgs</varname>, have this function.
</para> </para>
<para> <para>
@ -125,9 +125,9 @@ in ...</programlisting>
</para> </para>
<para> <para>
In the above example, the name, src and patches of the derivation In the above example, the <varname>name</varname>, <varname>src</varname>,
will be overridden, while all other attributes will be retained from the and <varname>patches</varname> of the derivation will be overridden, while
original derivation. all other attributes will be retained from the original derivation.
</para> </para>
<para> <para>
@ -135,6 +135,20 @@ in ...</programlisting>
the original derivation. the original derivation.
</para> </para>
<note>
<para>
A package's attributes are evaluated *before* being modified by
the <varname>overrideDerivation</varname> function.
For example, the <varname>name</varname> attribute reference
in <varname>url = "mirror://gnu/hello/${name}.tar.gz";</varname>
is filled-in *before* the <varname>overrideDerivation</varname> function
modifies the attribute set. This means that overriding the
<varname>name</varname> attribute, in this example, *will not* change the
value of the <varname>url</varname> attribute. Instead, we need to override
both the <varname>name</varname> *and* <varname>url</varname> attributes.
</para>
</note>
</section> </section>
<section xml:id="sec-lib-makeOverridable"> <section xml:id="sec-lib-makeOverridable">