nixpkgs/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml

<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-customising-packages">
  <title>Customising Packages</title>
  <para>
    Some packages in Nixpkgs have options to enable or disable optional
    functionality or change other aspects of the package. For instance,
    the Firefox wrapper package (which provides Firefox with a set of
    plugins such as the Adobe Flash player) has an option to enable the
    Google Talk plugin. It can be set in
    <literal>configuration.nix</literal> as follows:
    <literal>nixpkgs.config.firefox.enableGoogleTalkPlugin = true;</literal>
  </para>
  <warning>
    <para>
      Unfortunately, Nixpkgs currently lacks a way to query available
      configuration options.
    </para>
  </warning>
  <para>
    Apart from high-level options, it’s possible to tweak a package in
    almost arbitrary ways, such as changing or disabling dependencies of
    a package. For instance, the Emacs package in Nixpkgs by default has
    a dependency on GTK 2. If you want to build it against GTK 3, you
    can specify that as follows:
  </para>
  <programlisting language="bash">
environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
</programlisting>
  <para>
    The function <literal>override</literal> performs the call to the
    Nix function that produces Emacs, with the original arguments
    amended by the set of arguments specified by you. So here the
    function argument <literal>gtk</literal> gets the value
    <literal>pkgs.gtk3</literal>, causing Emacs to depend on GTK 3. (The
    parentheses are necessary because in Nix, function application binds
    more weakly than list construction, so without them,
    <xref linkend="opt-environment.systemPackages" /> would be a list
    with two elements.)
  </para>
  <para>
    Even greater customisation is possible using the function
    <literal>overrideAttrs</literal>. While the
    <literal>override</literal> mechanism above overrides the arguments
    of a package function, <literal>overrideAttrs</literal> allows
    changing the <emphasis>attributes</emphasis> passed to
    <literal>mkDerivation</literal>. This permits changing any aspect of
    the package, such as the source code. For instance, if you want to
    override the source code of Emacs, you can say:
  </para>
  <programlisting language="bash">
environment.systemPackages = [
  (pkgs.emacs.overrideAttrs (oldAttrs: {
    name = &quot;emacs-25.0-pre&quot;;
    src = /path/to/my/emacs/tree;
  }))
];
</programlisting>
  <para>
    Here, <literal>overrideAttrs</literal> takes the Nix derivation
    specified by <literal>pkgs.emacs</literal> and produces a new
    derivation in which the original’s <literal>name</literal> and
    <literal>src</literal> attribute have been replaced by the given
    values by re-calling <literal>stdenv.mkDerivation</literal>. The
    original attributes are accessible via the function argument, which
    is conventionally named <literal>oldAttrs</literal>.
  </para>
  <para>
    The overrides shown above are not global. They do not affect the
    original package; other packages in Nixpkgs continue to depend on
    the original rather than the customised package. This means that if
    another package in your system depends on the original package, you
    end up with two instances of the package. If you want to have
    everything depend on your customised instance, you can apply a
    <emphasis>global</emphasis> override as follows:
  </para>
  <programlisting language="bash">
nixpkgs.config.packageOverrides = pkgs:
  { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
  };
</programlisting>
  <para>
    The effect of this definition is essentially equivalent to modifying
    the <literal>emacs</literal> attribute in the Nixpkgs source tree.
    Any package in Nixpkgs that depends on <literal>emacs</literal> will
    be passed your customised instance. (However, the value
    <literal>pkgs.emacs</literal> in
    <literal>nixpkgs.config.packageOverrides</literal> refers to the
    original rather than overridden instance, to prevent an infinite
    recursion.)
  </para>
</section>