Manual updates

This commit is contained in:
Eelco Dolstra 2012-05-11 17:39:06 -04:00
parent 2b00e6990c
commit 8a08813d6c
6 changed files with 132 additions and 75 deletions

View file

@ -15,11 +15,11 @@
<listitem><para>Linux (particularly on x86, x86_64, and
PowerPC).</para></listitem>
<listitem><para>Mac OS X, both on Intel and
PowerPC.</para></listitem>
<listitem><para>Mac OS X.</para></listitem>
<listitem><para>FreeBSD (only tested on Intel).</para></listitem>
<!--
<listitem><para>Windows through <link
xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
@ -28,6 +28,7 @@
partition.</para></warning>
</listitem>
-->
</itemizedlist>
@ -47,7 +48,7 @@ for Red Hat, SuSE, and Fedora Core are also available.</para>
<para>Alternatively, the most recent sources of Nix can be obtained
from its <link
xlink:href="https://github.com/NixOS/nix">git
xlink:href="https://github.com/NixOS/nix">Git
repository</link>. For example, the following command will check out
the latest revision into a directory called
<filename>nix</filename>:</para>
@ -56,8 +57,8 @@ the latest revision into a directory called
$ git clone https://github.com/NixOS/nix</screen>
<para>Likewise, specific releases can be obtained from the <link
xlink:href="https://github.com/NixOS/nix/tags">tags
</link> of the repository.</para>
xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the
repository.</para>
</section>
@ -85,9 +86,9 @@ installed, including development headers and libraries. If your
distribution does not provide these, you can obtain bzip2 from <link
xlink:href="http://www.bzip.org/"/>.</para>
<para>Nix requires the SQLite embedded database library. If your
distribution does not provide it, please install it from <link
xlink:href="http://www.sqlite.org/" />.</para>
<para>Nix requires the SQLite embedded database library, version
3.6.19 or higher. If your distribution does not provide it, please
install it from <link xlink:href="http://www.sqlite.org/" />.</para>
<para>Nix requires the Perl DBI and DBD::SQLite libraries, which are
available from <link xlink:href="http://search.cpan.org/">CPAN</link>
@ -109,21 +110,20 @@ xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook XSL
stylesheets</link> and optionally the <link
xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
schemas</link>. Note that these are only required if you modify the
manual sources or when you are building from the Subversion
manual sources or when you are building from the Git
repository.</para>
<para>To build the parser, very <emphasis>recent</emphasis> versions
of Bison and Flex are required. (This is because Nix needs GLR
support in Bison and reentrancy support in Flex.) For Bison, you need
version 2.3 or higher (1.875 does <emphasis>not</emphasis> work),
which can be obtained from
the <link xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP
server</link>. For Flex, you need version 2.5.33, which is available
on <link xlink:href="http://lex.sourceforge.net/">SourceForge</link>.
Slightly older versions may also work, but ancient versions like the
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>
which can be obtained from the <link
xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP server</link>.
For Flex, you need version 2.5.33, which is available on <link
xlink:href="http://lex.sourceforge.net/">SourceForge</link>. Slightly
older versions may also work, but ancient versions like the ubiquitous
2.5.4a won't. Note that these are only required if you modify the
parser or when you are building from the Git repository.</para>
</section>
@ -140,8 +140,8 @@ $ make install</screen>
</para>
<para>When building from the Subversion repository, these should be
preceded by the command:
<para>When building from the Git repository, these should be preceded
by the command:
<screen>
$ ./bootstrap.sh</screen>

View file

