diff options
Diffstat (limited to 'nixos/doc/manual/configuration/customizing-packages.xml')
| -rw-r--r-- | nixos/doc/manual/configuration/customizing-packages.xml | 92 |
1 files changed, 92 insertions, 0 deletions
diff --git a/nixos/doc/manual/configuration/customizing-packages.xml b/nixos/doc/manual/configuration/customizing-packages.xml new file mode 100644 index 000000000000..6ee7a95dc6fa --- /dev/null +++ b/nixos/doc/manual/configuration/customizing-packages.xml @@ -0,0 +1,92 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + 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 +<filename>configuration.nix</filename> as follows: + +<filename> +nixpkgs.config.firefox.enableGoogleTalkPlugin = true; +</filename> +</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: + +<programlisting> +environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; +</programlisting> + +The function <varname>override</varname> 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 +<varname>gtk</varname> 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, +<literal>environment.systemPackages</literal> would be a list with two +elements.)</para> + +<para>Even greater customisation is possible using the function +<varname>overrideDerivation</varname>. While the +<varname>override</varname> mechanism above overrides the arguments of +a package function, <varname>overrideDerivation</varname> allows +changing the <emphasis>result</emphasis> of the function. 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: + +<programlisting> +environment.systemPackages = + [ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: { + name = "emacs-25.0-pre"; + src = /path/to/my/emacs/tree; + })) + ]; +</programlisting> + +Here, <varname>overrideDerivation</varname> takes the Nix derivation +specified by <varname>pkgs.emacs</varname> 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. The original attributes are accessible via +<varname>attrs</varname>.</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: + +<screen> +nixpkgs.config.packageOverrides = pkgs: + { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; }; + }; +</screen> + +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 +<varname>nixpkgs.config.packageOverrides</varname> refers to the +original rather than overridden instance, to prevent an infinite +recursion.)</para> + +</section> |