JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #128878 from bobby285271/pr2

Browse Source 
nixos/doc: convert "6.1. Declarative Package Management" to CommonMark
This commit is contained in:
Jörg Thalheim 2021-09-07 03:55:22 +01:00 committed by GitHub
commit b9ed8cbaff
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 320 additions and 161 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
nixos/doc/manual/configuration/adding-custom-packages.section.md Normal file
View File

@ -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!
```

73
nixos/doc/manual/configuration/adding-custom-packages.xml
View File

@ -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 &lt;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>

74
nixos/doc/manual/configuration/customizing-packages.section.md Normal file
View File

@ -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.)

86
nixos/doc/manual/configuration/customizing-packages.xml
View File

@ -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>

4
nixos/doc/manual/configuration/declarative-packages.xml
View File

@ -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>

80
nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml Normal file
View File

@ -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 = &quot;hello-2.8&quot;;
src = fetchurl {
url = &quot;mirror://gnu/hello/${name}.tar.gz&quot;;
sha256 = &quot;0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6&quot;;
};
};
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 &lt;nixpkgs&gt; {}; # bring all of Nixpkgs into scope
stdenv.mkDerivation rec {
name = &quot;hello-2.8&quot;;
src = fetchurl {
url = &quot;mirror://gnu/hello/${name}.tar.gz&quot;;
sha256 = &quot;0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6&quot;;
};
}
</programlisting>
<para>
This allows testing the package easily:
</para>
<programlisting>
$ nix-build my-hello.nix
$ ./result/bin/hello
Hello, world!
</programlisting>
</section>

90
nixos/doc/manual/from_md/configuration/customizing-packages.section.xml Normal file
View File

@ -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 = &quot;emacs-25.0-pre&quot;;
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>