@ -17,10 +17,10 @@ store</emphasis>, usually the directory
subdirectory such as
<programlisting>
/nix/store/r8vvq9kq18pz08v249h8my6r9vs7s0n3-firefox-2.0.0.1/
/nix/store/nlc4z5y1hm8w9s8vm6m1f5hy962xjmp5-firefox-12.0
</programlisting>
where <literal>r8vvq9kq</literal> is a unique identifier for the
where <literal>nlc4z5</literal> is a unique identifier for the
package that captures all its dependencies (its a cryptographic hash
of the packages build dependency graph). This enables many powerful
features.</para>
@ -72,15 +72,14 @@ sounds risky, but it works extremely well.</para>
<simplesect><title>Multi-user support</title>
<para>Starting at version 0.11, Nix has multi-user support. This
means that non-privileged users can securely install software. Each
user can have a different <emphasis>profile</emphasis>, a set of
packages in the Nix store that appear in the users
<envar>PATH</envar>. If a user installs a package that another user
has already installed previously, the package wont be built or
downloaded a second time. At the same time, it is not possible for
one user to inject a Trojan horse into a package that might be used by
another user.</para>
<para>Nix has multi-user support. This means that non-privileged
users can securely install software. Each user can have a different
<emphasis>profile</emphasis>, a set of packages in the Nix store that
appear in the users <envar>PATH</envar>. If a user installs a
package that another user has already installed previously, the
package wont be built or downloaded a second time. At the same time,
it is not possible for one user to inject a Trojan horse into a
package that might be used by another user.</para>
<!--
<para>More details can be found in Section 3 of our <a
@ -264,8 +263,10 @@ xlink:href="http://www.cs.uu.nl/wiki/Trace/WebHome">TraCE
project</link> (2003-2008). The project was funded by the Software
Engineering Research Program <link
xlink:href="http://www.jacquard.nl/">Jacquard</link> to improve the
support for variability in software systems. Further funding is now
provided by the NIRICT LaQuSo Build Farm project.</para>
support for variability in software systems. Further funding was
provided by the NIRICT LaQuSo Build Farm project. Development is
currently supported by <link
xlink:href="http://www.logicblox.com/">LogicBlox</link>.</para>
</section>
@ -275,7 +276,7 @@ provided by the NIRICT LaQuSo Build Farm project.</para>
<para>This manual tells you how to install and use Nix and how to
write Nix expressions for software not already in the Nix Packages
collection. It also discusses some advanced topics, such as setting
up a Nix-based build farm.</para>
up distributed multi-platform building.</para>
</section>
@ -315,13 +316,12 @@ Upgrading in a Purely Functional Component Deployment Model
paper <citetitle
xlink:href='http://www.st.ewi.tudelft.nl/~dolstra/pubs/servicecm-scm12-final.pdf'>
Service Configuration Management</citetitle> shows how services (e.g.,
web servers) can be deployed and managed through Nix. A short
overview of NixOS is given in the HotOS XI paper <citetitle
xlink:href="http://www.st.ewi.tudelft.nl/~dolstra/pubs/hotos-final.pdf">Purely
Functional System Configuration Management</citetitle>. The Nix
homepage has <link
xlink:href="http://nixos.org/docs/papers.html">an up-to-date list
of Nix-related papers</link>.</para>
web servers) can be deployed and managed through Nix. An overview of
NixOS is given in the JFP article <citetitle
xlink:href="http://www.st.ewi.tudelft.nl/~dolstra/pubs/nixos-jfp-final.pdf">NixOS:
A Purely Functional Linux Distribution</citetitle>. The Nix homepage
has <link xlink:href="http://nixos.org/docs/papers.html">an up-to-date
list of Nix-related papers</link>.</para>
<para>Nix is the subject of Eelco Dolstras PhD thesis <citetitle
xlink:href="http://igitur-archive.library.uu.nl/dissertations/2006-0118-200031/index.htm">The

View file

@ -5,8 +5,7 @@
<title>Nix User's Guide</title>
<subtitle>Draft (Version <xi:include href="version.txt"
parse="text" />)</subtitle>
<edition>Version <xi:include href="version.txt" parse="text" /></edition>
<author>
<personname>
@ -24,7 +23,7 @@
<holder>Eelco Dolstra</holder>
</copyright>
<date>January 2012</date>
<date>May 2012</date>
</info>

View file

