diff options
Diffstat (limited to 'nixos/doc/manual/from_md/configuration/customizing-packages.section.xml')
| -rw-r--r-- | nixos/doc/manual/from_md/configuration/customizing-packages.section.xml | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml new file mode 100644 index 00000000000..f78b5dc5460 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml @@ -0,0 +1,90 @@ +<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 = "emacs-25.0-pre"; + 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> |