nixpkgs docs: format =)
This commit is contained in:
Graham Christensen
+283
-276
@@ -1,42 +1,51 @@
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xml:id="chap-packageconfig">
|
||||
|
||||
<title>Global configuration</title>
|
||||
|
||||
<para>Nix comes with certain defaults about what packages can and
|
||||
cannot be installed, based on a package's metadata. By default, Nix
|
||||
will prevent installation if any of the following criteria are
|
||||
true:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>The package is thought to be broken, and has had
|
||||
its <literal>meta.broken</literal> set to
|
||||
<literal>true</literal>.</para></listitem>
|
||||
|
||||
<listitem><para>The package isn't intended to run on the given system, as none of its <literal>meta.platforms</literal> match the given system.</para></listitem>
|
||||
|
||||
<listitem><para>The package's <literal>meta.license</literal> is set
|
||||
to a license which is considered to be unfree.</para></listitem>
|
||||
|
||||
<listitem><para>The package has known security vulnerabilities but
|
||||
has not or can not be updated for some reason, and a list of issues
|
||||
has been entered in to the package's
|
||||
<literal>meta.knownVulnerabilities</literal>.</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>Note that all this is checked during evaluation already,
|
||||
and the check includes any package that is evaluated.
|
||||
In particular, all build-time dependencies are checked.
|
||||
<literal>nix-env -qa</literal> will (attempt to) hide any packages
|
||||
that would be refused.
|
||||
</para>
|
||||
|
||||
<para>Each of these criteria can be altered in the nixpkgs
|
||||
configuration.</para>
|
||||
|
||||
<para>The nixpkgs configuration for a NixOS system is set in the
|
||||
<literal>configuration.nix</literal>, as in the following example:
|
||||
<title>Global configuration</title>
|
||||
<para>
|
||||
Nix comes with certain defaults about what packages can and cannot be
|
||||
installed, based on a package's metadata. By default, Nix will prevent
|
||||
installation if any of the following criteria are true:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
The package is thought to be broken, and has had its
|
||||
<literal>meta.broken</literal> set to <literal>true</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
The package isn't intended to run on the given system, as none of its
|
||||
<literal>meta.platforms</literal> match the given system.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
The package's <literal>meta.license</literal> is set to a license which is
|
||||
considered to be unfree.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
The package has known security vulnerabilities but has not or can not be
|
||||
updated for some reason, and a list of issues has been entered in to the
|
||||
package's <literal>meta.knownVulnerabilities</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Note that all this is checked during evaluation already, and the check
|
||||
includes any package that is evaluated. In particular, all build-time
|
||||
dependencies are checked. <literal>nix-env -qa</literal> will (attempt to)
|
||||
hide any packages that would be refused.
|
||||
</para>
|
||||
<para>
|
||||
Each of these criteria can be altered in the nixpkgs configuration.
|
||||
</para>
|
||||
<para>
|
||||
The nixpkgs configuration for a NixOS system is set in the
|
||||
<literal>configuration.nix</literal>, as in the following example:
|
||||
<programlisting>
|
||||
{
|
||||
nixpkgs.config = {
|
||||
@@ -44,187 +53,197 @@ configuration.</para>
|
||||
};
|
||||
}
|
||||
</programlisting>
|
||||
However, this does not allow unfree software for individual users.
|
||||
Their configurations are managed separately.</para>
|
||||
|
||||
<para>A user's of nixpkgs configuration is stored in a user-specific
|
||||
configuration file located at
|
||||
<filename>~/.config/nixpkgs/config.nix</filename>. For example:
|
||||
However, this does not allow unfree software for individual users. Their
|
||||
configurations are managed separately.
|
||||
</para>
|
||||
<para>
|
||||
A user's of nixpkgs configuration is stored in a user-specific configuration
|
||||
file located at <filename>~/.config/nixpkgs/config.nix</filename>. For
|
||||
example:
|
||||
<programlisting>
|
||||
{
|
||||
allowUnfree = true;
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>Note that we are not able to test or build unfree software on Hydra
|
||||
due to policy. Most unfree licenses prohibit us from either executing or
|
||||
distributing the software.</para>
|
||||
|
||||
<section xml:id="sec-allow-broken">
|
||||
</para>
|
||||
<para>
|
||||
Note that we are not able to test or build unfree software on Hydra due to
|
||||
policy. Most unfree licenses prohibit us from either executing or
|
||||
distributing the software.
|
||||
</para>
|
||||
<section xml:id="sec-allow-broken">
|
||||
<title>Installing broken packages</title>
|
||||
|
||||
|
||||
<para>There are two ways to try compiling a package which has been
|
||||
marked as broken.</para>
|
||||
<para>
|
||||
There are two ways to try compiling a package which has been marked as
|
||||
broken.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
For allowing the build of a broken package once, you can use an
|
||||
environment variable for a single invocation of the nix tools:
|
||||
|
||||
<programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting>
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
For permanently allowing broken packages to be built, you may
|
||||
add <literal>allowBroken = true;</literal> to your user's
|
||||
configuration file, like this:
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
For allowing the build of a broken package once, you can use an
|
||||
environment variable for a single invocation of the nix tools:
|
||||
<programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
For permanently allowing broken packages to be built, you may add
|
||||
<literal>allowBroken = true;</literal> to your user's configuration file,
|
||||
like this:
|
||||
<programlisting>
|
||||
{
|
||||
allowBroken = true;
|
||||
}
|
||||
</programlisting>
|
||||
</para></listitem>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section xml:id="sec-allow-unsupported-system">
|
||||
</section>
|
||||
<section xml:id="sec-allow-unsupported-system">
|
||||
<title>Installing packages on unsupported systems</title>
|
||||
|
||||
|
||||
<para>
|
||||
There are also two ways to try compiling a package which has been marked as unsuported for the given system.
|
||||
There are also two ways to try compiling a package which has been marked as
|
||||
unsuported for the given system.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools:
|
||||
|
||||
<programlisting>$ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1</programlisting>
|
||||
</para></listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
For permanently allowing broken packages to be built, you may add <literal>allowUnsupportedSystem = true;</literal> to your user's configuration file, like this:
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
For allowing the build of a broken package once, you can use an
|
||||
environment variable for a single invocation of the nix tools:
|
||||
<programlisting>$ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
For permanently allowing broken packages to be built, you may add
|
||||
<literal>allowUnsupportedSystem = true;</literal> to your user's
|
||||
configuration file, like this:
|
||||
<programlisting>
|
||||
{
|
||||
allowUnsupportedSystem = true;
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
The difference between an a package being unsupported on some system and being broken is admittedly a bit fuzzy.
|
||||
If a program <emphasis>ought</emphasis> to work on a certain platform, but doesn't, the platform should be included in <literal>meta.platforms</literal>, but marked as broken with e.g. <literal>meta.broken = !hostPlatform.isWindows</literal>.
|
||||
Of course, this begs the question of what "ought" means exactly.
|
||||
That is left to the package maintainer.
|
||||
The difference between an a package being unsupported on some system and
|
||||
being broken is admittedly a bit fuzzy. If a program
|
||||
<emphasis>ought</emphasis> to work on a certain platform, but doesn't, the
|
||||
platform should be included in <literal>meta.platforms</literal>, but marked
|
||||
as broken with e.g. <literal>meta.broken =
|
||||
!hostPlatform.isWindows</literal>. Of course, this begs the question of what
|
||||
"ought" means exactly. That is left to the package maintainer.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="sec-allow-unfree">
|
||||
</section>
|
||||
<section xml:id="sec-allow-unfree">
|
||||
<title>Installing unfree packages</title>
|
||||
|
||||
<para>There are several ways to tweak how Nix handles a package
|
||||
which has been marked as unfree.</para>
|
||||
<para>
|
||||
There are several ways to tweak how Nix handles a package which has been
|
||||
marked as unfree.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
To temporarily allow all unfree packages, you can use an
|
||||
environment variable for a single invocation of the nix tools:
|
||||
|
||||
<programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
It is possible to permanently allow individual unfree packages,
|
||||
while still blocking unfree packages by default using the
|
||||
<literal>allowUnfreePredicate</literal> configuration
|
||||
option in the user configuration file.</para>
|
||||
|
||||
<para>This option is a function which accepts a package as a
|
||||
parameter, and returns a boolean. The following example
|
||||
configuration accepts a package and always returns false:
|
||||
<listitem>
|
||||
<para>
|
||||
To temporarily allow all unfree packages, you can use an environment
|
||||
variable for a single invocation of the nix tools:
|
||||
<programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
It is possible to permanently allow individual unfree packages, while
|
||||
still blocking unfree packages by default using the
|
||||
<literal>allowUnfreePredicate</literal> configuration option in the user
|
||||
configuration file.
|
||||
</para>
|
||||
<para>
|
||||
This option is a function which accepts a package as a parameter, and
|
||||
returns a boolean. The following example configuration accepts a package
|
||||
and always returns false:
|
||||
<programlisting>
|
||||
{
|
||||
allowUnfreePredicate = (pkg: false);
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>A more useful example, the following configuration allows
|
||||
only allows flash player and visual studio code:
|
||||
|
||||
</para>
|
||||
<para>
|
||||
A more useful example, the following configuration allows only allows
|
||||
flash player and visual studio code:
|
||||
<programlisting>
|
||||
{
|
||||
allowUnfreePredicate = (pkg: elem (builtins.parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);
|
||||
}
|
||||
</programlisting>
|
||||
</para></listitem>
|
||||
|
||||
<listitem>
|
||||
<para>It is also possible to whitelist and blacklist licenses
|
||||
that are specifically acceptable or not acceptable, using
|
||||
<literal>whitelistedLicenses</literal> and
|
||||
<literal>blacklistedLicenses</literal>, respectively.
|
||||
</para>
|
||||
|
||||
<para>The following example configuration whitelists the
|
||||
licenses <literal>amd</literal> and <literal>wtfpl</literal>:
|
||||
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
It is also possible to whitelist and blacklist licenses that are
|
||||
specifically acceptable or not acceptable, using
|
||||
<literal>whitelistedLicenses</literal> and
|
||||
<literal>blacklistedLicenses</literal>, respectively.
|
||||
</para>
|
||||
<para>
|
||||
The following example configuration whitelists the licenses
|
||||
<literal>amd</literal> and <literal>wtfpl</literal>:
|
||||
<programlisting>
|
||||
{
|
||||
whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>The following example configuration blacklists the
|
||||
<literal>gpl3</literal> and <literal>agpl3</literal> licenses:
|
||||
|
||||
</para>
|
||||
<para>
|
||||
The following example configuration blacklists the <literal>gpl3</literal>
|
||||
and <literal>agpl3</literal> licenses:
|
||||
<programlisting>
|
||||
{
|
||||
blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>A complete list of licenses can be found in the file
|
||||
<filename>lib/licenses.nix</filename> of the nixpkgs tree.</para>
|
||||
</section>
|
||||
<para>
|
||||
A complete list of licenses can be found in the file
|
||||
<filename>lib/licenses.nix</filename> of the nixpkgs tree.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-allow-insecure">
|
||||
<title>Installing insecure packages</title>
|
||||
|
||||
|
||||
<section xml:id="sec-allow-insecure">
|
||||
<title>
|
||||
Installing insecure packages
|
||||
</title>
|
||||
|
||||
<para>There are several ways to tweak how Nix handles a package
|
||||
which has been marked as insecure.</para>
|
||||
<para>
|
||||
There are several ways to tweak how Nix handles a package which has been
|
||||
marked as insecure.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
To temporarily allow all insecure packages, you can use an
|
||||
environment variable for a single invocation of the nix tools:
|
||||
|
||||
<programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting>
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
It is possible to permanently allow individual insecure
|
||||
packages, while still blocking other insecure packages by
|
||||
default using the <literal>permittedInsecurePackages</literal>
|
||||
configuration option in the user configuration file.</para>
|
||||
|
||||
<para>The following example configuration permits the
|
||||
installation of the hypothetically insecure package
|
||||
<literal>hello</literal>, version <literal>1.2.3</literal>:
|
||||
<listitem>
|
||||
<para>
|
||||
To temporarily allow all insecure packages, you can use an environment
|
||||
variable for a single invocation of the nix tools:
|
||||
<programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
It is possible to permanently allow individual insecure packages, while
|
||||
still blocking other insecure packages by default using the
|
||||
<literal>permittedInsecurePackages</literal> configuration option in the
|
||||
user configuration file.
|
||||
</para>
|
||||
<para>
|
||||
The following example configuration permits the installation of the
|
||||
hypothetically insecure package <literal>hello</literal>, version
|
||||
<literal>1.2.3</literal>:
|
||||
<programlisting>
|
||||
{
|
||||
permittedInsecurePackages = [
|
||||
@@ -232,47 +251,44 @@ distributing the software.</para>
|
||||
];
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem><para>
|
||||
It is also possible to create a custom policy around which
|
||||
insecure packages to allow and deny, by overriding the
|
||||
<literal>allowInsecurePredicate</literal> configuration
|
||||
option.</para>
|
||||
|
||||
<para>The <literal>allowInsecurePredicate</literal> option is a
|
||||
function which accepts a package and returns a boolean, much
|
||||
like <literal>allowUnfreePredicate</literal>.</para>
|
||||
|
||||
<para>The following configuration example only allows insecure
|
||||
packages with very short names:
|
||||
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
It is also possible to create a custom policy around which insecure
|
||||
packages to allow and deny, by overriding the
|
||||
<literal>allowInsecurePredicate</literal> configuration option.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>allowInsecurePredicate</literal> option is a function which
|
||||
accepts a package and returns a boolean, much like
|
||||
<literal>allowUnfreePredicate</literal>.
|
||||
</para>
|
||||
<para>
|
||||
The following configuration example only allows insecure packages with
|
||||
very short names:
|
||||
<programlisting>
|
||||
{
|
||||
allowInsecurePredicate = (pkg: (builtins.stringLength (builtins.parseDrvName pkg.name).name) <= 5);
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>Note that <literal>permittedInsecurePackages</literal> is
|
||||
only checked if <literal>allowInsecurePredicate</literal> is not
|
||||
specified.
|
||||
</para></listitem>
|
||||
</para>
|
||||
<para>
|
||||
Note that <literal>permittedInsecurePackages</literal> is only checked if
|
||||
<literal>allowInsecurePredicate</literal> is not specified.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
</section>
|
||||
<!--============================================================-->
|
||||
<section xml:id="sec-modify-via-packageOverrides">
|
||||
<title>Modify packages via <literal>packageOverrides</literal></title>
|
||||
|
||||
<section xml:id="sec-modify-via-packageOverrides"><title>Modify
|
||||
packages via <literal>packageOverrides</literal></title>
|
||||
|
||||
<para>You can define a function called
|
||||
<varname>packageOverrides</varname> in your local
|
||||
<filename>~/.config/nixpkgs/config.nix</filename> to override nix packages. It
|
||||
must be a function that takes pkgs as an argument and return modified
|
||||
set of packages.
|
||||
|
||||
<para>
|
||||
You can define a function called <varname>packageOverrides</varname> in your
|
||||
local <filename>~/.config/nixpkgs/config.nix</filename> to override nix
|
||||
packages. It must be a function that takes pkgs as an argument and return
|
||||
modified set of packages.
|
||||
<programlisting>
|
||||
{
|
||||
packageOverrides = pkgs: rec {
|
||||
@@ -280,30 +296,27 @@ set of packages.
|
||||
};
|
||||
}
|
||||
</programlisting>
|
||||
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section xml:id="sec-declarative-package-management">
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="sec-declarative-package-management">
|
||||
<title>Declarative Package Management</title>
|
||||
|
||||
<section xml:id="sec-building-environment">
|
||||
<title>Build an environment</title>
|
||||
<title>Build an environment</title>
|
||||
|
||||
<para>
|
||||
Using <literal>packageOverrides</literal>, it is possible to manage
|
||||
packages declaratively. This means that we can list all of our desired
|
||||
packages within a declarative Nix expression. For example, to have
|
||||
<literal>aspell</literal>, <literal>bc</literal>,
|
||||
<literal>ffmpeg</literal>, <literal>coreutils</literal>,
|
||||
<literal>gdb</literal>, <literal>nixUnstable</literal>,
|
||||
<literal>emscripten</literal>, <literal>jq</literal>,
|
||||
<literal>nox</literal>, and <literal>silver-searcher</literal>, we could
|
||||
use the following in <filename>~/.config/nixpkgs/config.nix</filename>:
|
||||
</para>
|
||||
<para>
|
||||
Using <literal>packageOverrides</literal>, it is possible to manage
|
||||
packages declaratively. This means that we can list all of our desired
|
||||
packages within a declarative Nix expression. For example, to have
|
||||
<literal>aspell</literal>, <literal>bc</literal>,
|
||||
<literal>ffmpeg</literal>, <literal>coreutils</literal>,
|
||||
<literal>gdb</literal>, <literal>nixUnstable</literal>,
|
||||
<literal>emscripten</literal>, <literal>jq</literal>,
|
||||
<literal>nox</literal>, and <literal>silver-searcher</literal>, we could
|
||||
use the following in <filename>~/.config/nixpkgs/config.nix</filename>:
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
<screen>
|
||||
{
|
||||
packageOverrides = pkgs: with pkgs; {
|
||||
myPackages = pkgs.buildEnv {
|
||||
@@ -314,17 +327,17 @@ set of packages.
|
||||
}
|
||||
</screen>
|
||||
|
||||
<para>
|
||||
To install it into our environment, you can just run <literal>nix-env -iA
|
||||
nixpkgs.myPackages</literal>. If you want to load the packages to be built
|
||||
from a working copy of <literal>nixpkgs</literal> you just run
|
||||
<literal>nix-env -f. -iA myPackages</literal>. To explore what's been
|
||||
installed, just look through <filename>~/.nix-profile/</filename>. You can
|
||||
see that a lot of stuff has been installed. Some of this stuff is useful
|
||||
some of it isn't. Let's tell Nixpkgs to only link the stuff that we want:
|
||||
</para>
|
||||
<para>
|
||||
To install it into our environment, you can just run <literal>nix-env -iA
|
||||
nixpkgs.myPackages</literal>. If you want to load the packages to be built
|
||||
from a working copy of <literal>nixpkgs</literal> you just run
|
||||
<literal>nix-env -f. -iA myPackages</literal>. To explore what's been
|
||||
installed, just look through <filename>~/.nix-profile/</filename>. You can
|
||||
see that a lot of stuff has been installed. Some of this stuff is useful
|
||||
some of it isn't. Let's tell Nixpkgs to only link the stuff that we want:
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
<screen>
|
||||
{
|
||||
packageOverrides = pkgs: with pkgs; {
|
||||
myPackages = pkgs.buildEnv {
|
||||
@@ -336,31 +349,30 @@ set of packages.
|
||||
}
|
||||
</screen>
|
||||
|
||||
<para>
|
||||
<literal>pathsToLink</literal> tells Nixpkgs to only link the paths listed
|
||||
which gets rid of the extra stuff in the profile.
|
||||
<filename>/bin</filename> and <filename>/share</filename> are good
|
||||
defaults for a user environment, getting rid of the clutter. If you are
|
||||
running on Nix on MacOS, you may want to add another path as well,
|
||||
<filename>/Applications</filename>, that makes GUI apps available.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<literal>pathsToLink</literal> tells Nixpkgs to only link the paths listed
|
||||
which gets rid of the extra stuff in the profile. <filename>/bin</filename>
|
||||
and <filename>/share</filename> are good defaults for a user environment,
|
||||
getting rid of the clutter. If you are running on Nix on MacOS, you may
|
||||
want to add another path as well, <filename>/Applications</filename>, that
|
||||
makes GUI apps available.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="sec-getting-documentation">
|
||||
<title>Getting documentation</title>
|
||||
<title>Getting documentation</title>
|
||||
|
||||
<para>
|
||||
After building that new environment, look through
|
||||
<filename>~/.nix-profile</filename> to make sure everything is there that
|
||||
we wanted. Discerning readers will note that some files are missing. Look
|
||||
inside <filename>~/.nix-profile/share/man/man1/</filename> to verify this.
|
||||
There are no man pages for any of the Nix tools! This is because some
|
||||
packages like Nix have multiple outputs for things like documentation (see
|
||||
section 4). Let's make Nix install those as well.
|
||||
</para>
|
||||
<para>
|
||||
After building that new environment, look through
|
||||
<filename>~/.nix-profile</filename> to make sure everything is there that
|
||||
we wanted. Discerning readers will note that some files are missing. Look
|
||||
inside <filename>~/.nix-profile/share/man/man1/</filename> to verify this.
|
||||
There are no man pages for any of the Nix tools! This is because some
|
||||
packages like Nix have multiple outputs for things like documentation (see
|
||||
section 4). Let's make Nix install those as well.
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
<screen>
|
||||
{
|
||||
packageOverrides = pkgs: with pkgs; {
|
||||
myPackages = pkgs.buildEnv {
|
||||
@@ -373,14 +385,13 @@ set of packages.
|
||||
}
|
||||
</screen>
|
||||
|
||||
<para>
|
||||
This provides us with some useful documentation for using our packages.
|
||||
However, if we actually want those manpages to be detected by man, we need
|
||||
to set up our environment. This can also be managed within Nix
|
||||
expressions.
|
||||
</para>
|
||||
<para>
|
||||
This provides us with some useful documentation for using our packages.
|
||||
However, if we actually want those manpages to be detected by man, we need
|
||||
to set up our environment. This can also be managed within Nix expressions.
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
<screen>
|
||||
{
|
||||
packageOverrides = pkgs: with pkgs; rec {
|
||||
myProfile = writeText "my-profile" ''
|
||||
@@ -412,13 +423,13 @@ cp ${myProfile} $out/etc/profile.d/my-profile.sh
|
||||
}
|
||||
</screen>
|
||||
|
||||
<para>
|
||||
For this to work fully, you must also have this script sourced when you
|
||||
are logged in. Try adding something like this to your
|
||||
<filename>~/.profile</filename> file:
|
||||
</para>
|
||||
<para>
|
||||
For this to work fully, you must also have this script sourced when you are
|
||||
logged in. Try adding something like this to your
|
||||
<filename>~/.profile</filename> file:
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
<screen>
|
||||
#!/bin/sh
|
||||
if [ -d $HOME/.nix-profile/etc/profile.d ]; then
|
||||
for i in $HOME/.nix-profile/etc/profile.d/*.sh; do
|
||||
@@ -429,23 +440,22 @@ if [ -d $HOME/.nix-profile/etc/profile.d ]; then
|
||||
fi
|
||||
</screen>
|
||||
|
||||
<para>
|
||||
Now just run <literal>source $HOME/.profile</literal> and you can starting
|
||||
loading man pages from your environent.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now just run <literal>source $HOME/.profile</literal> and you can starting
|
||||
loading man pages from your environent.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="sec-gnu-info-setup">
|
||||
<title>GNU info setup</title>
|
||||
<title>GNU info setup</title>
|
||||
|
||||
<para>
|
||||
Configuring GNU info is a little bit trickier than man pages. To work
|
||||
correctly, info needs a database to be generated. This can be done with
|
||||
some small modifications to our environment scripts.
|
||||
</para>
|
||||
<para>
|
||||
Configuring GNU info is a little bit trickier than man pages. To work
|
||||
correctly, info needs a database to be generated. This can be done with
|
||||
some small modifications to our environment scripts.
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
<screen>
|
||||
{
|
||||
packageOverrides = pkgs: with pkgs; rec {
|
||||
myProfile = writeText "my-profile" ''
|
||||
@@ -487,16 +497,13 @@ cp ${myProfile} $out/etc/profile.d/my-profile.sh
|
||||
}
|
||||
</screen>
|
||||
|
||||
<para>
|
||||
<literal>postBuild</literal> tells Nixpkgs to run a command after building
|
||||
the environment. In this case, <literal>install-info</literal> adds the
|
||||
installed info pages to <literal>dir</literal> which is GNU info's default
|
||||
root node. Note that <literal>texinfoInteractive</literal> is added to the
|
||||
environment to give the <literal>install-info</literal> command.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<literal>postBuild</literal> tells Nixpkgs to run a command after building
|
||||
the environment. In this case, <literal>install-info</literal> adds the
|
||||
installed info pages to <literal>dir</literal> which is GNU info's default
|
||||
root node. Note that <literal>texinfoInteractive</literal> is added to the
|
||||
environment to give the <literal>install-info</literal> command.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
</section>
|
||||
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
Reference in New Issue
Block a user