@ -11,9 +11,9 @@ to the following chapters.</para>
<orderedlist>
<listitem><para>Download a source tarball, RPM or Deb from <link
xlink:href='http://nixos.org/'/>. Build source distributions using
the regular sequence:
<listitem><para>Download a source tarball or RPM or Debian/Ubuntu
package from <link xlink:href='http://nixos.org/'/>. Build source
distributions using the regular sequence:
<screen>
$ tar xvfj nix-<replaceable>version</replaceable>.tar.bz2
@ -41,8 +41,7 @@ file).</para></listitem>
<listitem><para>Subscribe to the Nix Packages channel.
<screen>
$ nix-channel --add \
http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable</screen>
$ nix-channel --add http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable</screen>
</para></listitem>
@ -108,10 +107,10 @@ numbers).</para></listitem>
<listitem><para>You can also install specific packages directly from
your web browser. For instance, you can go to <link
xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest" />
and click on any link for the individual packages for your platform.
Associate <literal>application/nix-package</literal> with the program
<filename>/nix/bin/nix-install-package</filename>. A window should
xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
/> and click on any link for the individual packages for your
platform. Associate <literal>application/nix-package</literal> with
the program <command>nix-install-package</command>. A window should
appear asking you whether its okay to install the package. Say
<literal>Y</literal>. The package and all its dependencies will be
installed.</para></listitem>

View file

@ -234,7 +234,6 @@ div.glosslist dt
span.command strong
{
font-family: monospace;
font-weight: normal;
color: #400000;
}
@ -249,3 +248,8 @@ table
border-collapse: collapse;
box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
}
div.affiliation
{
font-style: italic;
}

View file

