mirror of
https://github.com/NixOS/nix.git
synced 2025-11-26 20:20:58 +01:00
This commit is contained in:
Wouter den Breejen
parent
1164d6a389
commit
4e11da960c
11 changed files with 536 additions and 61 deletions
|
|
@ -47,6 +47,14 @@ manual.html: $(MANUAL_SRCS) manual.is-valid images
|
|||
$(XSLTPROC) --nonet --xinclude --output manual.html \
|
||||
$(docbookxsl)/html/docbook.xsl manual.xml
|
||||
|
||||
manual.pdf: $(MANUAL_SRCS) manual.is-valid images
|
||||
if test "$(dblatex)" != ""; then \
|
||||
$(dblatex) manual.xml; \
|
||||
else \
|
||||
echo "Please install dblatex and rerun configure."; \
|
||||
exit 1; \
|
||||
fi
|
||||
|
||||
|
||||
NEWS_OPTS = \
|
||||
--stringparam generate.toc "article nop" \
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ functions and values. For instance, <function>derivation</function>
|
|||
is also available as <function>builtins.derivation</function>.</para>
|
||||
|
||||
|
||||
<variablelist >
|
||||
<variablelist>
|
||||
|
||||
|
||||
<varlistentry><term><function>abort</function> <replaceable>s</replaceable></term>
|
||||
|
|
|
|||
|
|
@ -263,6 +263,17 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
|
|||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term>
|
||||
|
||||
<listitem><para>This variable should be set to
|
||||
<literal>daemon</literal> if you want to use the Nix daemon to
|
||||
executed Nix operations, which is necessary in <link
|
||||
linkend="ssec-multi-user">multi-user Nix installations</link>.
|
||||
Otherwise, it should be left unset.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
|
||||
</variablelist>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -100,14 +100,16 @@ ubiquitous 2.5.4a won't. Note that these are only required if you
|
|||
modify the parser or when you are building from the Subversion
|
||||
repository.</para>
|
||||
|
||||
<para>Nix uses Sleepycat's Berkeley DB and CWI's ATerm library. These
|
||||
are included in the Nix source distribution. If you build from the
|
||||
Subversion repository, you must download them yourself and place them
|
||||
in the <filename>externals/</filename> directory. See
|
||||
<para>Nix uses Sleepycat's Berkeley DB, CWI's ATerm library and the
|
||||
bzip2 compressor (including the bzip2 library). These are included in
|
||||
the Nix source distribution. If you build from the Subversion
|
||||
repository, you must download them yourself and place them in the
|
||||
<filename>externals/</filename> directory. See
|
||||
<filename>externals/Makefile.am</filename> for the precise URLs of
|
||||
these packages. Alternatively, if you already have them installed,
|
||||
you can use <command>configure</command>'s <option>--with-bdb</option>
|
||||
and <option>--with-aterm</option> options to point to their respective
|
||||
you can use <command>configure</command>'s
|
||||
<option>--with-bdb</option>, <option>--with-aterm</option> and
|
||||
<option>--with-bzip2</option> options to point to their respective
|
||||
locations. Note that Berkeley DB <emphasis>must</emphasis> be version
|
||||
4.5; other versions may not have compatible database formats.</para>
|
||||
|
||||
|
|
@ -118,19 +120,21 @@ locations. Note that Berkeley DB <emphasis>must</emphasis> be version
|
|||
|
||||
<para>After unpacking or checking out the Nix sources, issue the
|
||||
following commands:
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
$ ./configure <replaceable>options...</replaceable>
|
||||
$ make
|
||||
$ make install</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>When building from the Subversion repository, these should be
|
||||
preceded by the command:
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
$ ./boostrap</screen>
|
||||
$ ./bootstrap</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>The installation path can be specified by passing the
|
||||
<option>--prefix=<replaceable>prefix</replaceable></option> to
|
||||
|
|
@ -165,20 +169,24 @@ Hat Linux. They have been known to work work on SuSE Linux 8.1 and
|
|||
distribution based on <literal>glibc</literal> 2.3 or later.</para>
|
||||
|
||||
<para>Once downloaded, the RPMs can be installed or upgraded using
|
||||
<command>rpm -U</command>. For example,</para>
|
||||
<command>rpm -U</command>. For example,
|
||||
|
||||
<screen>
|
||||
$ rpm -U nix-0.5pre664-1.i386.rpm</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>The RPMs install into the directory <filename>/nix</filename>.
|
||||
Nix can be uninstalled using <command>rpm -e nix</command>. After
|
||||
this it will be necessary to manually remove the Nix store and other
|
||||
auxiliary data:</para>
|
||||
auxiliary data:
|
||||
|
||||
<screen>
|
||||
$ rm -rf /nix/store
|
||||
$ rm -rf /nix/var</screen>
|
||||
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
|
|
@ -187,7 +195,7 @@ $ rm -rf /nix/var</screen>
|
|||
<para>You can install the latest stable version of Nix through Nix
|
||||
itself by subscribing to the channel <link
|
||||
xlink:href="http://nix.cs.uu.nl/dist/nix/channels-v3/nix-stable" />,
|
||||
or the latest unstable version by subscribing to the channel<link
|
||||
or the latest unstable version by subscribing to the channel <link
|
||||
xlink:href="http://nix.cs.uu.nl/dist/nix/channels-v3/nix-unstable" />.
|
||||
You can also do a <link linkend="sec-one-click">one-click
|
||||
installation</link> by clicking on the package links at <link
|
||||
|
|
@ -231,33 +239,215 @@ class="username">root</systemitem> all the time.</para>
|
|||
</section>
|
||||
|
||||
|
||||
<section><title>Multi-user mode</title>
|
||||
<section xml:id="ssec-multi-user"><title>Multi-user mode</title>
|
||||
|
||||
<para></para>
|
||||
<para>To allow a Nix store to be shared safely among multiple users,
|
||||
it is important that users are not able to run builders that modify
|
||||
the Nix store or database in arbitrary ways, or that interfere with
|
||||
builds started by other users. If they could do so, they could
|
||||
install a Trojan horse in some package and compromise the accounts of
|
||||
other users.</para>
|
||||
|
||||
|
||||
<!--
|
||||
|
||||
warning: the nix-builders group should contain *only* the Nix
|
||||
builders, and nothing else. If the Nix account is compromised, you
|
||||
can execute programs under the accounts in the nix-builders group, so
|
||||
it obviously shouldn’t contain any “real” user accounts. So don’t use
|
||||
an existing group like <literal>users</literal> — just create a new
|
||||
one.
|
||||
|
||||
-->
|
||||
<para>To prevent this, the Nix store and database are owned by some
|
||||
privileged user (usually <literal>root</literal>) and builders are
|
||||
executed under special user accounts (usually named
|
||||
<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.). When a
|
||||
unprivileged user runs a Nix command, actions that operate on the Nix
|
||||
store (such as builds) are forwarded to a <emphasis>Nix
|
||||
daemon</emphasis> running under the owner of the Nix store/database
|
||||
that performs the operation.</para>
|
||||
|
||||
<note><para>Multi-user mode has one important limitation: only
|
||||
<systemitem class="username">root</systemitem> can run <command
|
||||
linkend="sec-nix-pull">nix-pull</command> to register the availability
|
||||
of pre-built binaries. However, those registrations
|
||||
<emphasis>are</emphasis> used by all users to speed up
|
||||
builds.</para></note>
|
||||
of pre-built binaries. However, those registrations are shared by all
|
||||
users, so they still get the benefit from <command>nix-pull</command>s
|
||||
done by <systemitem class="username">root</systemitem>.</para></note>
|
||||
|
||||
|
||||
<section><title>Setting up the build users</title>
|
||||
|
||||
<para>The <emphasis>build users</emphasis> are the special UIDs under
|
||||
which builds are performed. They should all be members of the
|
||||
<emphasis>build users group</emphasis> (usually called
|
||||
<literal>nixbld</literal>). This group should have no other members.
|
||||
The build users should not be members of any other group.</para>
|
||||
|
||||
<para>Here is a typical <filename>/etc/group</filename> definition of
|
||||
the build users group with 10 build users:
|
||||
|
||||
<programlisting>
|
||||
nixbld:!:30000:nixbld1,nixbld2,nixbld3,nixbld4,nixbld5,nixbld6,nixbld7,nixbld8,nixbld9,nixbld10
|
||||
</programlisting>
|
||||
|
||||
In this example the <literal>nixbld</literal> group has UID 30000, but
|
||||
of course it can be anything that doesn’t collide with an existing
|
||||
group.</para>
|
||||
|
||||
<para>Here is the corresponding part of
|
||||
<filename>/etc/passwd</filename>:
|
||||
|
||||
<programlisting>
|
||||
nixbld1:x:30001:65534:Nix build user 1:/var/empty:/noshell
|
||||
nixbld2:x:30002:65534:Nix build user 2:/var/empty:/noshell
|
||||
nixbld3:x:30003:65534:Nix build user 3:/var/empty:/noshell
|
||||
...
|
||||
nixbld10:x:30010:65534:Nix build user 10:/var/empty:/noshell
|
||||
</programlisting>
|
||||
|
||||
The home directory of the build users should not exist or should be an
|
||||
empty directory to which they do not have write access.</para>
|
||||
|
||||
<para>The build users should have write access to the Nix store, but
|
||||
they should not have the right to delete files. Thus the Nix store’s
|
||||
group should be the build users group, and it should have the sticky
|
||||
bit turned on (like <filename>/tmp</filename>):
|
||||
|
||||
<screen>
|
||||
$ chgrp nixbld /nix/store
|
||||
$ chmod 1777 /nix/store
|
||||
</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>Finally, you should tell Nix to use the build users by
|
||||
specifying the build users group in the <link
|
||||
linkend="conf-build-users-group"><literal>build-users-group</literal>
|
||||
option</link> in the <link linkend="sec-conf-file">Nix configuration
|
||||
file</link> (<literal>/nix/etc/nix/nix.conf</literal>):
|
||||
|
||||
<programlisting>
|
||||
build-users-group = nixbld
|
||||
</programlisting>
|
||||
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
</section> <!-- end of permissions section -->
|
||||
<section><title>Nix store/database owned by root</title>
|
||||
|
||||
<para>The simplest setup is to let <literal>root</literal> own the Nix
|
||||
store and database. I.e.,
|
||||
|
||||
<screen>
|
||||
$ chown -R root /nix/store /nix/var/nix</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>The Nix daemon should be started as follows (as
|
||||
<literal>root</literal>):
|
||||
|
||||
<screen>
|
||||
$ nix-worker --daemon</screen>
|
||||
|
||||
You’ll want to put that line somewhere in your system’s boot
|
||||
scripts.</para>
|
||||
|
||||
<para>To let unprivileged users use the daemon, they should set the
|
||||
<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment
|
||||
variable</link> to <literal>daemon</literal>. So you should put a
|
||||
line like
|
||||
|
||||
<programlisting>
|
||||
export NIX_REMOTE=daemon</programlisting>
|
||||
|
||||
into the users’ login scripts.</para>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<section><title>Nix store/database not owned by root</title>
|
||||
|
||||
<para>It is also possible to let the Nix store and database be owned
|
||||
by a non-root user, which should be more secure<footnote><para>Note
|
||||
however that even when the Nix daemon runs as root, not
|
||||
<emphasis>that</emphasis> much code is executed as root: Nix
|
||||
expression evaluation is performed by the calling (unprivileged) user,
|
||||
and builds are performed under the special build user accounts. So
|
||||
only the code that accesses the database and starts builds is executed
|
||||
as <literal>root</literal>.</para></footnote>. Typically, this user
|
||||
is a special account called <literal>nix</literal>, but it can be
|
||||
named anything. It should own the Nix store and database:
|
||||
|
||||
<screen>
|
||||
$ chown -R root /nix/store /nix/var/nix</screen>
|
||||
|
||||
and of course <command>nix-worker --daemon</command> should be started
|
||||
under that user, e.g.,
|
||||
|
||||
<screen>
|
||||
$ su - nix -c "exec /nix/bin/nix-worker --daemon"</screen>
|
||||
|
||||
</para>
|
||||
|
||||
<para>There is a catch, though: non-<literal>root</literal> users
|
||||
cannot start builds under the build user accounts, since the
|
||||
<function>setuid</function> system call is obviously privileged. To
|
||||
allow a non-<literal>root</literal> Nix daemon to use the build user
|
||||
feature, it calls a setuid-root helper program,
|
||||
<command>nix-setuid-helper</command>. This program is installed in
|
||||
<filename><replaceable>prefix</replaceable>/libexec/nix-setuid-helper</filename>.
|
||||
To set the permissions properly (Nix’s <command>make install</command>
|
||||
doesn’t do this, since we don’t want to ship setuid-root programs
|
||||
out-of-the-box):
|
||||
|
||||
<screen>
|
||||
$ chown root.root /nix/libexec/nix-setuid-helper
|
||||
$ chmod 4755 /nix/libexec/nix-setuid-helper
|
||||
</screen>
|
||||
|
||||
(This example assumes that the Nix binaries are installed in
|
||||
<filename>/nix</filename>.)</para>
|
||||
|
||||
<para>Of course, the <command>nix-setuid-helper</command> command
|
||||
should not be usable by just anybody, since then anybody could run
|
||||
commands under the Nix build user accounts. For that reason there is
|
||||
a configuration file <filename>/etc/nix-setuid.conf</filename> that
|
||||
restricts the use of the helper. This file should be a text file
|
||||
containing precisely two lines, the first being the Nix daemon user
|
||||
and the second being the build users group, e.g.,
|
||||
|
||||
<programlisting>
|
||||
nix
|
||||
nixbld
|
||||
</programlisting>
|
||||
|
||||
The setuid-helper barfs if it is called by a user other than the one
|
||||
specified on the first line, or if it is asked to execute a build
|
||||
under a user who is not a member of the group specified on the second
|
||||
line. The file <filename>/etc/nix-setuid.conf</filename> must be
|
||||
owned by root, and must not be group- or world-writable. The
|
||||
setuid-helper barfs if this is not the case.</para>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<section><title>Restricting access</title>
|
||||
|
||||
<para>To limit which users can perform Nix operations, you can use the
|
||||
permissions on the directory
|
||||
<filename>/nix/var/nix/daemon-socket</filename>. For instance, if you
|
||||
want to restrict the use of Nix to the members of a group called
|
||||
<literal>nix-users</literal>, do
|
||||
|
||||
<screen>
|
||||
$ chgrp nix-users /nix/var/nix/daemon-socket
|
||||
$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
|
||||
</screen>
|
||||
|
||||
This way, users who are not in the <literal>nix-users</literal> group
|
||||
cannot connect to the Unix domain socket
|
||||
<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot
|
||||
perform Nix operations.</para>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
</section> <!-- end of multi-user -->
|
||||
|
||||
|
||||
</section> <!-- end of security -->
|
||||
|
||||
|
||||
<section><title>Using Nix</title>
|
||||
|
|
|
|||
|
|
@ -19,13 +19,6 @@
|
|||
<command>nix-env</command>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
|
||||
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
|
||||
<arg>
|
||||
<group choice='req'>
|
||||
<arg choice='plain'><option>--attr</option></arg>
|
||||
<arg choice='plain'><option>-A</option></arg>
|
||||
</group>
|
||||
<replaceable>attrPath</replaceable>
|
||||
</arg>
|
||||
<arg>
|
||||
<group choice='req'>
|
||||
<arg choice='plain'><option>--file</option></arg>
|
||||
|
|
@ -45,9 +38,6 @@
|
|||
<replaceable>system</replaceable>
|
||||
</arg>
|
||||
<arg><option>--dry-run</option></arg>
|
||||
<arg><option>--from-expression</option></arg>
|
||||
<arg><option>-E</option></arg>
|
||||
<arg><option>--from-profile</option> <replaceable>path</replaceable></arg>
|
||||
<arg choice='plain'><replaceable>operation</replaceable></arg>
|
||||
<arg rep='repeat'><replaceable>options</replaceable></arg>
|
||||
<arg rep='repeat'><replaceable>arguments</replaceable></arg>
|
||||
|
|
@ -190,6 +180,7 @@ linkend="sec-common-options" />.</para>
|
|||
<arg choice='plain'><option>--install</option></arg>
|
||||
<arg choice='plain'><option>-i</option></arg>
|
||||
</group>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
|
||||
<group choice='opt'>
|
||||
<arg choice='plain'><option>--preserve-installed</option></arg>
|
||||
<arg choice='plain'><option>-P</option></arg>
|
||||
|
|
@ -397,6 +388,7 @@ the following paths will be substituted:
|
|||
<arg choice='plain'><option>--upgrade</option></arg>
|
||||
<arg choice='plain'><option>-u</option></arg>
|
||||
</group>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
|
||||
<group choice='opt'>
|
||||
<arg choice='plain'><option>--lt</option></arg>
|
||||
<arg choice='plain'><option>--leq</option></arg>
|
||||
|
|
@ -592,25 +584,21 @@ $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
|
|||
<arg choice='plain'><option>--query</option></arg>
|
||||
<arg choice='plain'><option>-q</option></arg>
|
||||
</group>
|
||||
<arg><option>--xml</option></arg>
|
||||
<group choice='opt'>
|
||||
<arg choice='plain'><option>--installed</option></arg>
|
||||
<arg choice='plain'><option>--available</option></arg>
|
||||
<arg choice='plain'><option>-a</option></arg>
|
||||
</group>
|
||||
|
||||
<sbr />
|
||||
|
||||
<arg>
|
||||
<group choice='req'>
|
||||
<arg choice='plain'><option>--status</option></arg>
|
||||
<arg choice='plain'><option>-s</option></arg>
|
||||
</group>
|
||||
</arg>
|
||||
<arg>
|
||||
<group choice='req'>
|
||||
<arg choice='plain'><option>--attr</option></arg>
|
||||
<arg choice='plain'><option>-A</option></arg>
|
||||
</group>
|
||||
</arg>
|
||||
<arg><option>--attr-path</option></arg>
|
||||
<arg><option>--no-name</option></arg>
|
||||
<arg>
|
||||
<group choice='req'>
|
||||
|
|
@ -622,6 +610,27 @@ $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
|
|||
<arg><option>--drv-path</option></arg>
|
||||
<arg><option>--out-path</option></arg>
|
||||
<arg><option>--description</option></arg>
|
||||
<arg><option>--meta</option></arg>
|
||||
|
||||
<sbr />
|
||||
|
||||
<arg><option>--xml</option></arg>
|
||||
<arg>
|
||||
<group choice='req'>
|
||||
<arg choice='plain'><option>--prebuilt-only</option></arg>
|
||||
<arg choice='plain'><option>-b</option></arg>
|
||||
</group>
|
||||
</arg>
|
||||
<arg>
|
||||
<group choice='req'>
|
||||
<arg choice='plain'><option>--attr</option></arg>
|
||||
<arg choice='plain'><option>-A</option></arg>
|
||||
</group>
|
||||
<replaceable>attribute-path</replaceable>
|
||||
</arg>
|
||||
|
||||
<sbr />
|
||||
|
||||
<arg choice='plain' rep='repeat'><replaceable>names</replaceable></arg>
|
||||
</cmdsynopsis>
|
||||
|
||||
|
|
|
|||
15
doc/manual/opt-inst-syn.xml
Normal file
15
doc/manual/opt-inst-syn.xml
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
<nop xmlns="http://docbook.org/ns/docbook">
|
||||
|
||||
<arg>
|
||||
<group choice='req'>
|
||||
<arg choice='plain'><option>--attr</option></arg>
|
||||
<arg choice='plain'><option>-A</option></arg>
|
||||
</group>
|
||||
</arg>
|
||||
|
||||
<arg><option>--from-expression</option></arg>
|
||||
<arg><option>-E</option></arg>
|
||||
|
||||
<arg><option>--from-profile</option> <replaceable>path</replaceable></arg>
|
||||
|
||||
</nop>
|
||||
|
|
@ -38,9 +38,13 @@
|
|||
paths.</para></listitem>
|
||||
|
||||
|
||||
<listitem><para>TODO: <varname>allowedReferences</varname> for
|
||||
checking the set of references in the output of a
|
||||
derivation.</para></listitem>
|
||||
<listitem><para>Derivations can specify the new special attribute
|
||||
<varname>allowedReferences</varname> to enforce that the references
|
||||
in the output of a derivation are a subset of a declared set of
|
||||
paths. For example, if <varname>allowedReferences</varname> is an
|
||||
empty list, then the output must not have any references. This is
|
||||
used in NixOS to check that generated files such as initial ramdisks
|
||||
for booting Linux don’t have any dependencies.</para></listitem>
|
||||
|
||||
|
||||
<listitem><para>TODO: semantic cleanups of string concatenation
|
||||
|
|
@ -54,8 +58,11 @@
|
|||
<command>nix-store --register-validity</command>.</para></listitem>
|
||||
|
||||
|
||||
<listitem><para>TODO: magic <varname>exportReferencesGraph</varname>
|
||||
attribute.</para></listitem>
|
||||
<listitem><para>The new attribute
|
||||
<varname>exportReferencesGraph</varname> allows builders access to
|
||||
the references graph of their inputs. This is used in NixOS for
|
||||
tasks such as generating ISO-9660 images that contain a Nix store
|
||||
populated with the closure of certain paths.</para></listitem>
|
||||
|
||||
|
||||
<listitem><para>TODO: option <option>--max-silent-time</option>,
|
||||
|
|
@ -109,8 +116,10 @@
|
|||
disambiguation (<command>nix-env -qaA</command>).</para></listitem>
|
||||
|
||||
|
||||
<listitem><para>TODO: substitutes table is gone, registering
|
||||
substitutes is now much faster.</para></listitem>
|
||||
<listitem><para>The substitutes table has been removed from the
|
||||
database. This makes operations such as <command>nix-pull</command>
|
||||
and <command>nix-channel --update</command>
|
||||
<emphasis>much</emphasis> faster.</para></listitem>
|
||||
|
||||
|
||||
<listitem><para><command>nix-prefetch-url</command> now has a
|
||||
|
|
|
|||
|
|
@ -607,7 +607,7 @@ language.</para>
|
|||
|
||||
<simplesect><title>Simple values</title>
|
||||
|
||||
<para>Nix has the following basic datatypes:
|
||||
<para>Nix has the following basic data types:
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
|
|
@ -679,7 +679,7 @@ configureFlags = "
|
|||
instance, <filename>builder.sh</filename> is not a
|
||||
path<footnote><para>It's parsed as an expression that selects the
|
||||
attribute <varname>sh</varname> from the variable
|
||||
<varname>builder</varname>.</para></footnote>. If the filename is
|
||||
<varname>builder</varname>.</para></footnote>. If the file name is
|
||||
relative, i.e., if it does not begin with a slash, it is made
|
||||
absolute at parse time relative to the directory of the Nix
|
||||
expression that contained it. For instance, if a Nix expression in
|
||||
|
|
@ -701,7 +701,7 @@ configureFlags = "
|
|||
<simplesect><title>Lists</title>
|
||||
|
||||
<para>Lists are formed by enclosing a whitespace-separated list of
|
||||
values between square bracktes. For example,
|
||||
values between square brackets. For example,
|
||||
|
||||
<programlisting>
|
||||
[ 123 ./foo.nix "abc" (f {x=y;}) ]</programlisting>
|
||||
|
|
@ -927,7 +927,7 @@ evaluates to <literal>["foobar" "foobla" "fooabc"]</literal>.</para>
|
|||
if <replaceable>e1</replaceable> then <replaceable>e2</replaceable> else <replaceable>e3</replaceable></programlisting>
|
||||
|
||||
where <replaceable>e1</replaceable> is an expression that should
|
||||
evaluate to a boolean value (<literal>true</literal> or
|
||||
evaluate to a Boolean value (<literal>true</literal> or
|
||||
<literal>false</literal>).</para>
|
||||
|
||||
</simplesect>
|
||||
|
|
@ -942,7 +942,7 @@ on or between features and dependencies hold. They look like this:
|
|||
assert <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting>
|
||||
|
||||
where <replaceable>e1</replaceable> is an expression that should
|
||||
evaluate to a boolean value. If it evaluates to
|
||||
evaluate to a Boolean value. If it evaluates to
|
||||
<literal>true</literal>, <replaceable>e2</replaceable> is returned;
|
||||
otherwise expression evaluation is aborted and a backtrace is printed.</para>
|
||||
|
||||
|
|
@ -1234,7 +1234,7 @@ set, the attributes of which specify the inputs of the build.</para>
|
|||
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>The optional argument <varname>args</varname>
|
||||
<listitem><para>The optional attribute <varname>args</varname>
|
||||
specifies command-line arguments to be passed to the builder. It
|
||||
should be a list.</para></listitem>
|
||||
|
||||
|
|
@ -1337,6 +1337,233 @@ command-line argument. See <xref linkend='sec-standard-environment'
|
|||
|
||||
</para>
|
||||
|
||||
|
||||
<section><title>Advanced attributes</title>
|
||||
|
||||
<para>Derivations can declare some infrequently used optional
|
||||
attributes.</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry><term><varname>allowedReferences</varname></term>
|
||||
|
||||
<listitem><para>The optional attribute
|
||||
<varname>allowedReferences</varname> specifies a list of legal
|
||||
references (dependencies) of the output of the builder. For
|
||||
example,
|
||||
|
||||
<programlisting>
|
||||
allowedReferences = [];
|
||||
</programlisting>
|
||||
|
||||
enforces that the output of a derivation cannot have any runtime
|
||||
dependencies on its inputs. This is used in NixOS to check that
|
||||
generated files such as initial ramdisks for booting Linux don’t
|
||||
have accidental dependencies on other paths in the Nix
|
||||
store.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry><term><varname>exportReferencesGraph</varname></term>
|
||||
|
||||
<listitem><para>This attribute allows builders access to the
|
||||
references graph of their inputs. The attribute is a list of
|
||||
inputs in the Nix store whose references graph the builder needs
|
||||
to know. The value of this attribute should be a list of pairs
|
||||
<literal>[<replaceable>name1</replaceable>
|
||||
<replaceable>path1</replaceable> <replaceable>name2</replaceable>
|
||||
<replaceable>path2</replaceable>
|
||||
<replaceable>...</replaceable>]</literal>. The references graph
|
||||
of each <replaceable>pathN</replaceable> will be stored in a text
|
||||
file <replaceable>nameN</replaceable> in the temporary build
|
||||
directory. The text files have the format used by
|
||||
<command>nix-store --register-validity</command> (with the deriver
|
||||
fields left empty). For example, when the following derivation is
|
||||
built:
|
||||
|
||||
<programlisting>
|
||||
derivation {
|
||||
...
|
||||
exportReferencesGraph = ["libfoo-graph" libfoo];
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
the references graph of <literal>libfoo</literal> is placed in the
|
||||
file <filename>libfoo-graph</filename> in the temporary build
|
||||
directory.</para>
|
||||
|
||||
<para><varname>exportReferencesGraph</varname> is useful for
|
||||
builders that want to do something with the closure of a store
|
||||
path. Examples include the builders in NixOS that generate the
|
||||
initial ramdisk for booting Linux (a <command>cpio</command>
|
||||
archive containing the closure of the boot script) and the
|
||||
ISO-9660 image for the installation CD (which is populated with a
|
||||
Nix store containing the closure of a bootable NixOS
|
||||
configuration).</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry xml:id="fixed-output-drvs">
|
||||
<term><varname>outputHash</varname></term>
|
||||
<term><varname>outputHashAlgo</varname></term>
|
||||
<term><varname>outputHashMode</varname></term>
|
||||
|
||||
<listitem><para>These attributes declare that the derivation is a
|
||||
so-called <emphasis>fixed-output derivation</emphasis>, which
|
||||
means that a cryptographic hash of the output is already known in
|
||||
advance. When the build of a fixed-output derivation finishes,
|
||||
Nix computes the cryptographic hash of the output and compares it
|
||||
to the hash declared with these attributes. If there is a
|
||||
mismatch, the build fails.</para>
|
||||
|
||||
<para>The rationale for fixed-output derivations is derivations
|
||||
such as those produced by the <function>fetchurl</function>
|
||||
function. This function downloads a file from a given URL. To
|
||||
ensure that the downloaded file has not been modified, the caller
|
||||
must also specify a cryptographic hash of the file. For example,
|
||||
|
||||
<programlisting>
|
||||
fetchurl {
|
||||
url = http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz;
|
||||
md5 = "70c9ccf9fac07f762c24f2df2290784d";
|
||||
}
|
||||
</programlisting>
|
||||
|
||||
It sometimes happens that the URL of the file changes, e.g.,
|
||||
because servers are reorganised or no longer available. We then
|
||||
must update the call to <function>fetchurl</function>, e.g.,
|
||||
|
||||
<programlisting>
|
||||
fetchurl {
|
||||
url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
|
||||
md5 = "70c9ccf9fac07f762c24f2df2290784d";
|
||||
}
|
||||
</programlisting>
|
||||
|
||||
If a <function>fetchurl</function> derivation was treated like a
|
||||
normal derivation, the output paths of the derivation and
|
||||
<emphasis>all derivations depending on it</emphasis> would change.
|
||||
For instance, if we were to change the URL of the Glibc source
|
||||
distribution in Nixpkgs (a package on which almost all other
|
||||
packages depend) massive rebuilds would be needed. This is
|
||||
unfortunate for a change which we know cannot have a real effect
|
||||
as it propagates upwards through the dependency graph.</para>
|
||||
|
||||
<para>For fixed-output derivations, on the other hand, the name of
|
||||
the output path only depends on the <varname>outputHash*</varname>
|
||||
and <varname>name</varname> attributes, while all other attributes
|
||||
are ignored for the purpose of computing the output path. (The
|
||||
<varname>name</varname> attribute is included because it is part
|
||||
of the path.)</para>
|
||||
|
||||
<para>As an example, here is the (simplified) Nix expression for
|
||||
<varname>fetchurl</varname>:
|
||||
|
||||
<programlisting>
|
||||
{stdenv, curl}: # The <command>curl</command> program is used for downloading.
|
||||
|
||||
{url, md5}:
|
||||
|
||||
stdenv.mkDerivation {
|
||||
name = baseNameOf (toString url);
|
||||
builder = ./builder.sh;
|
||||
buildInputs = [curl];
|
||||
|
||||
# This is a fixed-output derivation; the output must be a regular
|
||||
# file with MD5 hash <varname>md5</varname>.
|
||||
outputHashMode = "flat";
|
||||
outputHashAlgo = "md5";
|
||||
outputHash = md5;
|
||||
|
||||
inherit url;
|
||||
}
|
||||
</programlisting>
|
||||
|
||||
</para>
|
||||
|
||||
<para>The <varname>outputHashAlgo</varname> attribute specifies
|
||||
the hash algorithm used to compute the hash. It can currently be
|
||||
<literal>"md5"</literal>, <literal>"sha1"</literal> or
|
||||
<literal>"sha256"</literal>.</para>
|
||||
|
||||
<para>The <varname>outputHashMode</varname> attribute determines
|
||||
how the hash is computed. It must be one of the following two
|
||||
values:
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry><term><literal>"flat"</literal></term>
|
||||
|
||||
<listitem><para>The output must be a non-executable regular
|
||||
file. If it isn’t, the build fails. The hash is simply
|
||||
computed over the contents of that file (so it’s equal to what
|
||||
Unix commands like <command>md5sum</command> or
|
||||
<command>sha1sum</command> produce).</para>
|
||||
|
||||
<para>This is the default.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><literal>"recursive"</literal></term>
|
||||
|
||||
<listitem><para>The hash is computed over the NAR archive dump
|
||||
of the output (i.e., the result of <link
|
||||
linkend="refsec-nix-store-dump"><command>nix-store
|
||||
--dump</command></link>). In this case, the output can be
|
||||
anything, including a directory tree.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</para>
|
||||
|
||||
<para>The <varname>outputHash</varname> attribute, finally, must
|
||||
be a string containing the hash in either hexadecimal or base-32
|
||||
notation. (See the <link
|
||||
linkend="sec-nix-hash"><command>nix-hash</command> command</link>
|
||||
for information about converting to and from base-32
|
||||
notation.)</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry><term><varname>impureEnvVars</varname></term>
|
||||
|
||||
<listitem><para>This attribute allows you to specify a list of
|
||||
environment variables that should be passed from the environment
|
||||
of the calling user to the builder. Usually, the environment is
|
||||
cleared completely when the builder is executed, but with this
|
||||
attribute you can allow specific environment variables to be
|
||||
passed unmodified. For example, <function>fetchurl</function> in
|
||||
Nixpkgs has the line
|
||||
|
||||
<programlisting>
|
||||
impureEnvVars = ["http_proxy" "https_proxy" <replaceable>...</replaceable>];
|
||||
</programlisting>
|
||||
|
||||
to make it use the proxy server configuration specified by the
|
||||
user in the environment variables <envar>http_proxy</envar> and
|
||||
friends.</para>
|
||||
|
||||
<para>This attribute is only allowed in <link
|
||||
linkend="fixed-output-drvs">fixed-output derivations</link>, where
|
||||
impurities such as these are okay since (the hash of) the output
|
||||
is known in advance. It is ignored for all other
|
||||
derivations.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
|
||||
|
||||
|
||||
</variablelist>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue