lix-project/lix
20
57
Fork 31
Code Issues 349 Code Review (Gerrit) Projects 3 Releases Wiki Activity

* Refactoring.

Browse source 
* Convert tabs to spaces.
This commit is contained in:
Eelco Dolstra 2003-11-26 11:24:13 +00:00
parent bd0ce1a4be
commit 2a4bac5459
7 changed files with 636 additions and 657 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
doc/manual/Makefile.am
View file

@ -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)

32
doc/manual/book.xml
View file

@ -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;

18
doc/manual/installation.xml
View file

@ -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>

336
doc/manual/introduction.xml
View file

@ -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>
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>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>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>
<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>
<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>
<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>
</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>
<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>
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>
<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>
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>

6
doc/manual/fix-reference.xml → doc/manual/nix-instantiate-reference.xml
View file

@ -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>

444
doc/manual/nix-reference.xml
View file

@ -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:
-->

444
doc/manual/nix-store-reference.xml Normal file
View file

@ -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:
-->