@ -11,6 +11,13 @@ the things that tell Nix how to build packages. It starts with a
simple example (a Nix expression for GNU Hello), and then moves
on to a more in-depth look at the Nix expression language.</para>
<note><para>This chapter is mostly about the Nix expression language.
For more extensive information on adding packages to the Nix Packages
collection (such as functions in the standard environment and coding
conventions), please consult <link
xlink:href="http://hydra.nixos.org/job/nixpkgs/trunk/tarball/latest/download-by-type/doc/manual">its
manual</link>.</para></note>
<section><title>A simple Nix expression</title>
@ -315,15 +322,15 @@ error check.</para>
rec { <co xml:id='ex-hello-composition-co-1' />
hello = (import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' />) { <co xml:id='ex-hello-composition-co-3' />
hello = import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' /> { <co xml:id='ex-hello-composition-co-3' />
inherit fetchurl stdenv perl;
};
perl = (import ../development/interpreters/perl) { <co xml:id='ex-hello-composition-co-4' />
perl = import ../development/interpreters/perl { <co xml:id='ex-hello-composition-co-4' />
inherit fetchurl stdenv;
};
fetchurl = (import ../build-support/fetchurl) {
fetchurl = import ../build-support/fetchurl {
inherit stdenv; ...
};
@ -390,6 +397,23 @@ some fragments of
<varname>stdenv.mkDerivation</varname> in <xref
linkend='ex-hello-nix' />).</para>
<note><para>Nixpkgs has a convenience function
<function>callPackage</function> that imports and calls a
function, filling in any missing arguments by passing the
corresponding attribute from the Nixpkgs set, like this:
<programlisting>
hello = callPackage ../applications/misc/hello/ex-1 { };
</programlisting>
If necessary, you can set or override arguments:
<programlisting>
hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; };
</programlisting>
</para></note>
</callout>
<callout arearefs='ex-hello-composition-co-4'>
@ -813,7 +837,23 @@ occur once.</para>
<programlisting>
{ a = "Foo"; b = "Bar"; }.a</programlisting>
evaluates to <literal>"Foo"</literal>.</para>
evaluates to <literal>"Foo"</literal>. It is possible to provide a
default value in an attribute selection using the
<literal>or</literal> keyword. For example,
<programlisting>
{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</programlisting>
will evaluate to <literal>"Xyzzy"</literal> because there is no
<varname>c</varname> attribute in the set.</para>
<para>You can use arbitrary string constants as attribute names by
enclosing them in quotes:
<programlisting>
{ "foo bar" = 123; "nix-1.0" = 456; }."foo bar" </programlisting>
This will evaluate to <literal>123</literal>.</para>
</simplesect>
@ -1189,12 +1229,17 @@ weakest binding).</para>
</thead>
<tbody>
<row>
<entry><replaceable>e</replaceable> .
<replaceable>id</replaceable></entry>
<entry><replaceable>e</replaceable> <literal>.</literal>
<replaceable>attrpath</replaceable>
[ <literal>or</literal> <replaceable>def</replaceable> ]
</entry>
<entry>none</entry>
<entry>Select attribute named <replaceable>id</replaceable>
from attribute set <replaceable>e</replaceable>. Abort
evaluation if the attribute doesnt exist.</entry>
<entry>Select attribute denoted by the attribute path
<replaceable>attrpath</replaceable> from attribute set
<replaceable>e</replaceable>. (An attribute path is a
dot-separated list of attribute names.) If the attribute
doesnt exist, return <replaceable>def</replaceable> if
provided, otherwise abort evaluation.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <replaceable>e2</replaceable></entry>
@ -1203,31 +1248,31 @@ weakest binding).</para>
argument <replaceable>e2</replaceable>.</entry>
</row>
<row>
<entry><replaceable>e</replaceable> ?
<replaceable>id</replaceable></entry>
<entry><replaceable>e</replaceable> <literal>?</literal>
<replaceable>attrpath</replaceable></entry>
<entry>none</entry>
<entry>Test whether attribute set <replaceable>e</replaceable>
contains an attribute named <replaceable>id</replaceable>;
contains the attribute denoted by <replaceable>attrpath</replaceable>;
return <literal>true</literal> or
<literal>false</literal>.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> ++ <replaceable>e2</replaceable></entry>
<entry><replaceable>e1</replaceable> <literal>++</literal> <replaceable>e2</replaceable></entry>
<entry>right</entry>
<entry>List concatenation.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> + <replaceable>e2</replaceable></entry>
<entry><replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>String or path concatenation.</entry>
</row>
<row>
<entry>! <replaceable>e</replaceable></entry>
<entry><literal>!</literal> <replaceable>e</replaceable></entry>
<entry>left</entry>
<entry>Boolean negation.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> //
<entry><replaceable>e1</replaceable> <literal>//</literal>
<replaceable>e2</replaceable></entry>
<entry>right</entry>
<entry>Return an attribute set consisting of the attributes in
@ -1236,31 +1281,31 @@ weakest binding).</para>
precedence over the former in case of equally named attributes).</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> ==
<entry><replaceable>e1</replaceable> <literal>==</literal>
<replaceable>e2</replaceable></entry>
<entry>none</entry>
<entry>Equality.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> !=
<entry><replaceable>e1</replaceable> <literal>!=</literal>
<replaceable>e2</replaceable></entry>
<entry>none</entry>
<entry>Inequality.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> &amp;&amp;
<entry><replaceable>e1</replaceable> <literal>&amp;&amp;</literal>
<replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>Logical AND.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> ||
<entry><replaceable>e1</replaceable> <literal>||</literal>
<replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>Logical OR.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> ->
<entry><replaceable>e1</replaceable> <literal>-></literal>
<replaceable>e2</replaceable></entry>
<entry>none</entry>
<entry>Logical implication (equivalent to
@ -1662,7 +1707,17 @@ impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ];
</varlistentry>
<varlistentry><term><varname>preferLocalBuild</varname></term>
<listitem><para>If this attribute is set to
<literal>true</literal> and <link
linkend="chap-distributed-builds">distributed building is
enabled</link>, then, if possible, perform this build locally
instead of forwarding it to a remote machine. This is appropriate
for trivial builders where the cost of doing a remote build would
exceed the cost of building locally.</para></listitem>
</varlistentry>
</variablelist>