43dade238f
This is a new package that provides a shell hook to make it easy to
declare manpages and shell completions in a manner that doesn't require
remembering where to actually install them. Basic usage looks like
{ stdenv, installShellFiles, ... }:
stdenv.mkDerivation {
# ...
nativeBuildInputs = [ installShellFiles ];
postInstall = ''
installManPage doc/foobar.1
installShellCompletion --bash share/completions/foobar.bash
installShellCompletion --fish share/completions/foobar.fish
installShellCompletion --zsh share/completions/_foobar
'';
# ...
}
See source comments for more details on the functions.
3137 lines
110 KiB
XML
3137 lines
110 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
xml:id="chap-stdenv">
|
||
<title>The Standard Environment</title>
|
||
<para>
|
||
The standard build environment in the Nix Packages collection provides an
|
||
environment for building Unix packages that does a lot of common build tasks
|
||
automatically. In fact, for Unix packages that use the standard
|
||
<literal>./configure; make; make install</literal> build interface, you
|
||
don’t need to write a build script at all; the standard environment does
|
||
everything automatically. If <literal>stdenv</literal> doesn’t do what you
|
||
need automatically, you can easily customise or override the various build
|
||
phases.
|
||
</para>
|
||
<section xml:id="sec-using-stdenv">
|
||
<title>Using <literal>stdenv</literal></title>
|
||
|
||
<para>
|
||
To build a package with the standard environment, you use the function
|
||
<varname>stdenv.mkDerivation</varname>, instead of the primitive built-in
|
||
function <varname>derivation</varname>, e.g.
|
||
<programlisting>
|
||
stdenv.mkDerivation {
|
||
name = "libfoo-1.2.3";
|
||
src = fetchurl {
|
||
url = http://example.org/libfoo-1.2.3.tar.bz2;
|
||
sha256 = "0x2g1jqygyr5wiwg4ma1nd7w4ydpy82z9gkcv8vh2v8dn3y58v5m";
|
||
};
|
||
}</programlisting>
|
||
(<varname>stdenv</varname> needs to be in scope, so if you write this in a
|
||
separate Nix expression from <filename>pkgs/all-packages.nix</filename>, you
|
||
need to pass it as a function argument.) Specifying a
|
||
<varname>name</varname> and a <varname>src</varname> is the absolute minimum
|
||
Nix requires. For convenience, you can also use <varname>pname</varname> and
|
||
<varname>version</varname> attributes and <literal>mkDerivation</literal>
|
||
will automatically set <varname>name</varname> to
|
||
<literal>"${pname}-${version}"</literal> by default. Since
|
||
<link xlink:href="https://github.com/NixOS/rfcs/pull/35">RFC 0035</link>,
|
||
this is preferred for packages in Nixpkgs, as it allows us to reuse the
|
||
version easily:
|
||
<programlisting>
|
||
stdenv.mkDerivation rec {
|
||
pname = "libfoo";
|
||
version = "1.2.3";
|
||
src = fetchurl {
|
||
url = "http://example.org/libfoo-source-${version}.tar.bz2";
|
||
sha256 = "0x2g1jqygyr5wiwg4ma1nd7w4ydpy82z9gkcv8vh2v8dn3y58v5m";
|
||
};
|
||
}</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
Many packages have dependencies that are not provided in the standard
|
||
environment. It’s usually sufficient to specify those dependencies in the
|
||
<varname>buildInputs</varname> attribute:
|
||
<programlisting>
|
||
stdenv.mkDerivation {
|
||
name = "libfoo-1.2.3";
|
||
...
|
||
buildInputs = [libbar perl ncurses];
|
||
}</programlisting>
|
||
This attribute ensures that the <filename>bin</filename> subdirectories of
|
||
these packages appear in the <envar>PATH</envar> environment variable during
|
||
the build, that their <filename>include</filename> subdirectories are
|
||
searched by the C compiler, and so on. (See
|
||
<xref linkend="ssec-setup-hooks"/> for details.)
|
||
</para>
|
||
|
||
<para>
|
||
Often it is necessary to override or modify some aspect of the build. To
|
||
make this easier, the standard environment breaks the package build into a
|
||
number of <emphasis>phases</emphasis>, all of which can be overridden or
|
||
modified individually: unpacking the sources, applying patches, configuring,
|
||
building, and installing. (There are some others; see
|
||
<xref linkend="sec-stdenv-phases"/>.) For instance, a package that doesn’t
|
||
supply a makefile but instead has to be compiled “manually” could be
|
||
handled like this:
|
||
<programlisting>
|
||
stdenv.mkDerivation {
|
||
name = "fnord-4.5";
|
||
...
|
||
buildPhase = ''
|
||
gcc foo.c -o foo
|
||
'';
|
||
installPhase = ''
|
||
mkdir -p $out/bin
|
||
cp foo $out/bin
|
||
'';
|
||
}</programlisting>
|
||
(Note the use of <literal>''</literal>-style string literals, which are very
|
||
convenient for large multi-line script fragments because they don’t need
|
||
escaping of <literal>"</literal> and <literal>\</literal>, and because
|
||
indentation is intelligently removed.)
|
||
</para>
|
||
|
||
<para>
|
||
There are many other attributes to customise the build. These are listed in
|
||
<xref linkend="ssec-stdenv-attributes"/>.
|
||
</para>
|
||
|
||
<para>
|
||
While the standard environment provides a generic builder, you can still
|
||
supply your own build script:
|
||
<programlisting>
|
||
stdenv.mkDerivation {
|
||
name = "libfoo-1.2.3";
|
||
...
|
||
builder = ./builder.sh;
|
||
}</programlisting>
|
||
where the builder can do anything it wants, but typically starts with
|
||
<programlisting>
|
||
source $stdenv/setup
|
||
</programlisting>
|
||
to let <literal>stdenv</literal> set up the environment (e.g., process the
|
||
<varname>buildInputs</varname>). If you want, you can still use
|
||
<literal>stdenv</literal>’s generic builder:
|
||
<programlisting>
|
||
source $stdenv/setup
|
||
|
||
buildPhase() {
|
||
echo "... this is my custom build phase ..."
|
||
gcc foo.c -o foo
|
||
}
|
||
|
||
installPhase() {
|
||
mkdir -p $out/bin
|
||
cp foo $out/bin
|
||
}
|
||
|
||
genericBuild
|
||
</programlisting>
|
||
</para>
|
||
</section>
|
||
<section xml:id="sec-tools-of-stdenv">
|
||
<title>Tools provided by <literal>stdenv</literal></title>
|
||
|
||
<para>
|
||
The standard environment provides the following packages:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
The GNU C Compiler, configured with C and C++ support.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
GNU coreutils (contains a few dozen standard Unix commands).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
GNU findutils (contains <command>find</command>).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
GNU diffutils (contains <command>diff</command>, <command>cmp</command>).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
GNU <command>sed</command>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
GNU <command>grep</command>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
GNU <command>awk</command>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
GNU <command>tar</command>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<command>gzip</command>, <command>bzip2</command> and
|
||
<command>xz</command>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
GNU Make. It has been patched to provide <quote>nested</quote> output
|
||
that can be fed into the <command>nix-log2xml</command> command and
|
||
<command>log2html</command> stylesheet to create a structured, readable
|
||
output of the build steps performed by Make.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Bash. This is the shell used for all builders in the Nix Packages
|
||
collection. Not using <command>/bin/sh</command> removes a large source
|
||
of portability problems.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <command>patch</command> command.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
On Linux, <literal>stdenv</literal> also includes the
|
||
<command>patchelf</command> utility.
|
||
</para>
|
||
</section>
|
||
<section xml:id="ssec-stdenv-dependencies">
|
||
<title>Specifying dependencies</title>
|
||
|
||
<para>
|
||
As described in the Nix manual, almost any <filename>*.drv</filename> store
|
||
path in a derivation's attribute set will induce a dependency on that
|
||
derivation. <varname>mkDerivation</varname>, however, takes a few attributes
|
||
intended to, between them, include all the dependencies of a package. This
|
||
is done both for structure and consistency, but also so that certain other
|
||
setup can take place. For example, certain dependencies need their bin
|
||
directories added to the <envar>PATH</envar>. That is built-in, but other
|
||
setup is done via a pluggable mechanism that works in conjunction with these
|
||
dependency attributes. See <xref linkend="ssec-setup-hooks"/> for details.
|
||
</para>
|
||
|
||
<para>
|
||
Dependencies can be broken down along three axes: their host and target
|
||
platforms relative to the new derivation's, and whether they are propagated.
|
||
The platform distinctions are motivated by cross compilation; see
|
||
<xref linkend="chap-cross"/> for exactly what each platform means.
|
||
<footnote xml:id="footnote-stdenv-ignored-build-platform">
|
||
<para>
|
||
The build platform is ignored because it is a mere implementation detail
|
||
of the package satisfying the dependency: As a general programming
|
||
principle, dependencies are always <emphasis>specified</emphasis> as
|
||
interfaces, not concrete implementation.
|
||
</para>
|
||
</footnote>
|
||
But even if one is not cross compiling, the platforms imply whether or not
|
||
the dependency is needed at run-time or build-time, a concept that makes
|
||
perfect sense outside of cross compilation. By default, the
|
||
run-time/build-time distinction is just a hint for mental clarity, but with
|
||
<varname>strictDeps</varname> set it is mostly enforced even in the native
|
||
case.
|
||
</para>
|
||
|
||
<para>
|
||
The extension of <envar>PATH</envar> with dependencies, alluded to above,
|
||
proceeds according to the relative platforms alone. The process is carried
|
||
out only for dependencies whose host platform matches the new derivation's
|
||
build platform i.e. dependencies which run on the platform where the new
|
||
derivation will be built.
|
||
<footnote xml:id="footnote-stdenv-native-dependencies-in-path">
|
||
<para>
|
||
Currently, this means for native builds all dependencies are put on the
|
||
<envar>PATH</envar>. But in the future that may not be the case for sake
|
||
of matching cross: the platforms would be assumed to be unique for native
|
||
and cross builds alike, so only the <varname>depsBuild*</varname> and
|
||
<varname>nativeBuildInputs</varname> would be added to the
|
||
<envar>PATH</envar>.
|
||
</para>
|
||
</footnote>
|
||
For each dependency <replaceable>dep</replaceable> of those dependencies,
|
||
<filename><replaceable>dep</replaceable>/bin</filename>, if present, is
|
||
added to the <envar>PATH</envar> environment variable.
|
||
</para>
|
||
|
||
<para>
|
||
The dependency is propagated when it forces some of its other-transitive
|
||
(non-immediate) downstream dependencies to also take it on as an immediate
|
||
dependency. Nix itself already takes a package's transitive dependencies
|
||
into account, but this propagation ensures nixpkgs-specific infrastructure
|
||
like setup hooks (mentioned above) also are run as if the propagated
|
||
dependency.
|
||
</para>
|
||
|
||
<para>
|
||
It is important to note that dependencies are not necessarily propagated as
|
||
the same sort of dependency that they were before, but rather as the
|
||
corresponding sort so that the platform rules still line up. The exact rules
|
||
for dependency propagation can be given by assigning to each dependency two
|
||
integers based one how its host and target platforms are offset from the
|
||
depending derivation's platforms. Those offsets are given below in the
|
||
descriptions of each dependency list attribute. Algorithmically, we traverse
|
||
propagated inputs, accumulating every propagated dependency's propagated
|
||
dependencies and adjusting them to account for the "shift in perspective"
|
||
described by the current dependency's platform offsets. This results in sort
|
||
a transitive closure of the dependency relation, with the offsets being
|
||
approximately summed when two dependency links are combined. We also prune
|
||
transitive dependencies whose combined offsets go out-of-bounds, which can
|
||
be viewed as a filter over that transitive closure removing dependencies
|
||
that are blatantly absurd.
|
||
</para>
|
||
|
||
<para>
|
||
We can define the process precisely with
|
||
<link xlink:href="https://en.wikipedia.org/wiki/Natural_deduction">Natural
|
||
Deduction</link> using the inference rules. This probably seems a bit
|
||
obtuse, but so is the bash code that actually implements it!
|
||
<footnote xml:id="footnote-stdenv-find-inputs-location">
|
||
<para>
|
||
The <function>findInputs</function> function, currently residing in
|
||
<filename>pkgs/stdenv/generic/setup.sh</filename>, implements the
|
||
propagation logic.
|
||
</para>
|
||
</footnote>
|
||
They're confusing in very different ways so... hopefully if something
|
||
doesn't make sense in one presentation, it will in the other!
|
||
<programlisting>
|
||
let mapOffset(h, t, i) = i + (if i <= 0 then h else t - 1)
|
||
|
||
propagated-dep(h0, t0, A, B)
|
||
propagated-dep(h1, t1, B, C)
|
||
h0 + h1 in {-1, 0, 1}
|
||
h0 + t1 in {-1, 0, 1}
|
||
-------------------------------------- Transitive property
|
||
propagated-dep(mapOffset(h0, t0, h1),
|
||
mapOffset(h0, t0, t1),
|
||
A, C)</programlisting>
|
||
<programlisting>
|
||
let mapOffset(h, t, i) = i + (if i <= 0 then h else t - 1)
|
||
|
||
dep(h0, _, A, B)
|
||
propagated-dep(h1, t1, B, C)
|
||
h0 + h1 in {-1, 0, 1}
|
||
h0 + t1 in {-1, 0, -1}
|
||
----------------------------- Take immediate dependencies' propagated dependencies
|
||
propagated-dep(mapOffset(h0, t0, h1),
|
||
mapOffset(h0, t0, t1),
|
||
A, C)</programlisting>
|
||
<programlisting>
|
||
propagated-dep(h, t, A, B)
|
||
----------------------------- Propagated dependencies count as dependencies
|
||
dep(h, t, A, B)</programlisting>
|
||
Some explanation of this monstrosity is in order. In the common case, the
|
||
target offset of a dependency is the successor to the target offset:
|
||
<literal>t = h + 1</literal>. That means that:
|
||
<programlisting>
|
||
let f(h, t, i) = i + (if i <= 0 then h else t - 1)
|
||
let f(h, h + 1, i) = i + (if i <= 0 then h else (h + 1) - 1)
|
||
let f(h, h + 1, i) = i + (if i <= 0 then h else h)
|
||
let f(h, h + 1, i) = i + h
|
||
</programlisting>
|
||
This is where "sum-like" comes in from above: We can just sum all of the
|
||
host offsets to get the host offset of the transitive dependency. The target
|
||
offset is the transitive dependency is simply the host offset + 1, just as
|
||
it was with the dependencies composed to make this transitive one; it can be
|
||
ignored as it doesn't add any new information.
|
||
</para>
|
||
|
||
<para>
|
||
Because of the bounds checks, the uncommon cases are <literal>h =
|
||
t</literal> and <literal>h + 2 = t</literal>. In the former case, the
|
||
motivation for <function>mapOffset</function> is that since its host and
|
||
target platforms are the same, no transitive dependency of it should be able
|
||
to "discover" an offset greater than its reduced target offsets.
|
||
<function>mapOffset</function> effectively "squashes" all its transitive
|
||
dependencies' offsets so that none will ever be greater than the target
|
||
offset of the original <literal>h = t</literal> package. In the other case,
|
||
<literal>h + 1</literal> is skipped over between the host and target
|
||
offsets. Instead of squashing the offsets, we need to "rip" them apart so no
|
||
transitive dependencies' offset is that one.
|
||
</para>
|
||
|
||
<para>
|
||
Overall, the unifying theme here is that propagation shouldn't be
|
||
introducing transitive dependencies involving platforms the depending
|
||
package is unaware of. [One can imagine the dependending package asking for
|
||
dependencies with the platforms it knows about; other platforms it doesn't
|
||
know how to ask for. The platform description in that scenario is a kind of
|
||
unforagable capability.] The offset bounds checking and definition of
|
||
<function>mapOffset</function> together ensure that this is the case.
|
||
Discovering a new offset is discovering a new platform, and since those
|
||
platforms weren't in the derivation "spec" of the needing package, they
|
||
cannot be relevant. From a capability perspective, we can imagine that the
|
||
host and target platforms of a package are the capabilities a package
|
||
requires, and the depending package must provide the capability to the
|
||
dependency.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<title>Variables specifying dependencies</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>depsBuildBuild</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of dependencies whose host and target platforms are the new
|
||
derivation's build platform. This means a <literal>-1</literal> host and
|
||
<literal>-1</literal> target offset from the new derivation's platforms.
|
||
These are programs and libraries used at build time that produce programs
|
||
and libraries also used at build time. If the dependency doesn't care
|
||
about the target platform (i.e. isn't a compiler or similar tool), put it
|
||
in <varname>nativeBuildInputs</varname> instead. The most common use of
|
||
this <literal>buildPackages.stdenv.cc</literal>, the default C compiler
|
||
for this role. That example crops up more than one might think in old
|
||
commonly used C libraries.
|
||
</para>
|
||
<para>
|
||
Since these packages are able to be run at build-time, they are always
|
||
added to the <envar>PATH</envar>, as described above. But since these
|
||
packages are only guaranteed to be able to run then, they shouldn't
|
||
persist as run-time dependencies. This isn't currently enforced, but
|
||
could be in the future.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>nativeBuildInputs</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of dependencies whose host platform is the new derivation's build
|
||
platform, and target platform is the new derivation's host platform. This
|
||
means a <literal>-1</literal> host offset and <literal>0</literal> target
|
||
offset from the new derivation's platforms. These are programs and
|
||
libraries used at build-time that, if they are a compiler or similar
|
||
tool, produce code to run at run-time—i.e. tools used to build the new
|
||
derivation. If the dependency doesn't care about the target platform
|
||
(i.e. isn't a compiler or similar tool), put it here, rather than in
|
||
<varname>depsBuildBuild</varname> or <varname>depsBuildTarget</varname>.
|
||
This could be called <varname>depsBuildHost</varname> but
|
||
<varname>nativeBuildInputs</varname> is used for historical continuity.
|
||
</para>
|
||
<para>
|
||
Since these packages are able to be run at build-time, they are added to
|
||
the <envar>PATH</envar>, as described above. But since these packages are
|
||
only guaranteed to be able to run then, they shouldn't persist as
|
||
run-time dependencies. This isn't currently enforced, but could be in the
|
||
future.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>depsBuildTarget</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of dependencies whose host platform is the new derivation's build
|
||
platform, and target platform is the new derivation's target platform.
|
||
This means a <literal>-1</literal> host offset and <literal>1</literal>
|
||
target offset from the new derivation's platforms. These are programs
|
||
used at build time that produce code to run with code produced by the
|
||
depending package. Most commonly, these are tools used to build the
|
||
runtime or standard library that the currently-being-built compiler will
|
||
inject into any code it compiles. In many cases, the
|
||
currently-being-built-compiler is itself employed for that task, but when
|
||
that compiler won't run (i.e. its build and host platform differ) this is
|
||
not possible. Other times, the compiler relies on some other tool, like
|
||
binutils, that is always built separately so that the dependency is
|
||
unconditional.
|
||
</para>
|
||
<para>
|
||
This is a somewhat confusing concept to wrap one’s head around, and for
|
||
good reason. As the only dependency type where the platform offsets are
|
||
not adjacent integers, it requires thinking of a bootstrapping stage
|
||
<emphasis>two</emphasis> away from the current one. It and its use-case
|
||
go hand in hand and are both considered poor form: try to not need this
|
||
sort of dependency, and try to avoid building standard libraries and
|
||
runtimes in the same derivation as the compiler produces code using them.
|
||
Instead strive to build those like a normal library, using the
|
||
newly-built compiler just as a normal library would. In short, do not use
|
||
this attribute unless you are packaging a compiler and are sure it is
|
||
needed.
|
||
</para>
|
||
<para>
|
||
Since these packages are able to run at build time, they are added to the
|
||
<envar>PATH</envar>, as described above. But since these packages are
|
||
only guaranteed to be able to run then, they shouldn't persist as
|
||
run-time dependencies. This isn't currently enforced, but could be in the
|
||
future.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>depsHostHost</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of dependencies whose host and target platforms match the new
|
||
derivation's host platform. This means a <literal>0</literal> host offset
|
||
and <literal>0</literal> target offset from the new derivation's host
|
||
platform. These are packages used at run-time to generate code also used
|
||
at run-time. In practice, this would usually be tools used by compilers
|
||
for macros or a metaprogramming system, or libraries used by the macros
|
||
or metaprogramming code itself. It's always preferable to use a
|
||
<varname>depsBuildBuild</varname> dependency in the derivation being
|
||
built over a <varname>depsHostHost</varname> on the tool doing the
|
||
building for this purpose.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>buildInputs</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of dependencies whose host platform and target platform match the
|
||
new derivation's. This means a <literal>0</literal> host offset and a
|
||
<literal>1</literal> target offset from the new derivation's host
|
||
platform. This would be called <varname>depsHostTarget</varname> but for
|
||
historical continuity. If the dependency doesn't care about the target
|
||
platform (i.e. isn't a compiler or similar tool), put it here, rather
|
||
than in <varname>depsBuildBuild</varname>.
|
||
</para>
|
||
<para>
|
||
These are often programs and libraries used by the new derivation at
|
||
<emphasis>run</emphasis>-time, but that isn't always the case. For
|
||
example, the machine code in a statically-linked library is only used at
|
||
run-time, but the derivation containing the library is only needed at
|
||
build-time. Even in the dynamic case, the library may also be needed at
|
||
build-time to appease the linker.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>depsTargetTarget</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of dependencies whose host platform matches the new derivation's
|
||
target platform. This means a <literal>1</literal> offset from the new
|
||
derivation's platforms. These are packages that run on the target
|
||
platform, e.g. the standard library or run-time deps of standard library
|
||
that a compiler insists on knowing about. It's poor form in almost all
|
||
cases for a package to depend on another from a future stage [future
|
||
stage corresponding to positive offset]. Do not use this attribute unless
|
||
you are packaging a compiler and are sure it is needed.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>depsBuildBuildPropagated</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The propagated equivalent of <varname>depsBuildBuild</varname>. This
|
||
perhaps never ought to be used, but it is included for consistency [see
|
||
below for the others].
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>propagatedNativeBuildInputs</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The propagated equivalent of <varname>nativeBuildInputs</varname>. This
|
||
would be called <varname>depsBuildHostPropagated</varname> but for
|
||
historical continuity. For example, if package <varname>Y</varname> has
|
||
<literal>propagatedNativeBuildInputs = [X]</literal>, and package
|
||
<varname>Z</varname> has <literal>buildInputs = [Y]</literal>, then
|
||
package <varname>Z</varname> will be built as if it included package
|
||
<varname>X</varname> in its <varname>nativeBuildInputs</varname>. If
|
||
instead, package <varname>Z</varname> has <literal>nativeBuildInputs =
|
||
[Y]</literal>, then <varname>Z</varname> will be built as if it included
|
||
<varname>X</varname> in the <varname>depsBuildBuild</varname> of package
|
||
<varname>Z</varname>, because of the sum of the two <literal>-1</literal>
|
||
host offsets.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>depsBuildTargetPropagated</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The propagated equivalent of <varname>depsBuildTarget</varname>. This is
|
||
prefixed for the same reason of alerting potential users.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>depsHostHostPropagated</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The propagated equivalent of <varname>depsHostHost</varname>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>propagatedBuildInputs</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The propagated equivalent of <varname>buildInputs</varname>. This would
|
||
be called <varname>depsHostTargetPropagated</varname> but for historical
|
||
continuity.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>depsTargetTargetPropagated</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The propagated equivalent of <varname>depsTargetTarget</varname>. This is
|
||
prefixed for the same reason of alerting potential users.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
<section xml:id="ssec-stdenv-attributes">
|
||
<title>Attributes</title>
|
||
|
||
<variablelist>
|
||
<title>Variables affecting <literal>stdenv</literal> initialisation</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>NIX_DEBUG</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A natural number indicating how much information to log. If set to 1 or
|
||
higher, <literal>stdenv</literal> will print moderate debugging
|
||
information during the build. In particular, the <command>gcc</command>
|
||
and <command>ld</command> wrapper scripts will print out the complete
|
||
command line passed to the wrapped tools. If set to 6 or higher, the
|
||
<literal>stdenv</literal> setup script will be run with <literal>set
|
||
-x</literal> tracing. If set to 7 or higher, the <command>gcc</command>
|
||
and <command>ld</command> wrapper scripts will also be run with
|
||
<literal>set -x</literal> tracing.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<variablelist>
|
||
<title>Attributes affecting build properties</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>enableParallelBuilding</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set to <literal>true</literal>, <literal>stdenv</literal> will pass
|
||
specific flags to <literal>make</literal> and other build tools to enable
|
||
parallel building with up to <literal>build-cores</literal> workers.
|
||
</para>
|
||
<para>
|
||
Unless set to <literal>false</literal>, some build systems with good
|
||
support for parallel building including <literal>cmake</literal>,
|
||
<literal>meson</literal>, and <literal>qmake</literal> will set it to
|
||
<literal>true</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<variablelist>
|
||
<title>Special variables</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>passthru</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This is an attribute set which can be filled with arbitrary values. For
|
||
example:
|
||
<programlisting>
|
||
passthru = {
|
||
foo = "bar";
|
||
baz = {
|
||
value1 = 4;
|
||
value2 = 5;
|
||
};
|
||
}
|
||
</programlisting>
|
||
</para>
|
||
<para>
|
||
Values inside it are not passed to the builder, so you can change them
|
||
without triggering a rebuild. However, they can be accessed outside of a
|
||
derivation directly, as if they were set inside a derivation itself, e.g.
|
||
<literal>hello.baz.value1</literal>. We don't specify any usage or schema
|
||
of <literal>passthru</literal> - it is meant for values that would be
|
||
useful outside the derivation in other parts of a Nix expression (e.g. in
|
||
other derivations). An example would be to convey some specific
|
||
dependency of your derivation which contains a program with plugins
|
||
support. Later, others who make derivations with plugins can use
|
||
passed-through dependency to ensure that their plugin would be
|
||
binary-compatible with built program.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>passthru.updateScript</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A script to be run by <filename>maintainers/scripts/update.nix</filename>
|
||
when the package is matched. It needs to be an executable file, either on
|
||
the file system:
|
||
<programlisting>
|
||
passthru.updateScript = ./update.sh;
|
||
</programlisting>
|
||
or inside the expression itself:
|
||
<programlisting>
|
||
passthru.updateScript = writeScript "update-zoom-us" ''
|
||
#!/usr/bin/env nix-shell
|
||
#!nix-shell -i bash -p curl pcre common-updater-scripts
|
||
|
||
set -eu -o pipefail
|
||
|
||
version="$(curl -sI https://zoom.us/client/latest/zoom_x86_64.tar.xz | grep -Fi 'Location:' | pcregrep -o1 '/(([0-9]\.?)+)/')"
|
||
update-source-version zoom-us "$version"
|
||
'';
|
||
</programlisting>
|
||
The attribute can also contain a list, a script followed by arguments to
|
||
be passed to it:
|
||
<programlisting>
|
||
passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ];
|
||
</programlisting>
|
||
</para>
|
||
<para>
|
||
The script will be usually run from the root of the Nixpkgs repository
|
||
but you should not rely on that. Also note that the update scripts will
|
||
be run in parallel by default; you should avoid running <command>git
|
||
commit</command> or any other commands that cannot handle that.
|
||
</para>
|
||
<para>
|
||
For information about how to run the updates, execute
|
||
<command>nix-shell maintainers/scripts/update.nix</command>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
<section xml:id="sec-stdenv-phases">
|
||
<title>Phases</title>
|
||
|
||
<para>
|
||
The generic builder has a number of <emphasis>phases</emphasis>. Package
|
||
builds are split into phases to make it easier to override specific parts of
|
||
the build (e.g., unpacking the sources or installing the binaries).
|
||
Furthermore, it allows a nicer presentation of build logs in the Nix build
|
||
farm.
|
||
</para>
|
||
|
||
<para>
|
||
Each phase can be overridden in its entirety either by setting the
|
||
environment variable <varname><replaceable>name</replaceable>Phase</varname>
|
||
to a string containing some shell commands to be executed, or by redefining
|
||
the shell function <varname><replaceable>name</replaceable>Phase</varname>.
|
||
The former is convenient to override a phase from the derivation, while the
|
||
latter is convenient from a build script. However, typically one only wants
|
||
to <emphasis>add</emphasis> some commands to a phase, e.g. by defining
|
||
<literal>postInstall</literal> or <literal>preFixup</literal>, as skipping
|
||
some of the default actions may have unexpected consequences. The default
|
||
script for each phase is defined in the file <filename>pkgs/stdenv/generic/setup.sh</filename>.
|
||
</para>
|
||
|
||
<section xml:id="ssec-controlling-phases">
|
||
<title>Controlling phases</title>
|
||
|
||
<para>
|
||
There are a number of variables that control what phases are executed and
|
||
in what order:
|
||
<variablelist>
|
||
<title>Variables affecting phase control</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>phases</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the phases. You can change the order in which phases are
|
||
executed, or add new phases, by setting this variable. If it’s not
|
||
set, the default value is used, which is <literal>$prePhases
|
||
unpackPhase patchPhase $preConfigurePhases configurePhase
|
||
$preBuildPhases buildPhase checkPhase $preInstallPhases installPhase
|
||
fixupPhase installCheckPhase $preDistPhases distPhase $postPhases</literal>.
|
||
</para>
|
||
<para>
|
||
Usually, if you just want to add a few phases, it’s more convenient
|
||
to set one of the variables below (such as
|
||
<varname>preInstallPhases</varname>), as you then don’t specify all
|
||
the normal phases.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>prePhases</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Additional phases executed before any of the default phases.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preConfigurePhases</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Additional phases executed just before the configure phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preBuildPhases</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Additional phases executed just before the build phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preInstallPhases</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Additional phases executed just before the install phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preFixupPhases</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Additional phases executed just before the fixup phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preDistPhases</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Additional phases executed just before the distribution phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postPhases</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Additional phases executed after any of the default phases.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="ssec-unpack-phase">
|
||
<title>The unpack phase</title>
|
||
|
||
<para>
|
||
The unpack phase is responsible for unpacking the source code of the
|
||
package. The default implementation of <function>unpackPhase</function>
|
||
unpacks the source files listed in the <envar>src</envar> environment
|
||
variable to the current directory. It supports the following files by
|
||
default:
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
Tar files
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
These can optionally be compressed using <command>gzip</command>
|
||
(<filename>.tar.gz</filename>, <filename>.tgz</filename> or
|
||
<filename>.tar.Z</filename>), <command>bzip2</command>
|
||
(<filename>.tar.bz2</filename>, <filename>.tbz2</filename> or
|
||
<filename>.tbz</filename>) or <command>xz</command>
|
||
(<filename>.tar.xz</filename>, <filename>.tar.lzma</filename> or
|
||
<filename>.txz</filename>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
Zip files
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Zip files are unpacked using <command>unzip</command>. However,
|
||
<command>unzip</command> is not in the standard environment, so you
|
||
should add it to <varname>nativeBuildInputs</varname> yourself.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
Directories in the Nix store
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
These are simply copied to the current directory. The hash part of the
|
||
file name is stripped, e.g.
|
||
<filename>/nix/store/1wydxgby13cz...-my-sources</filename> would be
|
||
copied to <filename>my-sources</filename>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
Additional file types can be supported by setting the
|
||
<varname>unpackCmd</varname> variable (see below).
|
||
</para>
|
||
|
||
<para></para>
|
||
|
||
<variablelist>
|
||
<title>Variables controlling the unpack phase</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>srcs</varname> / <varname>src</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The list of source files or directories to be unpacked or copied. One of
|
||
these must be set.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>sourceRoot</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
After running <function>unpackPhase</function>, the generic builder
|
||
changes the current directory to the directory created by unpacking the
|
||
sources. If there are multiple source directories, you should set
|
||
<varname>sourceRoot</varname> to the name of the intended directory.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>setSourceRoot</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Alternatively to setting <varname>sourceRoot</varname>, you can set
|
||
<varname>setSourceRoot</varname> to a shell command to be evaluated by
|
||
the unpack phase after the sources have been unpacked. This command must
|
||
set <varname>sourceRoot</varname>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preUnpack</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the start of the unpack phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postUnpack</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the end of the unpack phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontUnpack</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Set to true to skip the unpack phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontMakeSourcesWritable</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set to <literal>1</literal>, the unpacked sources are
|
||
<emphasis>not</emphasis> made writable. By default, they are made
|
||
writable to prevent problems with read-only sources. For example, copied
|
||
store directories would be read-only without this.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>unpackCmd</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The unpack phase evaluates the string <literal>$unpackCmd</literal> for
|
||
any unrecognised file. The path to the current source file is contained
|
||
in the <varname>curSrc</varname> variable.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
|
||
<section xml:id="ssec-patch-phase">
|
||
<title>The patch phase</title>
|
||
|
||
<para>
|
||
The patch phase applies the list of patches defined in the
|
||
<varname>patches</varname> variable.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<title>Variables controlling the patch phase</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>patches</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The list of patches. They must be in the format accepted by the
|
||
<command>patch</command> command, and may optionally be compressed using
|
||
<command>gzip</command> (<filename>.gz</filename>),
|
||
<command>bzip2</command> (<filename>.bz2</filename>) or
|
||
<command>xz</command> (<filename>.xz</filename>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>patchFlags</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Flags to be passed to <command>patch</command>. If not set, the argument
|
||
<option>-p1</option> is used, which causes the leading directory
|
||
component to be stripped from the file names in each patch.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>prePatch</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the start of the patch phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postPatch</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the end of the patch phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
|
||
<section xml:id="ssec-configure-phase">
|
||
<title>The configure phase</title>
|
||
|
||
<para>
|
||
The configure phase prepares the source tree for building. The default
|
||
<function>configurePhase</function> runs <filename>./configure</filename>
|
||
(typically an Autoconf-generated script) if it exists.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<title>Variables controlling the configure phase</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>configureScript</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The name of the configure script. It defaults to
|
||
<filename>./configure</filename> if it exists; otherwise, the configure
|
||
phase is skipped. This can actually be a command (like <literal>perl
|
||
./Configure.pl</literal>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>configureFlags</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of strings passed as additional arguments to the configure
|
||
script.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontConfigure</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Set to true to skip the configure phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>configureFlagsArray</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A shell array containing additional arguments passed to the configure
|
||
script. You must use this instead of <varname>configureFlags</varname>
|
||
if the arguments contain spaces.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontAddPrefix</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
By default, the flag <literal>--prefix=$prefix</literal> is added to the
|
||
configure flags. If this is undesirable, set this variable to true.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>prefix</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The prefix under which the package must be installed, passed via the
|
||
<option>--prefix</option> option to the configure script. It defaults to
|
||
<option>$out</option>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>prefixKey</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The key to use when specifying the prefix. By default, this is set to
|
||
<option>--prefix=</option> as that is used by the majority of packages.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontAddDisableDepTrack</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
By default, the flag <literal>--disable-dependency-tracking</literal> is
|
||
added to the configure flags to speed up Automake-based builds. If this
|
||
is undesirable, set this variable to true.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontFixLibtool</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
By default, the configure phase applies some special hackery to all
|
||
files called <filename>ltmain.sh</filename> before running the configure
|
||
script in order to improve the purity of Libtool-based packages
|
||
<footnote xml:id="footnote-stdenv-sys-lib-search-path">
|
||
<para>
|
||
It clears the
|
||
<varname>sys_lib_<replaceable>*</replaceable>search_path</varname>
|
||
variables in the Libtool script to prevent Libtool from using
|
||
libraries in <filename>/usr/lib</filename> and such.
|
||
</para>
|
||
</footnote>
|
||
. If this is undesirable, set this variable to true.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontDisableStatic</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
By default, when the configure script has
|
||
<option>--enable-static</option>, the option
|
||
<option>--disable-static</option> is added to the configure flags.
|
||
</para>
|
||
<para>
|
||
If this is undesirable, set this variable to true.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>configurePlatforms</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
By default, when cross compiling, the configure script has
|
||
<option>--build=...</option> and <option>--host=...</option> passed.
|
||
Packages can instead pass <literal>[ "build" "host" "target" ]</literal>
|
||
or a subset to control exactly which platform flags are passed.
|
||
Compilers and other tools can use this to also pass the target platform.
|
||
<footnote xml:id="footnote-stdenv-build-time-guessing-impurity">
|
||
<para>
|
||
Eventually these will be passed building natively as well, to improve
|
||
determinism: build-time guessing, as is done today, is a risk of
|
||
impurity.
|
||
</para>
|
||
</footnote>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preConfigure</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the start of the configure phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postConfigure</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the end of the configure phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
|
||
<section xml:id="build-phase">
|
||
<title>The build phase</title>
|
||
|
||
<para>
|
||
The build phase is responsible for actually building the package (e.g.
|
||
compiling it). The default <function>buildPhase</function> simply calls
|
||
<command>make</command> if a file named <filename>Makefile</filename>,
|
||
<filename>makefile</filename> or <filename>GNUmakefile</filename> exists in
|
||
the current directory (or the <varname>makefile</varname> is explicitly
|
||
set); otherwise it does nothing.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<title>Variables controlling the build phase</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontBuild</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Set to true to skip the build phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>makefile</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The file name of the Makefile.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>makeFlags</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of strings passed as additional flags to <command>make</command>.
|
||
These flags are also used by the default install and check phase. For
|
||
setting make flags specific to the build phase, use
|
||
<varname>buildFlags</varname> (see below).
|
||
<programlisting>
|
||
makeFlags = [ "PREFIX=$(out)" ];
|
||
</programlisting>
|
||
<note>
|
||
<para>
|
||
The flags are quoted in bash, but environment variables can be
|
||
specified by using the make syntax.
|
||
</para>
|
||
</note>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>makeFlagsArray</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A shell array containing additional arguments passed to
|
||
<command>make</command>. You must use this instead of
|
||
<varname>makeFlags</varname> if the arguments contain spaces, e.g.
|
||
<programlisting>
|
||
preBuild = ''
|
||
makeFlagsArray+=(CFLAGS="-O0 -g" LDFLAGS="-lfoo -lbar")
|
||
'';
|
||
</programlisting>
|
||
Note that shell arrays cannot be passed through environment variables,
|
||
so you cannot set <varname>makeFlagsArray</varname> in a derivation
|
||
attribute (because those are passed through environment variables): you
|
||
have to define them in shell code.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>buildFlags</varname> / <varname>buildFlagsArray</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of strings passed as additional flags to <command>make</command>.
|
||
Like <varname>makeFlags</varname> and <varname>makeFlagsArray</varname>,
|
||
but only used by the build phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preBuild</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the start of the build phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postBuild</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the end of the build phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
You can set flags for <command>make</command> through the
|
||
<varname>makeFlags</varname> variable.
|
||
</para>
|
||
|
||
<para>
|
||
Before and after running <command>make</command>, the hooks
|
||
<varname>preBuild</varname> and <varname>postBuild</varname> are called,
|
||
respectively.
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="ssec-check-phase">
|
||
<title>The check phase</title>
|
||
|
||
<para>
|
||
The check phase checks whether the package was built correctly by running
|
||
its test suite. The default <function>checkPhase</function> calls
|
||
<command>make check</command>, but only if the <varname>doCheck</varname>
|
||
variable is enabled.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<title>Variables controlling the check phase</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>doCheck</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls whether the check phase is executed. By default it is skipped,
|
||
but if <varname>doCheck</varname> is set to true, the check phase is
|
||
usually executed. Thus you should set
|
||
<programlisting>doCheck = true;</programlisting>
|
||
in the derivation to enable checks. The exception is cross compilation.
|
||
Cross compiled builds never run tests, no matter how
|
||
<varname>doCheck</varname> is set, as the newly-built program won't run
|
||
on the platform used to build it.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>makeFlags</varname> / <varname>makeFlagsArray</varname> / <varname>makefile</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
See the build phase for details.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>checkTarget</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The make target that runs the tests. Defaults to
|
||
<literal>check</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>checkFlags</varname> / <varname>checkFlagsArray</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of strings passed as additional flags to <command>make</command>.
|
||
Like <varname>makeFlags</varname> and <varname>makeFlagsArray</varname>,
|
||
but only used by the check phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>checkInputs</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of dependencies used by the phase. This gets included in
|
||
<varname>nativeBuildInputs</varname> when <varname>doCheck</varname> is
|
||
set.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preCheck</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the start of the check phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postCheck</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the end of the check phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
|
||
<section xml:id="ssec-install-phase">
|
||
<title>The install phase</title>
|
||
|
||
<para>
|
||
The install phase is responsible for installing the package in the Nix
|
||
store under <envar>out</envar>. The default
|
||
<function>installPhase</function> creates the directory
|
||
<literal>$out</literal> and calls <command>make install</command>.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<title>Variables controlling the install phase</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>makeFlags</varname> / <varname>makeFlagsArray</varname> / <varname>makefile</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
See the build phase for details.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>installTargets</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The make targets that perform the installation. Defaults to
|
||
<literal>install</literal>. Example:
|
||
<programlisting>
|
||
installTargets = "install-bin install-doc";</programlisting>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>installFlags</varname> / <varname>installFlagsArray</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of strings passed as additional flags to <command>make</command>.
|
||
Like <varname>makeFlags</varname> and <varname>makeFlagsArray</varname>,
|
||
but only used by the install phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preInstall</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the start of the install phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postInstall</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the end of the install phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
|
||
<section xml:id="ssec-fixup-phase">
|
||
<title>The fixup phase</title>
|
||
|
||
<para>
|
||
The fixup phase performs some (Nix-specific) post-processing actions on the
|
||
files installed under <filename>$out</filename> by the install phase. The
|
||
default <function>fixupPhase</function> does the following:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
It moves the <filename>man/</filename>, <filename>doc/</filename> and
|
||
<filename>info/</filename> subdirectories of <envar>$out</envar> to
|
||
<filename>share/</filename>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
It strips libraries and executables of debug information.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
On Linux, it applies the <command>patchelf</command> command to ELF
|
||
executables and libraries to remove unused directories from the
|
||
<literal>RPATH</literal> in order to prevent unnecessary runtime
|
||
dependencies.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
It rewrites the interpreter paths of shell scripts to paths found in
|
||
<envar>PATH</envar>. E.g., <filename>/usr/bin/perl</filename> will be
|
||
rewritten to
|
||
<filename>/nix/store/<replaceable>some-perl</replaceable>/bin/perl</filename>
|
||
found in <envar>PATH</envar>.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<variablelist>
|
||
<title>Variables controlling the fixup phase</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontFixup</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Set to true to skip the fixup phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontStrip</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set, libraries and executables are not stripped. By default, they
|
||
are.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontStripHost</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Like <varname>dontStrip</varname>, but only affects the
|
||
<command>strip</command> command targetting the package's host platform.
|
||
Useful when supporting cross compilation, but otherwise feel free to
|
||
ignore.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontStripTarget</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Like <varname>dontStrip</varname>, but only affects the
|
||
<command>strip</command> command targetting the packages' target
|
||
platform. Useful when supporting cross compilation, but otherwise feel
|
||
free to ignore.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontMoveSbin</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set, files in <filename>$out/sbin</filename> are not moved to
|
||
<filename>$out/bin</filename>. By default, they are.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>stripAllList</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
List of directories to search for libraries and executables from which
|
||
<emphasis>all</emphasis> symbols should be stripped. By default, it’s
|
||
empty. Stripping all symbols is risky, since it may remove not just
|
||
debug symbols but also ELF information necessary for normal execution.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>stripAllFlags</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Flags passed to the <command>strip</command> command applied to the
|
||
files in the directories listed in <varname>stripAllList</varname>.
|
||
Defaults to <option>-s</option> (i.e. <option>--strip-all</option>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>stripDebugList</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
List of directories to search for libraries and executables from which
|
||
only debugging-related symbols should be stripped. It defaults to
|
||
<literal>lib bin sbin</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>stripDebugFlags</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Flags passed to the <command>strip</command> command applied to the
|
||
files in the directories listed in <varname>stripDebugList</varname>.
|
||
Defaults to <option>-S</option> (i.e. <option>--strip-debug</option>).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontPatchELF</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set, the <command>patchelf</command> command is not used to remove
|
||
unnecessary <literal>RPATH</literal> entries. Only applies to Linux.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontPatchShebangs</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set, scripts starting with <literal>#!</literal> do not have their
|
||
interpreter paths rewritten to paths in the Nix store.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontPruneLibtoolFiles</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set, libtool <literal>.la</literal> files associated with shared
|
||
libraries won't have their <literal>dependency_libs</literal> field
|
||
cleared.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>forceShare</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The list of directories that must be moved from
|
||
<filename>$out</filename> to <filename>$out/share</filename>. Defaults
|
||
to <literal>man doc info</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>setupHook</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A package can export a <link linkend="ssec-setup-hooks">setup
|
||
hook</link> by setting this variable. The setup hook, if defined, is
|
||
copied to <filename>$out/nix-support/setup-hook</filename>. Environment
|
||
variables are then substituted in it using
|
||
<function
|
||
linkend="fun-substituteAll">substituteAll</function>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preFixup</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the start of the fixup phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postFixup</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the end of the fixup phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry xml:id="stdenv-separateDebugInfo">
|
||
<term>
|
||
<varname>separateDebugInfo</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set to <literal>true</literal>, the standard environment will enable
|
||
debug information in C/C++ builds. After installation, the debug
|
||
information will be separated from the executables and stored in the
|
||
output named <literal>debug</literal>. (This output is enabled
|
||
automatically; you don’t need to set the <varname>outputs</varname>
|
||
attribute explicitly.) To be precise, the debug information is stored in
|
||
<filename><replaceable>debug</replaceable>/lib/debug/.build-id/<replaceable>XX</replaceable>/<replaceable>YYYY…</replaceable></filename>,
|
||
where <replaceable>XXYYYY…</replaceable> is the <replaceable>build
|
||
ID</replaceable> of the binary — a SHA-1 hash of the contents of the
|
||
binary. Debuggers like GDB use the build ID to look up the separated
|
||
debug information.
|
||
</para>
|
||
<para>
|
||
For example, with GDB, you can add
|
||
<programlisting>
|
||
set debug-file-directory ~/.nix-profile/lib/debug
|
||
</programlisting>
|
||
to <filename>~/.gdbinit</filename>. GDB will then be able to find debug
|
||
information installed via <literal>nix-env -i</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
|
||
<section xml:id="ssec-installCheck-phase">
|
||
<title>The installCheck phase</title>
|
||
|
||
<para>
|
||
The installCheck phase checks whether the package was installed correctly
|
||
by running its test suite against the installed directories. The default
|
||
<function>installCheck</function> calls <command>make
|
||
installcheck</command>.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<title>Variables controlling the installCheck phase</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>doInstallCheck</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Controls whether the installCheck phase is executed. By default it is
|
||
skipped, but if <varname>doInstallCheck</varname> is set to true, the
|
||
installCheck phase is usually executed. Thus you should set
|
||
<programlisting>doInstallCheck = true;</programlisting>
|
||
in the derivation to enable install checks. The exception is cross
|
||
compilation. Cross compiled builds never run tests, no matter how
|
||
<varname>doInstallCheck</varname> is set, as the newly-built program
|
||
won't run on the platform used to build it.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>installCheckTarget</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The make target that runs the install tests. Defaults to
|
||
<literal>installcheck</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>installCheckFlags</varname> / <varname>installCheckFlagsArray</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of strings passed as additional flags to <command>make</command>.
|
||
Like <varname>makeFlags</varname> and <varname>makeFlagsArray</varname>,
|
||
but only used by the installCheck phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>installCheckInputs</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A list of dependencies used by the phase. This gets included in
|
||
<varname>nativeBuildInputs</varname> when
|
||
<varname>doInstallCheck</varname> is set.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preInstallCheck</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the start of the installCheck phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postInstallCheck</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the end of the installCheck phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
|
||
<section xml:id="ssec-distribution-phase">
|
||
<title>The distribution phase</title>
|
||
|
||
<para>
|
||
The distribution phase is intended to produce a source distribution of the
|
||
package. The default <function>distPhase</function> first calls
|
||
<command>make dist</command>, then it copies the resulting source tarballs
|
||
to <filename>$out/tarballs/</filename>. This phase is only executed if the
|
||
attribute <varname>doDist</varname> is set.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<title>Variables controlling the distribution phase</title>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>distTarget</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The make target that produces the distribution. Defaults to
|
||
<literal>dist</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>distFlags</varname> / <varname>distFlagsArray</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Additional flags passed to <command>make</command>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>tarballs</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The names of the source distribution files to be copied to
|
||
<filename>$out/tarballs/</filename>. It can contain shell wildcards. The
|
||
default is <filename>*.tar.gz</filename>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>dontCopyDist</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
If set, no files are copied to <filename>$out/tarballs/</filename>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>preDist</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the start of the distribution phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>postDist</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Hook executed at the end of the distribution phase.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
</section>
|
||
<section xml:id="ssec-stdenv-functions">
|
||
<title>Shell functions</title>
|
||
|
||
<para>
|
||
The standard environment provides a number of useful functions.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry xml:id='fun-makeWrapper'>
|
||
<term>
|
||
<function>makeWrapper</function> <replaceable>executable</replaceable> <replaceable>wrapperfile</replaceable> <replaceable>args</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Constructs a wrapper for a program with various possible arguments. For
|
||
example:
|
||
<programlisting>
|
||
# adds `FOOBAR=baz` to `$out/bin/foo`’s environment
|
||
makeWrapper $out/bin/foo $wrapperfile --set FOOBAR baz
|
||
|
||
# prefixes the binary paths of `hello` and `git`
|
||
# Be advised that paths often should be patched in directly
|
||
# (via string replacements or in `configurePhase`).
|
||
makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello git ]}
|
||
</programlisting>
|
||
There’s many more kinds of arguments, they are documented in
|
||
<literal>nixpkgs/pkgs/build-support/setup-hooks/make-wrapper.sh</literal>.
|
||
</para>
|
||
<para>
|
||
<literal>wrapProgram</literal> is a convenience function you probably
|
||
want to use most of the time.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry xml:id='fun-substitute'>
|
||
<term>
|
||
<function>substitute</function> <replaceable>infile</replaceable> <replaceable>outfile</replaceable> <replaceable>subs</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Performs string substitution on the contents of
|
||
<replaceable>infile</replaceable>, writing the result to
|
||
<replaceable>outfile</replaceable>. The substitutions in
|
||
<replaceable>subs</replaceable> are of the following form:
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<option>--replace</option> <replaceable>s1</replaceable> <replaceable>s2</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Replace every occurrence of the string <replaceable>s1</replaceable>
|
||
by <replaceable>s2</replaceable>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>--subst-var</option> <replaceable>varName</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Replace every occurrence of
|
||
<literal>@<replaceable>varName</replaceable>@</literal> by the
|
||
contents of the environment variable
|
||
<replaceable>varName</replaceable>. This is useful for generating
|
||
files from templates, using
|
||
<literal>@<replaceable>...</replaceable>@</literal> in the template
|
||
as placeholders.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<option>--subst-var-by</option> <replaceable>varName</replaceable> <replaceable>s</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Replace every occurrence of
|
||
<literal>@<replaceable>varName</replaceable>@</literal> by the string
|
||
<replaceable>s</replaceable>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
<para>
|
||
Example:
|
||
<programlisting>
|
||
substitute ./foo.in ./foo.out \
|
||
--replace /usr/bin/bar $bar/bin/bar \
|
||
--replace "a string containing spaces" "some other text" \
|
||
--subst-var someVar
|
||
</programlisting>
|
||
</para>
|
||
<para>
|
||
<function>substitute</function> is implemented using the
|
||
<command
|
||
xlink:href="http://replace.richardlloyd.org.uk/">replace</command>
|
||
command. Unlike with the <command>sed</command> command, you don’t have
|
||
to worry about escaping special characters. It supports performing
|
||
substitutions on binary files (such as executables), though there
|
||
you’ll probably want to make sure that the replacement string is as
|
||
long as the replaced string.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry xml:id='fun-substituteInPlace'>
|
||
<term>
|
||
<function>substituteInPlace</function> <replaceable>file</replaceable> <replaceable>subs</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Like <function>substitute</function>, but performs the substitutions in
|
||
place on the file <replaceable>file</replaceable>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry xml:id='fun-substituteAll'>
|
||
<term>
|
||
<function>substituteAll</function> <replaceable>infile</replaceable> <replaceable>outfile</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Replaces every occurrence of
|
||
<literal>@<replaceable>varName</replaceable>@</literal>, where
|
||
<replaceable>varName</replaceable> is any environment variable, in
|
||
<replaceable>infile</replaceable>, writing the result to
|
||
<replaceable>outfile</replaceable>. For instance, if
|
||
<replaceable>infile</replaceable> has the contents
|
||
<programlisting>
|
||
#! @bash@/bin/sh
|
||
PATH=@coreutils@/bin
|
||
echo @foo@
|
||
</programlisting>
|
||
and the environment contains
|
||
<literal>bash=/nix/store/bmwp0q28cf21...-bash-3.2-p39</literal> and
|
||
<literal>coreutils=/nix/store/68afga4khv0w...-coreutils-6.12</literal>,
|
||
but does not contain the variable <varname>foo</varname>, then the output
|
||
will be
|
||
<programlisting>
|
||
#! /nix/store/bmwp0q28cf21...-bash-3.2-p39/bin/sh
|
||
PATH=/nix/store/68afga4khv0w...-coreutils-6.12/bin
|
||
echo @foo@
|
||
</programlisting>
|
||
That is, no substitution is performed for undefined variables.
|
||
</para>
|
||
<para>
|
||
Environment variables that start with an uppercase letter or an
|
||
underscore are filtered out, to prevent global variables (like
|
||
<literal>HOME</literal>) or private variables (like
|
||
<literal>__ETC_PROFILE_DONE</literal>) from accidentally getting
|
||
substituted. The variables also have to be valid bash “names”, as
|
||
defined in the bash manpage (alphanumeric or <literal>_</literal>, must
|
||
not start with a number).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry xml:id='fun-substituteAllInPlace'>
|
||
<term>
|
||
<function>substituteAllInPlace</function> <replaceable>file</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Like <function>substituteAll</function>, but performs the substitutions
|
||
in place on the file <replaceable>file</replaceable>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry xml:id='fun-stripHash'>
|
||
<term>
|
||
<function>stripHash</function> <replaceable>path</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Strips the directory and hash part of a store path, outputting the name
|
||
part to <literal>stdout</literal>. For example:
|
||
<programlisting>
|
||
# prints coreutils-8.24
|
||
stripHash "/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24"
|
||
</programlisting>
|
||
If you wish to store the result in another variable, then the following
|
||
idiom may be useful:
|
||
<programlisting>
|
||
name="/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24"
|
||
someVar=$(stripHash $name)
|
||
</programlisting>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry xml:id='fun-wrapProgram'>
|
||
<term>
|
||
<function>wrapProgram</function> <replaceable>executable</replaceable> <replaceable>makeWrapperArgs</replaceable>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Convenience function for <literal>makeWrapper</literal> that
|
||
automatically creates a sane wrapper file It takes all the same arguments
|
||
as <literal>makeWrapper</literal>, except for <literal>--argv0</literal>.
|
||
</para>
|
||
<para>
|
||
It cannot be applied multiple times, since it will overwrite the wrapper
|
||
file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
<section xml:id="ssec-setup-hooks">
|
||
<title>Package setup hooks</title>
|
||
|
||
<para>
|
||
Nix itself considers a build-time dependency as merely something that should
|
||
previously be built and accessible at build time—packages themselves are
|
||
on their own to perform any additional setup. In most cases, that is fine,
|
||
and the downstream derivation can deal with its own dependencies. But for a
|
||
few common tasks, that would result in almost every package doing the same
|
||
sort of setup work—depending not on the package itself, but entirely on
|
||
which dependencies were used.
|
||
</para>
|
||
|
||
<para>
|
||
In order to alleviate this burden, the <firstterm>setup hook</firstterm>
|
||
mechanism was written, where any package can include a shell script that [by
|
||
convention rather than enforcement by Nix], any downstream
|
||
reverse-dependency will source as part of its build process. That allows the
|
||
downstream dependency to merely specify its dependencies, and lets those
|
||
dependencies effectively initialize themselves. No boilerplate mirroring the
|
||
list of dependencies is needed.
|
||
</para>
|
||
|
||
<para>
|
||
The setup hook mechanism is a bit of a sledgehammer though: a powerful
|
||
feature with a broad and indiscriminate area of effect. The combination of
|
||
its power and implicit use may be expedient, but isn't without costs. Nix
|
||
itself is unchanged, but the spirit of added dependencies being effect-free
|
||
is violated even if the letter isn't. For example, if a derivation path is
|
||
mentioned more than once, Nix itself doesn't care and simply makes sure the
|
||
dependency derivation is already built just the same—depending is just
|
||
needing something to exist, and needing is idempotent. However, a dependency
|
||
specified twice will have its setup hook run twice, and that could easily
|
||
change the build environment (though a well-written setup hook will
|
||
therefore strive to be idempotent so this is in fact not observable). More
|
||
broadly, setup hooks are anti-modular in that multiple dependencies, whether
|
||
the same or different, should not interfere and yet their setup hooks may
|
||
well do so.
|
||
</para>
|
||
|
||
<para>
|
||
The most typical use of the setup hook is actually to add other hooks which
|
||
are then run (i.e. after all the setup hooks) on each dependency. For
|
||
example, the C compiler wrapper's setup hook feeds itself flags for each
|
||
dependency that contains relevant libraries and headers. This is done by
|
||
defining a bash function, and appending its name to one of
|
||
<envar>envBuildBuildHooks</envar>`, <envar>envBuildHostHooks</envar>`,
|
||
<envar>envBuildTargetHooks</envar>`, <envar>envHostHostHooks</envar>`,
|
||
<envar>envHostTargetHooks</envar>`, or <envar>envTargetTargetHooks</envar>`.
|
||
These 6 bash variables correspond to the 6 sorts of dependencies by platform
|
||
(there's 12 total but we ignore the propagated/non-propagated axis).
|
||
</para>
|
||
|
||
<para>
|
||
Packages adding a hook should not hard code a specific hook, but rather
|
||
choose a variable <emphasis>relative</emphasis> to how they are included.
|
||
Returning to the C compiler wrapper example, if the wrapper itself is an
|
||
<literal>n</literal> dependency, then it only wants to accumulate flags from
|
||
<literal>n + 1</literal> dependencies, as only those ones match the
|
||
compiler's target platform. The <envar>hostOffset</envar> variable is
|
||
defined with the current dependency's host offset
|
||
<envar>targetOffset</envar> with its target offset, before its setup hook is
|
||
sourced. Additionally, since most environment hooks don't care about the
|
||
target platform, that means the setup hook can append to the right bash
|
||
array by doing something like
|
||
<programlisting language="bash">
|
||
addEnvHooks "$hostOffset" myBashFunction
|
||
</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
The <emphasis>existence</emphasis> of setups hooks has long been documented
|
||
and packages inside Nixpkgs are free to use this mechanism. Other packages,
|
||
however, should not rely on these mechanisms not changing between Nixpkgs
|
||
versions. Because of the existing issues with this system, there's little
|
||
benefit from mandating it be stable for any period of time.
|
||
</para>
|
||
|
||
<para>
|
||
First, let’s cover some setup hooks that are part of Nixpkgs default
|
||
stdenv. This means that they are run for every package built using
|
||
<function>stdenv.mkDerivation</function>. Some of these are platform
|
||
specific, so they may run on Linux but not Darwin or vice-versa.
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>move-docs.sh</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This setup hook moves any installed documentation to the
|
||
<literal>/share</literal> subdirectory directory. This includes the man,
|
||
doc and info directories. This is needed for legacy programs that do not
|
||
know how to use the <literal>share</literal> subdirectory.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>compress-man-pages.sh</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This setup hook compresses any man pages that have been installed. The
|
||
compression is done using the gzip program. This helps to reduce the
|
||
installed size of packages.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>strip.sh</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This runs the strip command on installed binaries and libraries. This
|
||
removes unnecessary information like debug symbols when they are not
|
||
needed. This also helps to reduce the installed size of packages.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>patch-shebangs.sh</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This setup hook patches installed scripts to use the full path to the
|
||
shebang interpreter. A shebang interpreter is the first commented line
|
||
of a script telling the operating system which program will run the
|
||
script (e.g <literal>#!/bin/bash</literal>). In Nix, we want an exact
|
||
path to that interpreter to be used. This often replaces
|
||
<literal>/bin/sh</literal> with a path in the Nix store.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>audit-tmpdir.sh</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This verifies that no references are left from the install binaries to
|
||
the directory used to build those binaries. This ensures that the
|
||
binaries do not need things outside the Nix store. This is currently
|
||
supported in Linux only.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>multiple-outputs.sh</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This setup hook adds configure flags that tell packages to install files
|
||
into any one of the proper outputs listed in <literal>outputs</literal>.
|
||
This behavior can be turned off by setting
|
||
<literal>setOutputFlags</literal> to false in the derivation
|
||
environment. See <xref linkend="chap-multiple-output"/> for more
|
||
information.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>move-sbin.sh</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This setup hook moves any binaries installed in the sbin subdirectory
|
||
into bin. In addition, a link is provided from sbin to bin for
|
||
compatibility.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>move-lib64.sh</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This setup hook moves any libraries installed in the lib64 subdirectory
|
||
into lib. In addition, a link is provided from lib64 to lib for
|
||
compatibility.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<literal>set-source-date-epoch-to-latest.sh</literal>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This sets <literal>SOURCE_DATE_EPOCH</literal> to the modification time
|
||
of the most recent file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
Bintools Wrapper
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The Bintools Wrapper wraps the binary utilities for a bunch of
|
||
miscellaneous purposes. These are GNU Binutils when targetting Linux,
|
||
and a mix of cctools and GNU binutils for Darwin. [The "Bintools" name
|
||
is supposed to be a compromise between "Binutils" and "cctools" not
|
||
denoting any specific implementation.] Specifically, the underlying
|
||
bintools package, and a C standard library (glibc or Darwin's libSystem,
|
||
just for the dynamic loader) are all fed in, and dependency finding,
|
||
hardening (see below), and purity checks for each are handled by the
|
||
Bintools Wrapper. Packages typically depend on CC Wrapper, which in turn
|
||
(at run time) depends on the Bintools Wrapper.
|
||
</para>
|
||
<para>
|
||
The Bintools Wrapper was only just recently split off from CC Wrapper,
|
||
so the division of labor is still being worked out. For example, it
|
||
shouldn't care about about the C standard library, but just take a
|
||
derivation with the dynamic loader (which happens to be the glibc on
|
||
linux). Dependency finding however is a task both wrappers will continue
|
||
to need to share, and probably the most important to understand. It is
|
||
currently accomplished by collecting directories of host-platform
|
||
dependencies (i.e. <varname>buildInputs</varname> and
|
||
<varname>nativeBuildInputs</varname>) in environment variables. The
|
||
Bintools Wrapper's setup hook causes any <filename>lib</filename> and
|
||
<filename>lib64</filename> subdirectories to be added to
|
||
<envar>NIX_LDFLAGS</envar>. Since the CC Wrapper and the Bintools
|
||
Wrapper use the same strategy, most of the Bintools Wrapper code is
|
||
sparsely commented and refers to the CC Wrapper. But the CC Wrapper's
|
||
code, by contrast, has quite lengthy comments. The Bintools Wrapper
|
||
merely cites those, rather than repeating them, to avoid falling out of
|
||
sync.
|
||
</para>
|
||
<para>
|
||
A final task of the setup hook is defining a number of standard
|
||
environment variables to tell build systems which executables fulfill
|
||
which purpose. They are defined to just be the base name of the tools,
|
||
under the assumption that the Bintools Wrapper's binaries will be on the
|
||
path. Firstly, this helps poorly-written packages, e.g. ones that look
|
||
for just <command>gcc</command> when <envar>CC</envar> isn't defined yet
|
||
<command>clang</command> is to be used. Secondly, this helps packages
|
||
not get confused when cross-compiling, in which case multiple Bintools
|
||
Wrappers may simultaneously be in use.
|
||
<footnote xml:id="footnote-stdenv-per-platform-wrapper">
|
||
<para>
|
||
Each wrapper targets a single platform, so if binaries for multiple
|
||
platforms are needed, the underlying binaries must be wrapped multiple
|
||
times. As this is a property of the wrapper itself, the multiple
|
||
wrappings are needed whether or not the same underlying binaries can
|
||
target multiple platforms.
|
||
</para>
|
||
</footnote>
|
||
<envar>BUILD_</envar>- and <envar>TARGET_</envar>-prefixed versions of
|
||
the normal environment variable are defined for additional Bintools
|
||
Wrappers, properly disambiguating them.
|
||
</para>
|
||
<para>
|
||
A problem with this final task is that the Bintools Wrapper is honest
|
||
and defines <envar>LD</envar> as <command>ld</command>. Most packages,
|
||
however, firstly use the C compiler for linking, secondly use
|
||
<envar>LD</envar> anyways, defining it as the C compiler, and thirdly,
|
||
only so define <envar>LD</envar> when it is undefined as a fallback.
|
||
This triple-threat means Bintools Wrapper will break those packages, as
|
||
LD is already defined as the actual linker which the package won't
|
||
override yet doesn't want to use. The workaround is to define, just for
|
||
the problematic package, <envar>LD</envar> as the C compiler. A good way
|
||
to do this would be <command>preConfigure = "LD=$CC"</command>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
CC Wrapper
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The CC Wrapper wraps a C toolchain for a bunch of miscellaneous
|
||
purposes. Specifically, a C compiler (GCC or Clang), wrapped binary
|
||
tools, and a C standard library (glibc or Darwin's libSystem, just for
|
||
the dynamic loader) are all fed in, and dependency finding, hardening
|
||
(see below), and purity checks for each are handled by the CC Wrapper.
|
||
Packages typically depend on the CC Wrapper, which in turn (at run-time)
|
||
depends on the Bintools Wrapper.
|
||
</para>
|
||
<para>
|
||
Dependency finding is undoubtedly the main task of the CC Wrapper. This
|
||
works just like the Bintools Wrapper, except that any
|
||
<filename>include</filename> subdirectory of any relevant dependency is
|
||
added to <envar>NIX_CFLAGS_COMPILE</envar>. The setup hook itself
|
||
contains some lengthy comments describing the exact convoluted mechanism
|
||
by which this is accomplished.
|
||
</para>
|
||
<para>
|
||
Similarly, the CC Wrapper follows the Bintools Wrapper in defining
|
||
standard environment variables with the names of the tools it wraps, for
|
||
the same reasons described above. Importantly, while it includes a
|
||
<command>cc</command> symlink to the c compiler for portability, the
|
||
<envar>CC</envar> will be defined using the compiler's "real name" (i.e.
|
||
<command>gcc</command> or <command>clang</command>). This helps lousy
|
||
build systems that inspect on the name of the compiler rather than run
|
||
it.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
|
||
<para>
|
||
Here are some more packages that provide a setup hook. Since the list of
|
||
hooks is extensible, this is not an exhaustive list the mechanism is only to
|
||
be used as a last resort, it might cover most uses.
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
Perl
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <filename>lib/site_perl</filename> subdirectory of each build
|
||
input to the <envar>PERL5LIB</envar> environment variable. For instance,
|
||
if <varname>buildInputs</varname> contains Perl, then the
|
||
<filename>lib/site_perl</filename> subdirectory of each input is added
|
||
to the <envar>PERL5LIB</envar> environment variable.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
Python
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <filename>lib/${python.libPrefix}/site-packages</filename>
|
||
subdirectory of each build input to the <envar>PYTHONPATH</envar>
|
||
environment variable.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
pkg-config
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <filename>lib/pkgconfig</filename> and
|
||
<filename>share/pkgconfig</filename> subdirectories of each build input
|
||
to the <envar>PKG_CONFIG_PATH</envar> environment variable.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
Automake
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <filename>share/aclocal</filename> subdirectory of each build
|
||
input to the <envar>ACLOCAL_PATH</envar> environment variable.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
Autoconf
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
The <varname>autoreconfHook</varname> derivation adds
|
||
<varname>autoreconfPhase</varname>, which runs autoreconf, libtoolize
|
||
and automake, essentially preparing the configure script in
|
||
autotools-based builds. Most autotools-based packages come with the
|
||
configure script pre-generated, but this hook is necessary for a few
|
||
packages and when you need to patch the package’s configure scripts.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
libxml2
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds every file named <filename>catalog.xml</filename> found under the
|
||
<filename>xml/dtd</filename> and <filename>xml/xsl</filename>
|
||
subdirectories of each build input to the
|
||
<envar>XML_CATALOG_FILES</envar> environment variable.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
teTeX / TeX Live
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <filename>share/texmf-nix</filename> subdirectory of each build
|
||
input to the <envar>TEXINPUTS</envar> environment variable.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
Qt 4
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the <envar>QTDIR</envar> environment variable to Qt’s path.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
gdk-pixbuf
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Exports <envar>GDK_PIXBUF_MODULE_FILE</envar> environment variable to
|
||
the builder. Add librsvg package to <varname>buildInputs</varname> to
|
||
get svg support.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
GHC
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Creates a temporary package database and registers every Haskell build
|
||
input in it (TODO: how?).
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
GStreamer
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the GStreamer plugins subdirectory of each build input to the
|
||
<envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> or
|
||
<envar>GST_PLUGIN_SYSTEM_PATH</envar> environment variable.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
autoPatchelfHook
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This is a special setup hook which helps in packaging proprietary
|
||
software in that it automatically tries to find missing shared library
|
||
dependencies of ELF files based on the given
|
||
<varname>buildInputs</varname> and <varname>nativeBuildInputs</varname>.
|
||
</para>
|
||
<para>
|
||
You can also specify a <envar>runtimeDependencies</envar> environment
|
||
variable which lists dependencies that are unconditionally added to all
|
||
executables.
|
||
</para>
|
||
<para>
|
||
This is useful for programs that use <citerefentry>
|
||
<refentrytitle>dlopen</refentrytitle>
|
||
<manvolnum>3</manvolnum> </citerefentry> to load libraries at runtime.
|
||
</para>
|
||
<para>
|
||
In certain situations you may want to run the main command
|
||
(<command>autoPatchelf</command>) of the setup hook on a file or a set
|
||
of directories instead of unconditionally patching all outputs. This can
|
||
be done by setting the <envar>dontAutoPatchelf</envar> environment
|
||
variable to a non-empty value.
|
||
</para>
|
||
<para>
|
||
The <command>autoPatchelf</command> command also recognizes a
|
||
<parameter class="command">--no-recurse</parameter> command line flag,
|
||
which prevents it from recursing into subdirectories.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
breakpointHook
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This hook will make a build pause instead of stopping when a failure
|
||
happens. It prevents nix from cleaning up the build environment
|
||
immediately and allows the user to attach to a build environment using
|
||
the <command>cntr</command> command. Upon build error it will print
|
||
instructions on how to use <command>cntr</command>, which can be used to
|
||
enter the environment for debugging. Installing cntr and running the
|
||
command will provide shell access to the build sandbox of failed build.
|
||
At <filename>/var/lib/cntr</filename> the sandboxed filesystem is
|
||
mounted. All commands and files of the system are still accessible
|
||
within the shell. To execute commands from the sandbox use the cntr exec
|
||
subcommand. <command>cntr</command> is only supported
|
||
on Linux-based platforms. To use it first add <literal>cntr</literal> to
|
||
your <literal>environment.systemPackages</literal> on NixOS or
|
||
alternatively to the root user on non-NixOS systems. Then in the package
|
||
that is supposed to be inspected, add <literal>breakpointHook</literal>
|
||
to <literal>nativeBuildInputs</literal>.
|
||
<programlisting>
|
||
nativeBuildInputs = [ breakpointHook ];
|
||
</programlisting>
|
||
When a build failure happens there will be an instruction printed that
|
||
shows how to attach with <literal>cntr</literal> to the build sandbox.
|
||
</para>
|
||
<note>
|
||
<title>Caution with remote builds</title>
|
||
<para>
|
||
This won't work with remote builds as the build environment is on
|
||
a different machine and can't be accessed by <command>cntr</command>.
|
||
Remote builds can be turned off by setting <literal>--option builders ''</literal>
|
||
for <command>nix-build</command> or <literal>--builders ''</literal> for
|
||
<command>nix build</command>.
|
||
</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
installShellFiles
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This hook helps with installing manpages and shell completion files. It
|
||
exposes 2 shell functions <literal>installManPage</literal> and
|
||
<literal>installShellCompletion</literal> that can be used from your
|
||
<literal>postInstall</literal> hook.
|
||
</para>
|
||
<para>
|
||
The <literal>installManPage</literal> function takes one or more paths
|
||
to manpages to install. The manpages must have a section suffix, and may
|
||
optionally be compressed (with <literal>.gz</literal> suffix). This
|
||
function will place them into the correct directory.
|
||
</para>
|
||
<para>
|
||
The <literal>installShellCompletion</literal> function takes one or more
|
||
paths to shell completion files. By default it will autodetect the shell
|
||
type from the completion file extension, but you may also specify it by
|
||
passing one of <literal>--bash</literal>, <literal>--fish</literal>, or
|
||
<literal>--zsh</literal>. These flags apply to all paths listed after
|
||
them (up until another shell flag is given). Each path may also have a
|
||
custom installation name provided by providing a flag <literal>--name
|
||
NAME</literal> before the path. If this flag is not provided, zsh
|
||
completions will be renamed automatically such that
|
||
<literal>foobar.zsh</literal> becomes <literal>_foobar</literal>.
|
||
<programlisting>
|
||
nativeBuildInputs = [ installShellFiles ];
|
||
postInstall = ''
|
||
installManPage doc/foobar.1 doc/barfoo.3
|
||
# explicit behavior
|
||
installShellCompletion --bash --name foobar.bash share/completions.bash
|
||
installShellCompletion --fish --name foobar.fish share/completions.fish
|
||
installShellCompletion --zsh --name _foobar share/completions.zsh
|
||
# implicit behavior
|
||
installShellCompletion share/completions/foobar.{bash,fish,zsh}
|
||
'';
|
||
</programlisting>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
libiconv, libintl
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
A few libraries automatically add to <literal>NIX_LDFLAGS</literal>
|
||
their library, making their symbols automatically available to the
|
||
linker. This includes libiconv and libintl (gettext). This is done to
|
||
provide compatibility between GNU Linux, where libiconv and libintl are
|
||
bundled in, and other systems where that might not be the case.
|
||
Sometimes, this behavior is not desired. To disable this behavior, set
|
||
<literal>dontAddExtraLibs</literal>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
cmake
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Overrides the default configure phase to run the CMake command. By
|
||
default, we use the Make generator of CMake. In addition, dependencies
|
||
are added automatically to CMAKE_PREFIX_PATH so that packages are
|
||
correctly detected by CMake. Some additional flags are passed in to give
|
||
similar behavior to configure-based packages. You can disable this
|
||
hook’s behavior by setting configurePhase to a custom value, or by
|
||
setting dontUseCmakeConfigure. cmakeFlags controls flags passed only to
|
||
CMake. By default, parallel building is enabled as CMake supports
|
||
parallel building almost everywhere. When Ninja is also in use, CMake
|
||
will detect that and use the ninja generator.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
xcbuildHook
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Overrides the build and install phases to run the “xcbuild” command.
|
||
This hook is needed when a project only comes with build files for the
|
||
XCode build system. You can disable this behavior by setting buildPhase
|
||
and configurePhase to a custom value. xcbuildFlags controls flags passed
|
||
only to xcbuild.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
meson
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Overrides the configure phase to run meson to generate Ninja files. You
|
||
can disable this behavior by setting configurePhase to a custom value,
|
||
or by setting dontUseMesonConfigure. To run these files, you should
|
||
accompany meson with ninja. mesonFlags controls only the flags passed to
|
||
meson. By default, parallel building is enabled as Meson supports
|
||
parallel building almost everywhere.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
ninja
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Overrides the build, install, and check phase to run ninja instead of
|
||
make. You can disable this behavior with the dontUseNinjaBuild,
|
||
dontUseNinjaInstall, and dontUseNinjaCheck, respectively. Parallel
|
||
building is enabled by default in Ninja.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
unzip
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This setup hook will allow you to unzip .zip files specified in $src.
|
||
There are many similar packages like unrar, undmg, etc.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
wafHook
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Overrides the configure, build, and install phases. This will run the
|
||
"waf" script used by many projects. If wafPath (default ./waf) doesn’t
|
||
exist, it will copy the version of waf available in Nixpkgs. wafFlags can
|
||
be used to pass flags to the waf script.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
scons
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Overrides the build, install, and check phases. This uses the scons
|
||
build system as a replacement for make. scons does not provide a
|
||
configure phase, so everything is managed at build and install time.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</section>
|
||
<section xml:id="sec-purity-in-nixpkgs">
|
||
<title>Purity in Nixpkgs</title>
|
||
|
||
<para>
|
||
[measures taken to prevent dependencies on packages outside the store, and
|
||
what you can do to prevent them]
|
||
</para>
|
||
|
||
<para>
|
||
GCC doesn't search in locations such as <filename>/usr/include</filename>.
|
||
In fact, attempts to add such directories through the <option>-I</option>
|
||
flag are filtered out. Likewise, the linker (from GNU binutils) doesn't
|
||
search in standard locations such as <filename>/usr/lib</filename>. Programs
|
||
built on Linux are linked against a GNU C Library that likewise doesn't
|
||
search in the default system locations.
|
||
</para>
|
||
</section>
|
||
<section xml:id="sec-hardening-in-nixpkgs">
|
||
<title>Hardening in Nixpkgs</title>
|
||
|
||
<para>
|
||
There are flags available to harden packages at compile or link-time. These
|
||
can be toggled using the <varname>stdenv.mkDerivation</varname> parameters
|
||
<varname>hardeningDisable</varname> and <varname>hardeningEnable</varname>.
|
||
</para>
|
||
|
||
<para>
|
||
Both parameters take a list of flags as strings. The special
|
||
<varname>"all"</varname> flag can be passed to
|
||
<varname>hardeningDisable</varname> to turn off all hardening. These flags
|
||
can also be used as environment variables for testing or development
|
||
purposes.
|
||
</para>
|
||
|
||
<para>
|
||
The following flags are enabled by default and might require disabling with
|
||
<varname>hardeningDisable</varname> if the program to package is
|
||
incompatible.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>format</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <option>-Wformat -Wformat-security
|
||
-Werror=format-security</option> compiler options. At present, this warns
|
||
about calls to <varname>printf</varname> and <varname>scanf</varname>
|
||
functions where the format string is not a string literal and there are
|
||
no format arguments, as in <literal>printf(foo);</literal>. This may be a
|
||
security hole if the format string came from untrusted input and contains
|
||
<literal>%n</literal>.
|
||
</para>
|
||
<para>
|
||
This needs to be turned off or fixed for errors similar to:
|
||
</para>
|
||
<programlisting>
|
||
/tmp/nix-build-zynaddsubfx-2.5.2.drv-0/zynaddsubfx-2.5.2/src/UI/guimain.cpp:571:28: error: format not a string literal and no format arguments [-Werror=format-security]
|
||
printf(help_message);
|
||
^
|
||
cc1plus: some warnings being treated as errors
|
||
</programlisting>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>stackprotector</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <option>-fstack-protector-strong --param
|
||
ssp-buffer-size=4</option> compiler options. This adds safety checks
|
||
against stack overwrites rendering many potential code injection attacks
|
||
into aborting situations. In the best case this turns code injection
|
||
vulnerabilities into denial of service or into non-issues (depending on
|
||
the application).
|
||
</para>
|
||
<para>
|
||
This needs to be turned off or fixed for errors similar to:
|
||
</para>
|
||
<programlisting>
|
||
bin/blib.a(bios_console.o): In function `bios_handle_cup':
|
||
/tmp/nix-build-ipxe-20141124-5cbdc41.drv-0/ipxe-5cbdc41/src/arch/i386/firmware/pcbios/bios_console.c:86: undefined reference to `__stack_chk_fail'
|
||
</programlisting>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>fortify</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <option>-O2 -D_FORTIFY_SOURCE=2</option> compiler options.
|
||
During code generation the compiler knows a great deal of information
|
||
about buffer sizes (where possible), and attempts to replace insecure
|
||
unlimited length buffer function calls with length-limited ones. This is
|
||
especially useful for old, crufty code. Additionally, format strings in
|
||
writable memory that contain '%n' are blocked. If an application depends
|
||
on such a format string, it will need to be worked around.
|
||
</para>
|
||
<para>
|
||
Additionally, some warnings are enabled which might trigger build
|
||
failures if compiler warnings are treated as errors in the package build.
|
||
In this case, set <option>NIX_CFLAGS_COMPILE</option> to
|
||
<option>-Wno-error=warning-type</option>.
|
||
</para>
|
||
<para>
|
||
This needs to be turned off or fixed for errors similar to:
|
||
</para>
|
||
<programlisting>
|
||
malloc.c:404:15: error: return type is an incomplete type
|
||
malloc.c:410:19: error: storage size of 'ms' isn't known
|
||
</programlisting>
|
||
<programlisting>
|
||
strdup.h:22:1: error: expected identifier or '(' before '__extension__'
|
||
</programlisting>
|
||
<programlisting>
|
||
strsep.c:65:23: error: register name not specified for 'delim'
|
||
</programlisting>
|
||
<programlisting>
|
||
installwatch.c:3751:5: error: conflicting types for '__open_2'
|
||
</programlisting>
|
||
<programlisting>
|
||
fcntl2.h:50:4: error: call to '__open_missing_mode' declared with attribute error: open with O_CREAT or O_TMPFILE in second argument needs 3 arguments
|
||
</programlisting>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>pic</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <option>-fPIC</option> compiler options. This options adds
|
||
support for position independent code in shared libraries and thus making
|
||
ASLR possible.
|
||
</para>
|
||
<para>
|
||
Most notably, the Linux kernel, kernel modules and other code not running
|
||
in an operating system environment like boot loaders won't build with PIC
|
||
enabled. The compiler will is most cases complain that PIC is not
|
||
supported for a specific build.
|
||
</para>
|
||
<para>
|
||
This needs to be turned off or fixed for assembler errors similar to:
|
||
</para>
|
||
<programlisting>
|
||
ccbLfRgg.s: Assembler messages:
|
||
ccbLfRgg.s:33: Error: missing or invalid displacement expression `private_key_len@GOTOFF'
|
||
</programlisting>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>strictoverflow</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Signed integer overflow is undefined behaviour according to the C
|
||
standard. If it happens, it is an error in the program as it should check
|
||
for overflow before it can happen, not afterwards. GCC provides built-in
|
||
functions to perform arithmetic with overflow checking, which are correct
|
||
and faster than any custom implementation. As a workaround, the option
|
||
<option>-fno-strict-overflow</option> makes gcc behave as if signed
|
||
integer overflows were defined.
|
||
</para>
|
||
<para>
|
||
This flag should not trigger any build or runtime errors.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>relro</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <option>-z relro</option> linker option. During program load,
|
||
several ELF memory sections need to be written to by the linker, but can
|
||
be turned read-only before turning over control to the program. This
|
||
prevents some GOT (and .dtors) overwrite attacks, but at least the part
|
||
of the GOT used by the dynamic linker (.got.plt) is still vulnerable.
|
||
</para>
|
||
<para>
|
||
This flag can break dynamic shared object loading. For instance, the
|
||
module systems of Xorg and OpenCV are incompatible with this flag. In
|
||
almost all cases the <varname>bindnow</varname> flag must also be
|
||
disabled and incompatible programs typically fail with similar errors at
|
||
runtime.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>bindnow</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <option>-z bindnow</option> linker option. During program load,
|
||
all dynamic symbols are resolved, allowing for the complete GOT to be
|
||
marked read-only (due to <varname>relro</varname>). This prevents GOT
|
||
overwrite attacks. For very large applications, this can incur some
|
||
performance loss during initial load while symbols are resolved, but this
|
||
shouldn't be an issue for daemons.
|
||
</para>
|
||
<para>
|
||
This flag can break dynamic shared object loading. For instance, the
|
||
module systems of Xorg and PHP are incompatible with this flag. Programs
|
||
incompatible with this flag often fail at runtime due to missing symbols,
|
||
like:
|
||
</para>
|
||
<programlisting>
|
||
intel_drv.so: undefined symbol: vgaHWFreeHWRec
|
||
</programlisting>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The following flags are disabled by default and should be enabled with
|
||
<varname>hardeningEnable</varname> for packages that take untrusted input
|
||
like network services.
|
||
</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<varname>pie</varname>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Adds the <option>-fPIE</option> compiler and <option>-pie</option> linker
|
||
options. Position Independent Executables are needed to take advantage of
|
||
Address Space Layout Randomization, supported by modern kernel versions.
|
||
While ASLR can already be enforced for data areas in the stack and heap
|
||
(brk and mmap), the code areas must be compiled as position-independent.
|
||
Shared libraries already do this with the <varname>pic</varname> flag, so
|
||
they gain ASLR automatically, but binary .text regions need to be build
|
||
with <varname>pie</varname> to gain ASLR. When this happens, ROP attacks
|
||
are much harder since there are no static locations to bounce off of
|
||
during a memory corruption attack.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
For more in-depth information on these hardening flags and hardening in
|
||
general, refer to the
|
||
<link xlink:href="https://wiki.debian.org/Hardening">Debian Wiki</link>,
|
||
<link xlink:href="https://wiki.ubuntu.com/Security/Features">Ubuntu
|
||
Wiki</link>,
|
||
<link xlink:href="https://wiki.gentoo.org/wiki/Project:Hardened">Gentoo
|
||
Wiki</link>, and the
|
||
<link xlink:href="https://wiki.archlinux.org/index.php/DeveloperWiki:Security">
|
||
Arch Wiki</link>.
|
||
</para>
|
||
</section>
|
||
</chapter>
|