aboutsummaryrefslogtreecommitdiff
path: root/doc/manual
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual')
-rw-r--r--doc/manual/Makefile.am11
-rw-r--r--doc/manual/book.xml32
-rw-r--r--doc/manual/installation.xml18
-rw-r--r--doc/manual/introduction.xml352
-rw-r--r--doc/manual/nix-instantiate-reference.xml (renamed from doc/manual/fix-reference.xml)6
-rw-r--r--doc/manual/nix-reference.xml444
-rw-r--r--doc/manual/nix-store-reference.xml444
7 files changed, 643 insertions, 664 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 8b3060ac7..8e2fff208 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -3,16 +3,17 @@ ENV = SGML_CATALOG_FILES=$(docbookcatalog)
XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs
XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs
-SOURCES = book.xml introduction.xml installation.xml nix-reference.xml \
+SOURCES = book.xml introduction.xml installation.xml \
+ nix-store-reference.xml \
troubleshooting.xml bugs.xml
book.is-valid: $(SOURCES)
$(XMLLINT) --noout --valid book.xml
touch $@
-man1_MANS = nix.1 fix.1
+man1_MANS = nix-store.1 nix-instantiate.1
-man nix.1 fix.1: $(SOURCES) book.is-valid
+man $(MANS): $(SOURCES) book.is-valid
$(XSLTPROC) $(docbookxsl)/manpages/docbook.xsl book.xml
book.html: $(SOURCES) book.is-valid
@@ -24,4 +25,6 @@ install-data-local: book.html
$(INSTALL) -d $(datadir)/nix/manual
$(INSTALL_DATA) book.html $(datadir)/nix/manual
-EXTRA_DIST = $(SOURCES) book.html nix.1 fix.1 book.is-valid
+EXTRA_DIST = $(SOURCES) book.html book.is-valid $(MANS)
+
+DISTCLEANFILES = book.html book.is-valid $(MANS)
diff --git a/doc/manual/book.xml b/doc/manual/book.xml
index a2035fca7..1dc69d004 100644
--- a/doc/manual/book.xml
+++ b/doc/manual/book.xml
@@ -5,8 +5,8 @@
[
<!ENTITY introduction SYSTEM "introduction.xml">
<!ENTITY installation SYSTEM "installation.xml">
-<!ENTITY nix-reference SYSTEM "nix-reference.xml">
-<!ENTITY fix-reference SYSTEM "fix-reference.xml">
+<!ENTITY nix-store-reference SYSTEM "nix-store-reference.xml">
+<!ENTITY nix-instantiate-reference SYSTEM "nix-instantiate-reference.xml">
<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
<!ENTITY bugs SYSTEM "bugs.xml">
]>
@@ -28,34 +28,10 @@
&introduction;
&installation;
- <chapter>
- <title>A Guided Tour</title>
- <para>
- </para>
- </chapter>
-
- <chapter>
- <title>Nix Syntax and Semantics</title>
- <para>
- </para>
- </chapter>
-
- <chapter>
- <title>Fix Language Reference</title>
- <para>
- </para>
- </chapter>
-
- <chapter>
- <title>Writing Builders</title>
- <para>
- </para>
- </chapter>
-
<appendix>
<title>Command Reference</title>
- &nix-reference;
- &fix-reference;
+ &nix-store-reference;
+ &nix-instantiate-reference;
</appendix>
&troubleshooting;
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index bec9ebb21..f9bd0a742 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -20,8 +20,8 @@
<para>
Nix can be obtained from its <ulink
- url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk'>Subversion
- repository</ulink>. For example, the following command will check out
+ url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk'>Subversion
+ repository</ulink>. For example, the following command will check out
the latest revision into a directory called <filename>nix</filename>:
</para>
@@ -30,11 +30,11 @@ $ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk nix</sc
<para>
Likewise, specific releases can be obtained from the <ulink
- url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/tags'>tags
- directory</ulink> of the repository. If you don't have Subversion, you
+ url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/tags'>tags
+ directory</ulink> of the repository. If you don't have Subversion, you
can download a <ulink
- url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed
- tar-file</ulink> of the latest revision of the repository.
+ url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed
+ tar-file</ulink> of the latest revision of the repository.
</para>
</sect1>
@@ -63,9 +63,9 @@ $ make install</screen>
<warning>
<para>
- It is advisable <emphasis>not</emphasis> to change the installation
- prefix, since doing so will in all likelihood make it impossible to use
- derivates built on other systems.
+ It is advisable <emphasis>not</emphasis> to change the installation
+ prefix, since doing so will in all likelihood make it impossible to use
+ derivates built on other systems.
</para>
</warning>
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
index 5eea76459..feabeef9c 100644
--- a/doc/manual/introduction.xml
+++ b/doc/manual/introduction.xml
@@ -15,74 +15,74 @@
<title>Build management</title>
<para>
- Build management tools are used to perform <emphasis>software
- builds</emphasis>, that is, the construction of derived products
- (<emphasis>derivates)</emphasis>) such as executable programs from
- source code. A commonly used build tool is Make, which is a standard
- tool on Unix systems. These tools have to deal with several issues:
- <itemizedlist>
-
- <listitem>
- <para>
- <emphasis>Efficiency</emphasis>. Since building large systems
- can take a substantial amount of time, it is desirable that build
- steps that have been performed in the past are not repeated
- unnecessarily, i.e., if a new build differs from a previous build
- only with respect to certain sources, then only the build steps
- that (directly or indirectly) <emphasis>depend</emphasis> on
- those sources should be redone.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>Correctness</emphasis> is this context means that the
- derivates produced by a build are always consistent with the
- sources, that is, they are equal to what we would get if we were
- to build the derivates from those sources. This requirement is
- trivially met when we do a full, unconditional build, but is far
- from trivial under the requirement of efficiency, since it is not
- easy to determine which derivates are affected by a change to a
- source.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>Variability</emphasis> is the property that a software
- system can be built in a (potentially large) number of variants.
- Variation exists both in <emphasis>time</emphasis>---the
- evolution of different versions of an artifact---and in
- <emphasis>space</emphasis>---the artifact might have
- configuration options that lead to variants that differ in the
- features they support (for example, a system might be built with
- or without debugging information).
- </para>
-
- <para>
- Build managers historically have had good support for variation
- in time (rebuilding the system in an intelligent way when sources
- change is one of the primary reasons to use a build manager), but
- not always for variation in space. For example,
- <command>make</command> will not automatically ensure that
- variant builds are properly isolated from each other (they will
- in fact overwrite each other unless special precautions are
- taken).
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>High-level system modelling language</emphasis>. The
- language in which one describes what and how derivates are to be
- produced should have sufficient abstraction facilities to make it
- easy to specify the derivation of even very large systems. Also,
- the language should be <emphasis>modular</emphasis> to enable
- components from possible different sources to be easily combined.
- </para>
- </listitem>
-
- </itemizedlist>
+ Build management tools are used to perform <emphasis>software
+ builds</emphasis>, that is, the construction of derived products
+ (<emphasis>derivates)</emphasis>) such as executable programs from
+ source code. A commonly used build tool is Make, which is a standard
+ tool on Unix systems. These tools have to deal with several issues:
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <emphasis>Efficiency</emphasis>. Since building large systems
+ can take a substantial amount of time, it is desirable that build
+ steps that have been performed in the past are not repeated
+ unnecessarily, i.e., if a new build differs from a previous build
+ only with respect to certain sources, then only the build steps
+ that (directly or indirectly) <emphasis>depend</emphasis> on
+ those sources should be redone.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Correctness</emphasis> is this context means that the
+ derivates produced by a build are always consistent with the
+ sources, that is, they are equal to what we would get if we were
+ to build the derivates from those sources. This requirement is
+ trivially met when we do a full, unconditional build, but is far
+ from trivial under the requirement of efficiency, since it is not
+ easy to determine which derivates are affected by a change to a
+ source.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Variability</emphasis> is the property that a software
+ system can be built in a (potentially large) number of variants.
+ Variation exists both in <emphasis>time</emphasis>---the
+ evolution of different versions of an artifact---and in
+ <emphasis>space</emphasis>---the artifact might have
+ configuration options that lead to variants that differ in the
+ features they support (for example, a system might be built with
+ or without debugging information).
+ </para>
+
+ <para>
+ Build managers historically have had good support for variation
+ in time (rebuilding the system in an intelligent way when sources
+ change is one of the primary reasons to use a build manager), but
+ not always for variation in space. For example,
+ <command>make</command> will not automatically ensure that
+ variant builds are properly isolated from each other (they will
+ in fact overwrite each other unless special precautions are
+ taken).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>High-level system modelling language</emphasis>. The
+ language in which one describes what and how derivates are to be
+ produced should have sufficient abstraction facilities to make it
+ easy to specify the derivation of even very large systems. Also,
+ the language should be <emphasis>modular</emphasis> to enable
+ components from possible different sources to be easily combined.
+ </para>
+ </listitem>
+
+ </itemizedlist>
</para>
</sect2>
@@ -91,33 +91,33 @@
<title>Package management</title>
<para>
- After software has been built, is must also be
- <emphasis>deployed</emphasis> in the intended target environment, e.g.,
- the user's workstation. Examples include the Red Hat package manager
- (RPM), Microsoft's MSI, and so on. Here also we have several issues to
- contend with:
- <itemizedlist>
- <listitem>
- <para>
- The <emphasis>creation</emphasis> of packages from some formal
- description of what artifacts should be distributed in the
- package.
- </para>
- </listitem>
- <listitem>
- <para>
- The <emphasis>deployment</emphasis> of packages, that is, the
- mechanism by which we get them onto the intended target
- environment. This can be as simple as copying a file, but
- complexity comes from the wide range of possible installation
- media (such as a network install), and the scalability of the
- process (if a program must be installed on a thousand systems, we
- do not want to visit each system and perform some manual steps to
- install the program on that system; that is, the complexity for
- the system administrator should be constant, not linear).
- </para>
- </listitem>
- </itemizedlist>
+ After software has been built, is must also be
+ <emphasis>deployed</emphasis> in the intended target environment, e.g.,
+ the user's workstation. Examples include the Red Hat package manager
+ (RPM), Microsoft's MSI, and so on. Here also we have several issues to
+ contend with:
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <emphasis>creation</emphasis> of packages from some formal
+ description of what artifacts should be distributed in the
+ package.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <emphasis>deployment</emphasis> of packages, that is, the
+ mechanism by which we get them onto the intended target
+ environment. This can be as simple as copying a file, but
+ complexity comes from the wide range of possible installation
+ media (such as a network install), and the scalability of the
+ process (if a program must be installed on a thousand systems, we
+ do not want to visit each system and perform some manual steps to
+ install the program on that system; that is, the complexity for
+ the system administrator should be constant, not linear).
+ </para>
+ </listitem>
+ </itemizedlist>
</para>
</sect2>
@@ -136,95 +136,95 @@
<itemizedlist>
<listitem>
- <para>
- <emphasis>Reliable dependencies.</emphasis> Builds of file system
- objects depend on other file system object, such as source files,
- tools, and so on. We would like to ensure that a build does not
- refer to any objects that have not been declared as inputs for that
- build. This is important for several reasons. First, if any of the
- inputs change, we need to rebuild the things that depend on them to
- maintain consistency between sources and derivates. Second, when we
- <emphasis>deploy</emphasis> file system objects (that is, copy them
- to a different system), we want to be certain that we copy everything
- that we need.
- </para>
-
- <para>
- Nix ensures this by building and storing file system objects in paths
- that are infeasible to predict in advance. For example, the
- artifacts of a package <literal>X</literal> might be stored in
- <filename>/nix/store/d58a0606ed616820de291d594602665d-X</filename>,
- rather than in, say, <filename>/usr/lib</filename>. The path
- component <filename>d58a...</filename> is actually a cryptographic
- hash of all the inputs (i.e., sources, requisites, and build flags)
- used in building <literal>X</literal>, and as such is very fragile:
- any change to the inputs will change the hash. Therefore it is not
- sensible to <emphasis>hard-code</emphasis> such a path into the build
- scripts of a package <literal>Y</literal> that uses
- <literal>X</literal> (as does happen with <quote>fixed</quote> paths
- such as <filename>/usr/lib</filename>). Rather, the build script of
- package <literal>Y</literal> is parameterised with the actual
- location of <literal>X</literal>, which is supplied by the Nix
- system.
- </para>
+ <para>
+ <emphasis>Reliable dependencies.</emphasis> Builds of file system
+ objects depend on other file system object, such as source files,
+ tools, and so on. We would like to ensure that a build does not
+ refer to any objects that have not been declared as inputs for that
+ build. This is important for several reasons. First, if any of the
+ inputs change, we need to rebuild the things that depend on them to
+ maintain consistency between sources and derivates. Second, when we
+ <emphasis>deploy</emphasis> file system objects (that is, copy them
+ to a different system), we want to be certain that we copy everything
+ that we need.
+ </para>
+
+ <para>
+ Nix ensures this by building and storing file system objects in paths
+ that are infeasible to predict in advance. For example, the
+ artifacts of a package <literal>X</literal> might be stored in
+ <filename>/nix/store/d58a0606ed616820de291d594602665d-X</filename>,
+ rather than in, say, <filename>/usr/lib</filename>. The path
+ component <filename>d58a...</filename> is actually a cryptographic
+ hash of all the inputs (i.e., sources, requisites, and build flags)
+ used in building <literal>X</literal>, and as such is very fragile:
+ any change to the inputs will change the hash. Therefore it is not
+ sensible to <emphasis>hard-code</emphasis> such a path into the build
+ scripts of a package <literal>Y</literal> that uses
+ <literal>X</literal> (as does happen with <quote>fixed</quote> paths
+ such as <filename>/usr/lib</filename>). Rather, the build script of
+ package <literal>Y</literal> is parameterised with the actual
+ location of <literal>X</literal>, which is supplied by the Nix
+ system.
+ </para>
</listitem>
<listitem>
- <para>
- <emphasis>Support for variability.</emphasis>
- </para>
-
- <para>
- As stated above, the path name of a file system object contain a
- cryptographic hash of all inputs involved in building it. A change to
- any of the inputs will cause the hash to change--and by extension,
- the path name. These inputs include both sources (variation in time)
- and configuration options (variation in space). Therefore variants
- of the same package don't clash---they can co-exist peacefully within
- the same file system. So thanks to Nix's mechanism for reliably
- dealing with dependencies, we obtain management of variants for free
- (or, to quote Simon Peyton-Jone, it's not free, but it has already
- been paid for).
- </para>
+ <para>
+ <emphasis>Support for variability.</emphasis>
+ </para>
+
+ <para>
+ As stated above, the path name of a file system object contain a
+ cryptographic hash of all inputs involved in building it. A change to
+ any of the inputs will cause the hash to change--and by extension,
+ the path name. These inputs include both sources (variation in time)
+ and configuration options (variation in space). Therefore variants
+ of the same package don't clash---they can co-exist peacefully within
+ the same file system. So thanks to Nix's mechanism for reliably
+ dealing with dependencies, we obtain management of variants for free
+ (or, to quote Simon Peyton-Jone, it's not free, but it has already
+ been paid for).
+ </para>
</listitem>
<listitem>
- <para>
- <emphasis>Transparent source/binary deployment.</emphasis>
- </para>
+ <para>
+ <emphasis>Transparent source/binary deployment.</emphasis>
+ </para>
</listitem>
<listitem>
- <para>
- <emphasis>Easy configuration duplication.</emphasis>
- </para>
+ <para>
+ <emphasis>Easy configuration duplication.</emphasis>
+ </para>
</listitem>
<listitem>
- <para>
- <emphasis>Automatic storage management.</emphasis>
- </para>
+ <para>
+ <emphasis>Automatic storage management.</emphasis>
+ </para>
</listitem>
<listitem>
- <para>
- <emphasis>Atomic upgrades and rollbacks.</emphasis>
- </para>
+ <para>
+ <emphasis>Atomic upgrades and rollbacks.</emphasis>
+ </para>
</listitem>
<listitem>
- <para>
- <emphasis>Support for many simultaneous configurations.</emphasis>
- </para>
+ <para>
+ <emphasis>Support for many simultaneous configurations.</emphasis>
+ </para>
</listitem>
<listitem>
- <para>
- <emphasis>Portability.</emphasis> Nix is quite portable. Contrary
- to build systems like those in, e.g., Vesta and ClearCase [sic?], it
- does not rely on operating system extensions.
- </para>
+ <para>
+ <emphasis>Portability.</emphasis> Nix is quite portable. Contrary
+ to build systems like those in, e.g., Vesta and ClearCase [sic?], it
+ does not rely on operating system extensions.
+ </para>
</listitem>
</itemizedlist>
@@ -236,20 +236,20 @@
<itemizedlist>
<listitem>
- <para>
- <emphasis>Build management.</emphasis> In principle it is already
- possible to do build management using Fix (by writing builders that
- perform appropriate build steps), but the Fix language is not yet
- powerful enough to make this pleasant. The <ulink
- url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>
- should be retargeted to produce Nix expressions, or alternatively,
- extend Fix with Maak's semantics and concrete syntax (since Fix needs
- a concrete syntax anyway). Another interesting idea is to write a
- <command>make</command> implementation that uses Nix as a back-end to
- support <ulink
- url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink>
- build files.
- </para>
+ <para>
+ <emphasis>Build management.</emphasis> In principle it is already
+ possible to do build management using Fix (by writing builders that
+ perform appropriate build steps), but the Fix language is not yet
+ powerful enough to make this pleasant. The <ulink
+ url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>
+ should be retargeted to produce Nix expressions, or alternatively,
+ extend Fix with Maak's semantics and concrete syntax (since Fix needs
+ a concrete syntax anyway). Another interesting idea is to write a
+ <command>make</command> implementation that uses Nix as a back-end to
+ support <ulink
+ url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink>
+ build files.
+ </para>
</listitem>
</itemizedlist>
diff --git a/doc/manual/fix-reference.xml b/doc/manual/nix-instantiate-reference.xml
index aac1be648..2e2749e43 100644
--- a/doc/manual/fix-reference.xml
+++ b/doc/manual/nix-instantiate-reference.xml
@@ -1,6 +1,6 @@
<refentry>
<refnamediv>
- <refname>fix</refname>
+ <refname>nix-instantiate</refname>
<refpurpose>generate Nix expressions from a high-level description</refpurpose>
</refnamediv>
@@ -8,8 +8,8 @@
<cmdsynopsis>
<command>fix</command>
<group choice='opt' rep='repeat'>
- <arg><option>--verbose</option></arg>
- <arg><option>-v</option></arg>
+ <arg><option>--verbose</option></arg>
+ <arg><option>-v</option></arg>
</group>
<arg rep='repeat'><replaceable>files</replaceable></arg>
</cmdsynopsis>
diff --git a/doc/manual/nix-reference.xml b/doc/manual/nix-reference.xml
deleted file mode 100644
index d9c78ff07..000000000
--- a/doc/manual/nix-reference.xml
+++ /dev/null
@@ -1,444 +0,0 @@
-<refentry>
- <refnamediv>
- <refname>nix</refname>
- <refpurpose>manipulate or query the Nix store</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>nix</command>
- <group choice='opt'>
- <arg><option>--path</option></arg>
- <arg><option>-p</option></arg>
- </group>
- <group choice='opt' rep='repeat'>
- <arg><option>--verbose</option></arg>
- <arg><option>-v</option></arg>
- </group>
- <group choice='opt' rep='repeat'>
- <arg><option>--keep-failed</option></arg>
- <arg><option>-K</option></arg>
- </group>
- <arg choice='plain'><replaceable>operation</replaceable></arg>
- <arg rep='repeat'><replaceable>options</replaceable></arg>
- <arg rep='repeat'><replaceable>arguments</replaceable></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
-
- <para>
- The command <command>nix</command> provides access to the Nix store. This
- is the (set of) path(s) where Nix expressions and the file system objects
- built by them are stored.
- </para>
-
- <para>
- <command>nix</command> has many subcommands called
- <emphasis>operations</emphasis>. These are individually documented
- below. Exactly one operation must always be provided.
- </para>
-
- </refsect1>
-
- <refsect1>
- <title>Common Options</title>
-
- <para>
- In this section the options that are common to all Nix operations are
- listed. These options are allowed for every subcommand (although they
- may not always have an effect).
- </para>
-
- <variablelist>
-
- <varlistentry>
- <term><option>--path</option></term>
- <listitem>
- <para>
- Indicates that any identifier arguments to the operation are paths
- in the store rather than identifiers.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--verbose</option></term>
- <listitem>
- <para>
- Increases the level of verbosity of diagnostic messages printed on
- standard error. For each Nix operation, the information printed on
- standard output is well-defined and specified below in the
- respective sections. Any diagnostic information is printed on
- standard error, never on standard output.
- </para>
-
- <para>
- This option may be specified repeatedly. Currently, the following
- verbosity levels exist:
- </para>
-
- <variablelist>
- <varlistentry>
- <term>0</term>
- <listitem>
- <para>
- Print error messages only.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>1</term>
- <listitem>
- <para>
- Print informational messages.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>2</term>
- <listitem>
- <para>
- Print even more informational messages.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>3</term>
- <listitem>
- <para>
- Print messages that should only be useful for debugging.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>4</term>
- <listitem>
- <para>
- <quote>Vomit mode</quote>: print vast amounts of debug
- information.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--keep-failed</option></term>
- <listitem>
- <para>
- Specifies that in case of a build failure, the temporary directory
- (usually in <filename>/tmp</filename>) in which the build takes
- place should not be deleted. The path of the build directory is
- printed as an informational message.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </refsect1>
-
-
- <!--######################################################################-->
-
- <refsect1>
- <title>Operation <option>--install</option></title>
-
- <refsect2>
- <title>Synopsis</title>
- <cmdsynopsis>
- <command>nix</command>
- <group>
- <arg><option>--install</option></arg>
- <arg><option>-i</option></arg>
- </group>
- <arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg>
- </cmdsynopsis>
- </refsect2>
-
- <refsect2>
- <title>Description</title>
-
- <para>
- The operation <option>--install</option> realises the Nix expressions
- identified by <replaceable>ids</replaceable> in the file system. If
- these expressions are derivation expressions, they are first
- normalised. That is, their target paths are are built, unless a normal
- form is already known.
- </para>
-
- <para>
- The identifiers of the normal forms of the given Nix expressions are
- printed on standard output.
- </para>
-
- </refsect2>
-
- </refsect1>
-
-
- <!--######################################################################-->
-
- <refsect1>
- <title>Operation <option>--delete</option></title>
-
- <refsect2>
- <title>Synopsis</title>
- <cmdsynopsis>
- <command>nix</command>
- <group>
- <arg><option>--delete</option></arg>
- <arg><option>-d</option></arg>
- </group>
- <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
- </cmdsynopsis>
- </refsect2>
-
- <refsect2>
- <title>Description</title>
-
- <para>
- The operation <option>--delete</option> unconditionally deletes the
- paths <replaceable>paths</replaceable> from the Nix store. It is an
- error to attempt to delete paths outside of the store.
- </para>
-
- <warning>
- <para>
- This operation should almost never be called directly, since no
- attempt is made to verify that no references exist to the paths to
- be deleted. Therefore, careless deletion can result in an
- inconsistent system. Deletion of paths in the store is done by the
- garbage collector (which uses <option>--delete</option> to delete
- unreferenced paths).
-
- </para>
- </warning>
-
- </refsect2>
-
- </refsect1>
-
-
- <!--######################################################################-->
-
- <refsect1>
- <title>Operation <option>--query</option></title>
-
- <refsect2>
- <title>Synopsis</title>
- <cmdsynopsis>
- <command>nix</command>
- <group>
- <arg><option>--query</option></arg>
- <arg><option>-q</option></arg>
- </group>
- <group>
- <group>
- <arg><option>--list</option></arg>
- <arg><option>-l</option></arg>
- </group>
- <group>
- <arg><option>--requisites</option></arg>
- <arg><option>-r</option></arg>
- </group>
- <group>
- <arg><option>--expansion</option></arg>
- <arg><option>-e</option></arg>
- </group>
- <group>
- <arg><option>--graph</option></arg>
- <arg><option>-g</option></arg>
- </group>
- </group>
- <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
- </cmdsynopsis>
- </refsect2>
-
- <refsect2>
- <title>Description</title>
-
- <para>
- The operation <option>--query</option> displays various bits of
- information about Nix expressions or paths in the store. The queries
- are described in <xref linkend='nixref-queries' />. At most one query
- can be specified; the default query is <option>--list</option>.
- </para>
-
- </refsect2>
-
- <refsect2 id='nixref-queries'>
- <title>Queries</title>
-
- <variablelist>
-
- <varlistentry>
- <term><option>--list</option></term>
- <listitem>
- <para>
- Prints out the target paths of the Nix expressions indicated by
- the identifiers <replaceable>args</replaceable>. In the case of
- a derivation expression, these are the paths that will be
- produced by the builder of the expression. In the case of a
- slice expression, these are the root paths (which are generally
- the paths that were produced by the builder of the derivation
- expression of which the slice is a normal form).
- </para>
-
- <para>
- This query has one option:
- </para>
-
- <variablelist>
-
- <varlistentry>
- <term><option>--normalise</option></term>
- <listitem>
- <para>
- Causes the target paths of the <emphasis>normal
- forms</emphasis> of the expressions to be printed, rather
- than the target paths of the expressions themselves.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--requisites</option></term>
- <listitem>
- <para>
- Prints out the requisite paths of the Nix expressions indicated
- by the identifiers <replaceable>args</replaceable>. The
- requisite paths of a Nix expression are the paths that need to be
- present in the system to be able to realise the expression. That
- is, they form the <emphasis>closure</emphasis> of the expression
- in the file system (i.e., no path in the set of requisite paths
- points to anything outside the set of requisite paths).
- </para>
-
- <para>
- The notion of requisite paths is very useful when one wants to
- distribute Nix expressions. Since they form a closure, they are
- the only paths one needs to distribute to another system to be
- able to realise the expression on the other system.
- </para>
-
- <para>
- This query is generally used to implement various kinds of
- distribution. A <emphasis>source distribution</emphasis> is
- obtained by distributing the requisite paths of a derivation
- expression. A <emphasis>binary distribution</emphasis> is
- obtained by distributing the requisite paths of a slice
- expression (i.e., the normal form of a derivation expression; you
- can directly specify the identifier of the slice expression, or
- use <option>--normalise</option> and specify the identifier of a
- derivation expression). A <emphasis>cache
- distribution</emphasis> is obtained by distributing the
- requisite paths of a derivation expression and specifying the
- option <option>--include-successors</option>. This will include
- not just the paths of a source and binary distribution, but also
- all expressions and paths of subterms of the source. This is
- useful if one wants to realise on the target system a Nix
- expression that is similar but not quite the same as the one
- being distributed, since any common subterms will be reused.
- </para>
-
- <para>
- This query has a number of options:
- </para>
-
- <variablelist>
-
- <varlistentry>
- <term><option>--normalise</option></term>
- <listitem>
- <para>
- Causes the requisite paths of the <emphasis>normal
- forms</emphasis> of the expressions to be printed, rather
- than the requisite paths of the expressions themselves.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--exclude-exprs</option></term>
- <listitem>
- <para>
- Excludes the paths of Nix expressions. This causes the
- closure property to be lost, that is, the resulting set of
- paths is not enough to ensure realisibility.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--include-successors</option></term>
- <listitem>
- <para>
- Also include the requisites of successors (normal forms).
- Only the requisites of <emphasis>known</emphasis>
- successors are included, i.e., the normal forms of
- derivation expressions that have never been normalised will
- not be included.
- </para>
-
- <para>
- Note that not just the successor of a derivation expression
- will be included, but also the successors of all input
- expressions of that derivation expression. I.e., all
- normal forms of subterms involved in the normalisation of
- the top-level term are included.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--expansion</option></term>
- <listitem>
- <para>
- For each identifier in <replaceable>args</replaceable>, prints
- all expansions of that identifier, that is, all paths whose
- current content matches the identifier.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--graph</option></term>
- <listitem>
- <para>
- Prints a graph of the closure of the expressions identified by
- <replaceable>args</replaceable> in the format of the
- <command>dot</command> tool of AT&amp;T's GraphViz package.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </refsect2>
-
- </refsect1>
-
-
-</refentry>
-
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "refentry")
-end:
--->
diff --git a/doc/manual/nix-store-reference.xml b/doc/manual/nix-store-reference.xml
new file mode 100644
index 000000000..686fe4c15
--- /dev/null
+++ b/doc/manual/nix-store-reference.xml
@@ -0,0 +1,444 @@
+<refentry>
+ <refnamediv>
+ <refname>nix-store</refname>
+ <refpurpose>manipulate or query the Nix store</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>nix-store</command>
+ <group choice='opt'>
+ <arg><option>--path</option></arg>
+ <arg><option>-p</option></arg>
+ </group>
+ <group choice='opt' rep='repeat'>
+ <arg><option>--verbose</option></arg>
+ <arg><option>-v</option></arg>
+ </group>
+ <group choice='opt' rep='repeat'>
+ <arg><option>--keep-failed</option></arg>
+ <arg><option>-K</option></arg>
+ </group>
+ <arg choice='plain'><replaceable>operation</replaceable></arg>
+ <arg rep='repeat'><replaceable>options</replaceable></arg>
+ <arg rep='repeat'><replaceable>arguments</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ The command <command>nix</command> provides access to the Nix store. This
+ is the (set of) path(s) where Nix expressions and the file system objects
+ built by them are stored.
+ </para>
+
+ <para>
+ <command>nix</command> has many subcommands called
+ <emphasis>operations</emphasis>. These are individually documented
+ below. Exactly one operation must always be provided.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Common Options</title>
+
+ <para>
+ In this section the options that are common to all Nix operations are
+ listed. These options are allowed for every subcommand (although they
+ may not always have an effect).
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--path</option></term>
+ <listitem>
+ <para>
+ Indicates that any identifier arguments to the operation are paths
+ in the store rather than identifiers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--verbose</option></term>
+ <listitem>
+ <para>
+ Increases the level of verbosity of diagnostic messages printed on
+ standard error. For each Nix operation, the information printed on
+ standard output is well-defined and specified below in the
+ respective sections. Any diagnostic information is printed on
+ standard error, never on standard output.
+ </para>
+
+ <para>
+ This option may be specified repeatedly. Currently, the following
+ verbosity levels exist:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>
+ Print error messages only.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>1</term>
+ <listitem>
+ <para>
+ Print informational messages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>2</term>
+ <listitem>
+ <para>
+ Print even more informational messages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>3</term>
+ <listitem>
+ <para>
+ Print messages that should only be useful for debugging.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>4</term>
+ <listitem>
+ <para>
+ <quote>Vomit mode</quote>: print vast amounts of debug
+ information.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--keep-failed</option></term>
+ <listitem>
+ <para>
+ Specifies that in case of a build failure, the temporary directory
+ (usually in <filename>/tmp</filename>) in which the build takes
+ place should not be deleted. The path of the build directory is
+ printed as an informational message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect1>
+
+
+ <!--######################################################################-->
+
+ <refsect1>
+ <title>Operation <option>--install</option></title>
+
+ <refsect2>
+ <title>Synopsis</title>
+ <cmdsynopsis>
+ <command>nix</command>
+ <group>
+ <arg><option>--install</option></arg>
+ <arg><option>-i</option></arg>
+ </group>
+ <arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg>
+ </cmdsynopsis>
+ </refsect2>
+
+ <refsect2>
+ <title>Description</title>
+
+ <para>
+ The operation <option>--install</option> realises the Nix expressions
+ identified by <replaceable>ids</replaceable> in the file system. If
+ these expressions are derivation expressions, they are first
+ normalised. That is, their target paths are are built, unless a normal
+ form is already known.
+ </para>
+
+ <para>
+ The identifiers of the normal forms of the given Nix expressions are
+ printed on standard output.
+ </para>
+
+ </refsect2>
+
+ </refsect1>
+
+
+ <!--######################################################################-->
+
+ <refsect1>
+ <title>Operation <option>--delete</option></title>
+
+ <refsect2>
+ <title>Synopsis</title>
+ <cmdsynopsis>
+ <command>nix</command>
+ <group>
+ <arg><option>--delete</option></arg>
+ <arg><option>-d</option></arg>
+ </group>
+ <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+ </cmdsynopsis>
+ </refsect2>
+
+ <refsect2>
+ <title>Description</title>
+
+ <para>
+ The operation <option>--delete</option> unconditionally deletes the
+ paths <replaceable>paths</replaceable> from the Nix store. It is an
+ error to attempt to delete paths outside of the store.
+ </para>
+
+ <warning>
+ <para>
+ This operation should almost never be called directly, since no
+ attempt is made to verify that no references exist to the paths to
+ be deleted. Therefore, careless deletion can result in an
+ inconsistent system. Deletion of paths in the store is done by the
+ garbage collector (which uses <option>--delete</option> to delete
+ unreferenced paths).
+
+ </para>
+ </warning>
+
+ </refsect2>
+
+ </refsect1>
+
+
+ <!--######################################################################-->
+
+ <refsect1>
+ <title>Operation <option>--query</option></title>
+
+ <refsect2>
+ <title>Synopsis</title>
+ <cmdsynopsis>
+ <command>nix</command>
+ <group>
+ <arg><option>--query</option></arg>
+ <arg><option>-q</option></arg>
+ </group>
+ <group>
+ <group>
+ <arg><option>--list</option></arg>
+ <arg><option>-l</option></arg>
+ </group>
+ <group>
+ <arg><option>--requisites</option></arg>
+ <arg><option>-r</option></arg>
+ </group>
+ <group>
+ <arg><option>--expansion</option></arg>
+ <arg><option>-e</option></arg>
+ </group>
+ <group>
+ <arg><option>--graph</option></arg>
+ <arg><option>-g</option></arg>
+ </group>
+ </group>
+ <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
+ </cmdsynopsis>
+ </refsect2>
+
+ <refsect2>
+ <title>Description</title>
+
+ <para>
+ The operation <option>--query</option> displays various bits of
+ information about Nix expressions or paths in the store. The queries
+ are described in <xref linkend='nixref-queries' />. At most one query
+ can be specified; the default query is <option>--list</option>.
+ </para>
+
+ </refsect2>
+
+ <refsect2 id='nixref-queries'>
+ <title>Queries</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--list</option></term>
+ <listitem>
+ <para>
+ Prints out the target paths of the Nix expressions indicated by
+ the identifiers <replaceable>args</replaceable>. In the case of
+ a derivation expression, these are the paths that will be
+ produced by the builder of the expression. In the case of a
+ slice expression, these are the root paths (which are generally
+ the paths that were produced by the builder of the derivation
+ expression of which the slice is a normal form).
+ </para>
+
+ <para>
+ This query has one option:
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--normalise</option></term>
+ <listitem>
+ <para>
+ Causes the target paths of the <emphasis>normal
+ forms</emphasis> of the expressions to be printed, rather
+ than the target paths of the expressions themselves.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--requisites</option></term>
+ <listitem>
+ <para>
+ Prints out the requisite paths of the Nix expressions indicated
+ by the identifiers <replaceable>args</replaceable>. The
+ requisite paths of a Nix expression are the paths that need to be
+ present in the system to be able to realise the expression. That
+ is, they form the <emphasis>closure</emphasis> of the expression
+ in the file system (i.e., no path in the set of requisite paths
+ points to anything outside the set of requisite paths).
+ </para>
+
+ <para>
+ The notion of requisite paths is very useful when one wants to
+ distribute Nix expressions. Since they form a closure, they are
+ the only paths one needs to distribute to another system to be
+ able to realise the expression on the other system.
+ </para>
+
+ <para>
+ This query is generally used to implement various kinds of
+ distribution. A <emphasis>source distribution</emphasis> is
+ obtained by distributing the requisite paths of a derivation
+ expression. A <emphasis>binary distribution</emphasis> is
+ obtained by distributing the requisite paths of a slice
+ expression (i.e., the normal form of a derivation expression; you
+ can directly specify the identifier of the slice expression, or
+ use <option>--normalise</option> and specify the identifier of a
+ derivation expression). A <emphasis>cache
+ distribution</emphasis> is obtained by distributing the
+ requisite paths of a derivation expression and specifying the
+ option <option>--include-successors</option>. This will include
+ not just the paths of a source and binary distribution, but also
+ all expressions and paths of subterms of the source. This is
+ useful if one wants to realise on the target system a Nix
+ expression that is similar but not quite the same as the one
+ being distributed, since any common subterms will be reused.
+ </para>
+
+ <para>
+ This query has a number of options:
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>--normalise</option></term>
+ <listitem>
+ <para>
+ Causes the requisite paths of the <emphasis>normal
+ forms</emphasis> of the expressions to be printed, rather
+ than the requisite paths of the expressions themselves.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--exclude-exprs</option></term>
+ <listitem>
+ <para>
+ Excludes the paths of Nix expressions. This causes the
+ closure property to be lost, that is, the resulting set of
+ paths is not enough to ensure realisibility.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--include-successors</option></term>
+ <listitem>
+ <para>
+ Also include the requisites of successors (normal forms).
+ Only the requisites of <emphasis>known</emphasis>
+ successors are included, i.e., the normal forms of
+ derivation expressions that have never been normalised will
+ not be included.
+ </para>
+
+ <para>
+ Note that not just the successor of a derivation expression
+ will be included, but also the successors of all input
+ expressions of that derivation expression. I.e., all
+ normal forms of subterms involved in the normalisation of
+ the top-level term are included.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--expansion</option></term>
+ <listitem>
+ <para>
+ For each identifier in <replaceable>args</replaceable>, prints
+ all expansions of that identifier, that is, all paths whose
+ current content matches the identifier.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--graph</option></term>
+ <listitem>
+ <para>
+ Prints a graph of the closure of the expressions identified by
+ <replaceable>args</replaceable> in the format of the
+ <command>dot</command> tool of AT&amp;T's GraphViz package.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect2>
+
+ </refsect1>
+
+
+</refentry>
+
+
+<!--
+local variables:
+sgml-parent-document: ("book.xml" "refentry")
+end:
+-->