path: root/doc/functions.xml

<chapter xmlns="http://docbook.org/ns/docbook"
	 xmlns:xlink="http://www.w3.org/1999/xlink"
	 xml:id="chap-functions">

<title>Functions reference</title>

<para>
  The nixpkgs repository has several utility functions to manipulate Nix expressions.
</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 &lt;nixpkgs&gt; {};
  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>

</section>

<section xml:id="sec-pkg-override">
  <title>&lt;pkg&gt;.override</title>

  <para>
    The function <varname>override</varname> is usually available for all the
    derivations in the nixpkgs expression (<varname>pkgs</varname>).
  </para>
  <para>
    It is used to override the arguments passed to a function.
  </para>
  <para>
    Example usages:

    <programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting>
    <programlisting>pkgs.overridePackages (self: super: {
  foo = super.foo.override { barSupport = true ; };
})</programlisting>
    <programlisting>mypkg = pkgs.callPackage ./mypkg.nix {
  mydep = pkgs.mydep.override { ... };
})</programlisting>
  </para>

  <para>
    In the first example, <varname>pkgs.foo</varname> is the result of a function call
    with some default arguments, usually a derivation.
    Using <varname>pkgs.foo.override</varname> will call the same function with
    the given new arguments.
  </para>

</section>

<section xml:id="sec-pkg-overrideDerivation">
  <title>&lt;pkg&gt;.overrideDerivation</title>

  <para>
    The function <varname>overrideDerivation</varname> is usually available for all the
    derivations in the nixpkgs expression (<varname>pkgs</varname>).
  </para> 
  <para>
    It is used to create a new derivation by overriding the attributes of
    the original derivation according to the given function.
  </para>

  <para>
    Example usage:

    <programlisting>mySed = pkgs.gnused.overrideDerivation (oldAttrs: {
  name = "sed-4.2.2-pre";
  src = fetchurl {
    url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;
    sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k";
  };
  patches = [];
});</programlisting>
  </para>

  <para>
    In the above example, the name, src and patches of the derivation
    will be overridden, while all other attributes will be retained from the
    original derivation.
  </para>

  <para>
    The argument <varname>oldAttrs</varname> is used to refer to the attribute set of
    the original derivation.
  </para>

</section>

<section xml:id="sec-lib-makeOverridable">
  <title>lib.makeOverridable</title>

  <para>
    The function <varname>lib.makeOverridable</varname> is used make the result
    of a function easily customizable. This utility only makes sense for functions
    that accept an argument set and return an attribute set.
  </para>

  <para>
    Example usage:

    <programlisting>f = { a, b }: { result = a+b; }
c = lib.makeOverridable f { a = 1; b = 2; }</programlisting>

  </para>

  <para>
    The variable <varname>c</varname> is the value of the <varname>f</varname> function
    applied with some default arguments. Hence the value of <varname>c.result</varname>
    is <literal>3</literal>, in this example.
  </para>

  <para>
    The variable <varname>c</varname> however also has some additional functions, like
    <link linkend="sec-pkg-override">c.override</link> which can be used to
    override the default arguments. In this example the value of
    <varname>(c.override { a = 4; }).result</varname> is 6.
  </para>

</section>

</chapter>