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