pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-customising-packages">
2 <title>Customising Packages</title>
3 <para>
4 Some packages in Nixpkgs have options to enable or disable optional
5 functionality or change other aspects of the package. For instance,
6 the Firefox wrapper package (which provides Firefox with a set of
7 plugins such as the Adobe Flash player) has an option to enable the
8 Google Talk plugin. It can be set in
9 <literal>configuration.nix</literal> as follows:
10 <literal>nixpkgs.config.firefox.enableGoogleTalkPlugin = true;</literal>
11 </para>
12 <warning>
13 <para>
14 Unfortunately, Nixpkgs currently lacks a way to query available
15 configuration options.
16 </para>
17 </warning>
18 <para>
19 Apart from high-level options, it’s possible to tweak a package in
20 almost arbitrary ways, such as changing or disabling dependencies of
21 a package. For instance, the Emacs package in Nixpkgs by default has
22 a dependency on GTK 2. If you want to build it against GTK 3, you
23 can specify that as follows:
24 </para>
25 <programlisting language="bash">
26environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
27</programlisting>
28 <para>
29 The function <literal>override</literal> performs the call to the
30 Nix function that produces Emacs, with the original arguments
31 amended by the set of arguments specified by you. So here the
32 function argument <literal>gtk</literal> gets the value
33 <literal>pkgs.gtk3</literal>, causing Emacs to depend on GTK 3. (The
34 parentheses are necessary because in Nix, function application binds
35 more weakly than list construction, so without them,
36 <xref linkend="opt-environment.systemPackages" /> would be a list
37 with two elements.)
38 </para>
39 <para>
40 Even greater customisation is possible using the function
41 <literal>overrideAttrs</literal>. While the
42 <literal>override</literal> mechanism above overrides the arguments
43 of a package function, <literal>overrideAttrs</literal> allows
44 changing the <emphasis>attributes</emphasis> passed to
45 <literal>mkDerivation</literal>. This permits changing any aspect of
46 the package, such as the source code. For instance, if you want to
47 override the source code of Emacs, you can say:
48 </para>
49 <programlisting language="bash">
50environment.systemPackages = [
51 (pkgs.emacs.overrideAttrs (oldAttrs: {
52 name = "emacs-25.0-pre";
53 src = /path/to/my/emacs/tree;
54 }))
55];
56</programlisting>
57 <para>
58 Here, <literal>overrideAttrs</literal> takes the Nix derivation
59 specified by <literal>pkgs.emacs</literal> and produces a new
60 derivation in which the original’s <literal>name</literal> and
61 <literal>src</literal> attribute have been replaced by the given
62 values by re-calling <literal>stdenv.mkDerivation</literal>. The
63 original attributes are accessible via the function argument, which
64 is conventionally named <literal>oldAttrs</literal>.
65 </para>
66 <para>
67 The overrides shown above are not global. They do not affect the
68 original package; other packages in Nixpkgs continue to depend on
69 the original rather than the customised package. This means that if
70 another package in your system depends on the original package, you
71 end up with two instances of the package. If you want to have
72 everything depend on your customised instance, you can apply a
73 <emphasis>global</emphasis> override as follows:
74 </para>
75 <programlisting language="bash">
76nixpkgs.config.packageOverrides = pkgs:
77 { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
78 };
79</programlisting>
80 <para>
81 The effect of this definition is essentially equivalent to modifying
82 the <literal>emacs</literal> attribute in the Nixpkgs source tree.
83 Any package in Nixpkgs that depends on <literal>emacs</literal> will
84 be passed your customised instance. (However, the value
85 <literal>pkgs.emacs</literal> in
86 <literal>nixpkgs.config.packageOverrides</literal> refers to the
87 original rather than overridden instance, to prevent an infinite
88 recursion.)
89 </para>
90</section>