nixos docs: format =)
This commit is contained in:
Graham Christensen
@@ -3,53 +3,50 @@
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-customising-packages">
|
||||
<title>Customising Packages</title>
|
||||
|
||||
<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>
|
||||
|
||||
<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:
|
||||
<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>
|
||||
<xref linkend="opt-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, <xref linkend="opt-environment.systemPackages"/> would be a list with
|
||||
two elements.)
|
||||
</para>
|
||||
|
||||
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,
|
||||
<xref linkend="opt-environment.systemPackages"/> would be a list with two
|
||||
elements.)</para>
|
||||
|
||||
<para>Even greater customisation is possible using the function
|
||||
<varname>overrideAttrs</varname>. While the
|
||||
<varname>override</varname> mechanism above overrides the arguments of
|
||||
a package function, <varname>overrideAttrs</varname> 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>
|
||||
Even greater customisation is possible using the function
|
||||
<varname>overrideAttrs</varname>. While the <varname>override</varname>
|
||||
mechanism above overrides the arguments of a package function,
|
||||
<varname>overrideAttrs</varname> 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:
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> = [
|
||||
(pkgs.emacs.overrideAttrs (oldAttrs: {
|
||||
@@ -58,36 +55,32 @@ can say:
|
||||
}))
|
||||
];
|
||||
</programlisting>
|
||||
Here, <varname>overrideAttrs</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 by re-calling
|
||||
<literal>stdenv.mkDerivation</literal>. The original attributes are
|
||||
accessible via the function argument, which is conventionally named
|
||||
<varname>oldAttrs</varname>.
|
||||
</para>
|
||||
|
||||
Here, <varname>overrideAttrs</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 by re-calling <literal>stdenv.mkDerivation</literal>.
|
||||
The original attributes are accessible via the function argument,
|
||||
which is conventionally named <varname>oldAttrs</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:
|
||||
|
||||
<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>
|
||||
|
||||
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>
|
||||
|
||||
Reference in New Issue
Block a user