mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-23 23:43:30 +00:00
Merge pull request #128878 from bobby285271/pr2
nixos/doc: convert "6.1. Declarative Package Management" to CommonMark
This commit is contained in:
Jörg Thalheim
GitHub
commit
b9ed8cbaff
@ -0,0 +1,74 @@
|
||||
# Adding Custom Packages {#sec-custom-packages}
|
||||
|
||||
It's possible that a package you need is not available in NixOS. In that
|
||||
case, you can do two things. First, you can clone the Nixpkgs
|
||||
repository, add the package to your clone, and (optionally) submit a
|
||||
patch or pull request to have it accepted into the main Nixpkgs repository.
|
||||
This is described in detail in the [Nixpkgs manual](https://nixos.org/nixpkgs/manual).
|
||||
In short, you clone Nixpkgs:
|
||||
|
||||
```ShellSession
|
||||
$ git clone https://github.com/NixOS/nixpkgs
|
||||
$ cd nixpkgs
|
||||
```
|
||||
|
||||
Then you write and test the package as described in the Nixpkgs manual.
|
||||
Finally, you add it to [](#opt-environment.systemPackages), e.g.
|
||||
|
||||
```nix
|
||||
environment.systemPackages = [ pkgs.my-package ];
|
||||
```
|
||||
|
||||
and you run `nixos-rebuild`, specifying your own Nixpkgs tree:
|
||||
|
||||
```ShellSession
|
||||
# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
|
||||
```
|
||||
|
||||
The second possibility is to add the package outside of the Nixpkgs
|
||||
tree. For instance, here is how you specify a build of the
|
||||
[GNU Hello](https://www.gnu.org/software/hello/) package directly in
|
||||
`configuration.nix`:
|
||||
|
||||
```nix
|
||||
environment.systemPackages =
|
||||
let
|
||||
my-hello = with pkgs; stdenv.mkDerivation rec {
|
||||
name = "hello-2.8";
|
||||
src = fetchurl {
|
||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||
};
|
||||
};
|
||||
in
|
||||
[ my-hello ];
|
||||
```
|
||||
|
||||
Of course, you can also move the definition of `my-hello` into a
|
||||
separate Nix expression, e.g.
|
||||
|
||||
```nix
|
||||
environment.systemPackages = [ (import ./my-hello.nix) ];
|
||||
```
|
||||
|
||||
where `my-hello.nix` contains:
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {}; # bring all of Nixpkgs into scope
|
||||
|
||||
stdenv.mkDerivation rec {
|
||||
name = "hello-2.8";
|
||||
src = fetchurl {
|
||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
This allows testing the package easily:
|
||||
|
||||
```ShellSession
|
||||
$ nix-build my-hello.nix
|
||||
$ ./result/bin/hello
|
||||
Hello, world!
|
||||
```
|
||||
@ -1,73 +0,0 @@
|
||||
<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-custom-packages">
|
||||
<title>Adding Custom Packages</title>
|
||||
|
||||
<para>
|
||||
It’s possible that a package you need is not available in NixOS. In that
|
||||
case, you can do two things. First, you can clone the Nixpkgs repository, add
|
||||
the package to your clone, and (optionally) submit a patch or pull request to
|
||||
have it accepted into the main Nixpkgs repository. This is described in
|
||||
detail in the <link
|
||||
xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs
|
||||
manual</link>. In short, you clone Nixpkgs:
|
||||
<screen>
|
||||
<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
|
||||
<prompt>$ </prompt>cd nixpkgs
|
||||
</screen>
|
||||
Then you write and test the package as described in the Nixpkgs manual.
|
||||
Finally, you add it to <literal>environment.systemPackages</literal>, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ];
|
||||
</programlisting>
|
||||
and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs
|
||||
tree:
|
||||
<screen>
|
||||
<prompt># </prompt>nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The second possibility is to add the package outside of the Nixpkgs tree. For
|
||||
instance, here is how you specify a build of the
|
||||
<link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link>
|
||||
package directly in <filename>configuration.nix</filename>:
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> =
|
||||
let
|
||||
my-hello = with pkgs; stdenv.mkDerivation rec {
|
||||
name = "hello-2.8";
|
||||
src = fetchurl {
|
||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||
};
|
||||
};
|
||||
in
|
||||
[ my-hello ];
|
||||
</programlisting>
|
||||
Of course, you can also move the definition of <literal>my-hello</literal>
|
||||
into a separate Nix expression, e.g.
|
||||
<programlisting>
|
||||
<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ];
|
||||
</programlisting>
|
||||
where <filename>my-hello.nix</filename> contains:
|
||||
<programlisting>
|
||||
with import <nixpkgs> {}; # bring all of Nixpkgs into scope
|
||||
|
||||
stdenv.mkDerivation rec {
|
||||
name = "hello-2.8";
|
||||
src = fetchurl {
|
||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||
};
|
||||
}
|
||||
</programlisting>
|
||||
This allows testing the package easily:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-build my-hello.nix
|
||||
<prompt>$ </prompt>./result/bin/hello
|
||||
Hello, world!
|
||||
</screen>
|
||||
</para>
|
||||
</section>
|
||||
@ -0,0 +1,74 @@
|
||||
# Customising Packages {#sec-customising-packages}
|
||||
|
||||
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 `configuration.nix` as follows:
|
||||
`nixpkgs.config.firefox.enableGoogleTalkPlugin = true;`
|
||||
|
||||
::: {.warning}
|
||||
Unfortunately, Nixpkgs currently lacks a way to query available
|
||||
configuration options.
|
||||
:::
|
||||
|
||||
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:
|
||||
|
||||
```nix
|
||||
environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
|
||||
```
|
||||
|
||||
The function `override` 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 `gtk` gets the
|
||||
value `pkgs.gtk3`, 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,
|
||||
[](#opt-environment.systemPackages)
|
||||
would be a list with two elements.)
|
||||
|
||||
Even greater customisation is possible using the function
|
||||
`overrideAttrs`. While the `override` mechanism above overrides the
|
||||
arguments of a package function, `overrideAttrs` allows changing the
|
||||
*attributes* passed to `mkDerivation`. 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:
|
||||
|
||||
```nix
|
||||
environment.systemPackages = [
|
||||
(pkgs.emacs.overrideAttrs (oldAttrs: {
|
||||
name = "emacs-25.0-pre";
|
||||
src = /path/to/my/emacs/tree;
|
||||
}))
|
||||
];
|
||||
```
|
||||
|
||||
Here, `overrideAttrs` takes the Nix derivation specified by `pkgs.emacs`
|
||||
and produces a new derivation in which the original's `name` and `src`
|
||||
attribute have been replaced by the given values by re-calling
|
||||
`stdenv.mkDerivation`. The original attributes are accessible via the
|
||||
function argument, which is conventionally named `oldAttrs`.
|
||||
|
||||
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 *global* override as follows:
|
||||
|
||||
```nix
|
||||
nixpkgs.config.packageOverrides = pkgs:
|
||||
{ emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
|
||||
};
|
||||
```
|
||||
|
||||
The effect of this definition is essentially equivalent to modifying the
|
||||
`emacs` attribute in the Nixpkgs source tree. Any package in Nixpkgs
|
||||
that depends on `emacs` will be passed your customised instance.
|
||||
(However, the value `pkgs.emacs` in `nixpkgs.config.packageOverrides`
|
||||
refers to the original rather than overridden instance, to prevent an
|
||||
infinite recursion.)
|
||||
@ -1,86 +0,0 @@
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<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: {
|
||||
name = "emacs-25.0-pre";
|
||||
src = /path/to/my/emacs/tree;
|
||||
}))
|
||||
];
|
||||
</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>
|
||||
|
||||
<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>
|
||||
@ -48,7 +48,7 @@ nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
|
||||
<command>nixos-rebuild switch</command>.
|
||||
</para>
|
||||
|
||||
<xi:include href="customizing-packages.xml" />
|
||||
<xi:include href="../from_md/configuration/customizing-packages.section.xml" />
|
||||
|
||||
<xi:include href="adding-custom-packages.xml" />
|
||||
<xi:include href="../from_md/configuration/adding-custom-packages.section.xml" />
|
||||
</section>
|
||||
|
||||
@ -0,0 +1,80 @@
|
||||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-custom-packages">
|
||||
<title>Adding Custom Packages</title>
|
||||
<para>
|
||||
It’s possible that a package you need is not available in NixOS. In
|
||||
that case, you can do two things. First, you can clone the Nixpkgs
|
||||
repository, add the package to your clone, and (optionally) submit a
|
||||
patch or pull request to have it accepted into the main Nixpkgs
|
||||
repository. This is described in detail in the
|
||||
<link xlink:href="https://nixos.org/nixpkgs/manual">Nixpkgs
|
||||
manual</link>. In short, you clone Nixpkgs:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ git clone https://github.com/NixOS/nixpkgs
|
||||
$ cd nixpkgs
|
||||
</programlisting>
|
||||
<para>
|
||||
Then you write and test the package as described in the Nixpkgs
|
||||
manual. Finally, you add it to
|
||||
<xref linkend="opt-environment.systemPackages" />, e.g.
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
environment.systemPackages = [ pkgs.my-package ];
|
||||
</programlisting>
|
||||
<para>
|
||||
and you run <literal>nixos-rebuild</literal>, specifying your own
|
||||
Nixpkgs tree:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs
|
||||
</programlisting>
|
||||
<para>
|
||||
The second possibility is to add the package outside of the Nixpkgs
|
||||
tree. For instance, here is how you specify a build of the
|
||||
<link xlink:href="https://www.gnu.org/software/hello/">GNU
|
||||
Hello</link> package directly in
|
||||
<literal>configuration.nix</literal>:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
environment.systemPackages =
|
||||
let
|
||||
my-hello = with pkgs; stdenv.mkDerivation rec {
|
||||
name = "hello-2.8";
|
||||
src = fetchurl {
|
||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||
};
|
||||
};
|
||||
in
|
||||
[ my-hello ];
|
||||
</programlisting>
|
||||
<para>
|
||||
Of course, you can also move the definition of
|
||||
<literal>my-hello</literal> into a separate Nix expression, e.g.
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
environment.systemPackages = [ (import ./my-hello.nix) ];
|
||||
</programlisting>
|
||||
<para>
|
||||
where <literal>my-hello.nix</literal> contains:
|
||||
</para>
|
||||
<programlisting language="bash">
|
||||
with import <nixpkgs> {}; # bring all of Nixpkgs into scope
|
||||
|
||||
stdenv.mkDerivation rec {
|
||||
name = "hello-2.8";
|
||||
src = fetchurl {
|
||||
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||
};
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
This allows testing the package easily:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ nix-build my-hello.nix
|
||||
$ ./result/bin/hello
|
||||
Hello, world!
|
||||
</programlisting>
|
||||
</section>
|
||||
@ -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>
|
||||
Loading…
Reference in New Issue
Block a user