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