* Refactoring.
* Convert tabs to spaces.
This commit is contained in:
Eelco Dolstra
parent
bd0ce1a4be
commit
2a4bac5459
|
|
@ -3,16 +3,17 @@ ENV = SGML_CATALOG_FILES=$(docbookcatalog)
|
||||||
XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs
|
XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs
|
||||||
XSLTPROC = $(ENV) $(xsltproc) $(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
|
troubleshooting.xml bugs.xml
|
||||||
|
|
||||||
book.is-valid: $(SOURCES)
|
book.is-valid: $(SOURCES)
|
||||||
$(XMLLINT) --noout --valid book.xml
|
$(XMLLINT) --noout --valid book.xml
|
||||||
touch $@
|
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
|
$(XSLTPROC) $(docbookxsl)/manpages/docbook.xsl book.xml
|
||||||
|
|
||||||
book.html: $(SOURCES) book.is-valid
|
book.html: $(SOURCES) book.is-valid
|
||||||
|
|
@ -24,4 +25,6 @@ install-data-local: book.html
|
||||||
$(INSTALL) -d $(datadir)/nix/manual
|
$(INSTALL) -d $(datadir)/nix/manual
|
||||||
$(INSTALL_DATA) book.html $(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)
|
||||||
|
|
|
||||||
|
|
@ -5,8 +5,8 @@
|
||||||
[
|
[
|
||||||
<!ENTITY introduction SYSTEM "introduction.xml">
|
<!ENTITY introduction SYSTEM "introduction.xml">
|
||||||
<!ENTITY installation SYSTEM "installation.xml">
|
<!ENTITY installation SYSTEM "installation.xml">
|
||||||
<!ENTITY nix-reference SYSTEM "nix-reference.xml">
|
<!ENTITY nix-store-reference SYSTEM "nix-store-reference.xml">
|
||||||
<!ENTITY fix-reference SYSTEM "fix-reference.xml">
|
<!ENTITY nix-instantiate-reference SYSTEM "nix-instantiate-reference.xml">
|
||||||
<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
|
<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
|
||||||
<!ENTITY bugs SYSTEM "bugs.xml">
|
<!ENTITY bugs SYSTEM "bugs.xml">
|
||||||
]>
|
]>
|
||||||
|
|
@ -28,34 +28,10 @@
|
||||||
&introduction;
|
&introduction;
|
||||||
&installation;
|
&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>
|
<appendix>
|
||||||
<title>Command Reference</title>
|
<title>Command Reference</title>
|
||||||
&nix-reference;
|
&nix-store-reference;
|
||||||
&fix-reference;
|
&nix-instantiate-reference;
|
||||||
</appendix>
|
</appendix>
|
||||||
|
|
||||||
&troubleshooting;
|
&troubleshooting;
|
||||||
|
|
|
||||||
|
|
@ -20,8 +20,8 @@
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Nix can be obtained from its <ulink
|
Nix can be obtained from its <ulink
|
||||||
url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk'>Subversion
|
url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk'>Subversion
|
||||||
repository</ulink>. For example, the following command will check out
|
repository</ulink>. For example, the following command will check out
|
||||||
the latest revision into a directory called <filename>nix</filename>:
|
the latest revision into a directory called <filename>nix</filename>:
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
|
@ -30,11 +30,11 @@ $ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk nix</sc
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Likewise, specific releases can be obtained from the <ulink
|
Likewise, specific releases can be obtained from the <ulink
|
||||||
url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/tags'>tags
|
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
|
directory</ulink> of the repository. If you don't have Subversion, you
|
||||||
can download a <ulink
|
can download a <ulink
|
||||||
url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed
|
url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed
|
||||||
tar-file</ulink> of the latest revision of the repository.
|
tar-file</ulink> of the latest revision of the repository.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
@ -63,9 +63,9 @@ $ make install</screen>
|
||||||
|
|
||||||
<warning>
|
<warning>
|
||||||
<para>
|
<para>
|
||||||
It is advisable <emphasis>not</emphasis> to change the installation
|
It is advisable <emphasis>not</emphasis> to change the installation
|
||||||
prefix, since doing so will in all likelihood make it impossible to use
|
prefix, since doing so will in all likelihood make it impossible to use
|
||||||
derivates built on other systems.
|
derivates built on other systems.
|
||||||
</para>
|
</para>
|
||||||
</warning>
|
</warning>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -15,74 +15,74 @@
|
||||||
<title>Build management</title>
|
<title>Build management</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Build management tools are used to perform <emphasis>software
|
Build management tools are used to perform <emphasis>software
|
||||||
builds</emphasis>, that is, the construction of derived products
|
builds</emphasis>, that is, the construction of derived products
|
||||||
(<emphasis>derivates)</emphasis>) such as executable programs from
|
(<emphasis>derivates)</emphasis>) such as executable programs from
|
||||||
source code. A commonly used build tool is Make, which is a standard
|
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:
|
tool on Unix systems. These tools have to deal with several issues:
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Efficiency</emphasis>. Since building large systems
|
<emphasis>Efficiency</emphasis>. Since building large systems
|
||||||
can take a substantial amount of time, it is desirable that build
|
can take a substantial amount of time, it is desirable that build
|
||||||
steps that have been performed in the past are not repeated
|
steps that have been performed in the past are not repeated
|
||||||
unnecessarily, i.e., if a new build differs from a previous build
|
unnecessarily, i.e., if a new build differs from a previous build
|
||||||
only with respect to certain sources, then only the build steps
|
only with respect to certain sources, then only the build steps
|
||||||
that (directly or indirectly) <emphasis>depend</emphasis> on
|
that (directly or indirectly) <emphasis>depend</emphasis> on
|
||||||
those sources should be redone.
|
those sources should be redone.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Correctness</emphasis> is this context means that the
|
<emphasis>Correctness</emphasis> is this context means that the
|
||||||
derivates produced by a build are always consistent with 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
|
sources, that is, they are equal to what we would get if we were
|
||||||
to build the derivates from those sources. This requirement is
|
to build the derivates from those sources. This requirement is
|
||||||
trivially met when we do a full, unconditional build, but is far
|
trivially met when we do a full, unconditional build, but is far
|
||||||
from trivial under the requirement of efficiency, since it is not
|
from trivial under the requirement of efficiency, since it is not
|
||||||
easy to determine which derivates are affected by a change to a
|
easy to determine which derivates are affected by a change to a
|
||||||
source.
|
source.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Variability</emphasis> is the property that a software
|
<emphasis>Variability</emphasis> is the property that a software
|
||||||
system can be built in a (potentially large) number of variants.
|
system can be built in a (potentially large) number of variants.
|
||||||
Variation exists both in <emphasis>time</emphasis>---the
|
Variation exists both in <emphasis>time</emphasis>---the
|
||||||
evolution of different versions of an artifact---and in
|
evolution of different versions of an artifact---and in
|
||||||
<emphasis>space</emphasis>---the artifact might have
|
<emphasis>space</emphasis>---the artifact might have
|
||||||
configuration options that lead to variants that differ in the
|
configuration options that lead to variants that differ in the
|
||||||
features they support (for example, a system might be built with
|
features they support (for example, a system might be built with
|
||||||
or without debugging information).
|
or without debugging information).
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Build managers historically have had good support for variation
|
Build managers historically have had good support for variation
|
||||||
in time (rebuilding the system in an intelligent way when sources
|
in time (rebuilding the system in an intelligent way when sources
|
||||||
change is one of the primary reasons to use a build manager), but
|
change is one of the primary reasons to use a build manager), but
|
||||||
not always for variation in space. For example,
|
not always for variation in space. For example,
|
||||||
<command>make</command> will not automatically ensure that
|
<command>make</command> will not automatically ensure that
|
||||||
variant builds are properly isolated from each other (they will
|
variant builds are properly isolated from each other (they will
|
||||||
in fact overwrite each other unless special precautions are
|
in fact overwrite each other unless special precautions are
|
||||||
taken).
|
taken).
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>High-level system modelling language</emphasis>. The
|
<emphasis>High-level system modelling language</emphasis>. The
|
||||||
language in which one describes what and how derivates are to be
|
language in which one describes what and how derivates are to be
|
||||||
produced should have sufficient abstraction facilities to make it
|
produced should have sufficient abstraction facilities to make it
|
||||||
easy to specify the derivation of even very large systems. Also,
|
easy to specify the derivation of even very large systems. Also,
|
||||||
the language should be <emphasis>modular</emphasis> to enable
|
the language should be <emphasis>modular</emphasis> to enable
|
||||||
components from possible different sources to be easily combined.
|
components from possible different sources to be easily combined.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
@ -91,33 +91,33 @@
|
||||||
<title>Package management</title>
|
<title>Package management</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
After software has been built, is must also be
|
After software has been built, is must also be
|
||||||
<emphasis>deployed</emphasis> in the intended target environment, e.g.,
|
<emphasis>deployed</emphasis> in the intended target environment, e.g.,
|
||||||
the user's workstation. Examples include the Red Hat package manager
|
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
|
(RPM), Microsoft's MSI, and so on. Here also we have several issues to
|
||||||
contend with:
|
contend with:
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The <emphasis>creation</emphasis> of packages from some formal
|
The <emphasis>creation</emphasis> of packages from some formal
|
||||||
description of what artifacts should be distributed in the
|
description of what artifacts should be distributed in the
|
||||||
package.
|
package.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The <emphasis>deployment</emphasis> of packages, that is, the
|
The <emphasis>deployment</emphasis> of packages, that is, the
|
||||||
mechanism by which we get them onto the intended target
|
mechanism by which we get them onto the intended target
|
||||||
environment. This can be as simple as copying a file, but
|
environment. This can be as simple as copying a file, but
|
||||||
complexity comes from the wide range of possible installation
|
complexity comes from the wide range of possible installation
|
||||||
media (such as a network install), and the scalability of the
|
media (such as a network install), and the scalability of the
|
||||||
process (if a program must be installed on a thousand systems, we
|
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
|
do not want to visit each system and perform some manual steps to
|
||||||
install the program on that system; that is, the complexity for
|
install the program on that system; that is, the complexity for
|
||||||
the system administrator should be constant, not linear).
|
the system administrator should be constant, not linear).
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
|
|
@ -136,95 +136,95 @@
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Reliable dependencies.</emphasis> Builds of file system
|
<emphasis>Reliable dependencies.</emphasis> Builds of file system
|
||||||
objects depend on other file system object, such as source files,
|
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
|
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
|
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
|
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
|
inputs change, we need to rebuild the things that depend on them to
|
||||||
maintain consistency between sources and derivates. Second, when we
|
maintain consistency between sources and derivates. Second, when we
|
||||||
<emphasis>deploy</emphasis> file system objects (that is, copy them
|
<emphasis>deploy</emphasis> file system objects (that is, copy them
|
||||||
to a different system), we want to be certain that we copy everything
|
to a different system), we want to be certain that we copy everything
|
||||||
that we need.
|
that we need.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Nix ensures this by building and storing file system objects in paths
|
Nix ensures this by building and storing file system objects in paths
|
||||||
that are infeasible to predict in advance. For example, the
|
that are infeasible to predict in advance. For example, the
|
||||||
artifacts of a package <literal>X</literal> might be stored in
|
artifacts of a package <literal>X</literal> might be stored in
|
||||||
<filename>/nix/store/d58a0606ed616820de291d594602665d-X</filename>,
|
<filename>/nix/store/d58a0606ed616820de291d594602665d-X</filename>,
|
||||||
rather than in, say, <filename>/usr/lib</filename>. The path
|
rather than in, say, <filename>/usr/lib</filename>. The path
|
||||||
component <filename>d58a...</filename> is actually a cryptographic
|
component <filename>d58a...</filename> is actually a cryptographic
|
||||||
hash of all the inputs (i.e., sources, requisites, and build flags)
|
hash of all the inputs (i.e., sources, requisites, and build flags)
|
||||||
used in building <literal>X</literal>, and as such is very fragile:
|
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
|
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
|
sensible to <emphasis>hard-code</emphasis> such a path into the build
|
||||||
scripts of a package <literal>Y</literal> that uses
|
scripts of a package <literal>Y</literal> that uses
|
||||||
<literal>X</literal> (as does happen with <quote>fixed</quote> paths
|
<literal>X</literal> (as does happen with <quote>fixed</quote> paths
|
||||||
such as <filename>/usr/lib</filename>). Rather, the build script of
|
such as <filename>/usr/lib</filename>). Rather, the build script of
|
||||||
package <literal>Y</literal> is parameterised with the actual
|
package <literal>Y</literal> is parameterised with the actual
|
||||||
location of <literal>X</literal>, which is supplied by the Nix
|
location of <literal>X</literal>, which is supplied by the Nix
|
||||||
system.
|
system.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Support for variability.</emphasis>
|
<emphasis>Support for variability.</emphasis>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
As stated above, the path name of a file system object contain a
|
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
|
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,
|
any of the inputs will cause the hash to change--and by extension,
|
||||||
the path name. These inputs include both sources (variation in time)
|
the path name. These inputs include both sources (variation in time)
|
||||||
and configuration options (variation in space). Therefore variants
|
and configuration options (variation in space). Therefore variants
|
||||||
of the same package don't clash---they can co-exist peacefully within
|
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
|
the same file system. So thanks to Nix's mechanism for reliably
|
||||||
dealing with dependencies, we obtain management of variants for free
|
dealing with dependencies, we obtain management of variants for free
|
||||||
(or, to quote Simon Peyton-Jone, it's not free, but it has already
|
(or, to quote Simon Peyton-Jone, it's not free, but it has already
|
||||||
been paid for).
|
been paid for).
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Transparent source/binary deployment.</emphasis>
|
<emphasis>Transparent source/binary deployment.</emphasis>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Easy configuration duplication.</emphasis>
|
<emphasis>Easy configuration duplication.</emphasis>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Automatic storage management.</emphasis>
|
<emphasis>Automatic storage management.</emphasis>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Atomic upgrades and rollbacks.</emphasis>
|
<emphasis>Atomic upgrades and rollbacks.</emphasis>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Support for many simultaneous configurations.</emphasis>
|
<emphasis>Support for many simultaneous configurations.</emphasis>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Portability.</emphasis> Nix is quite portable. Contrary
|
<emphasis>Portability.</emphasis> Nix is quite portable. Contrary
|
||||||
to build systems like those in, e.g., Vesta and ClearCase [sic?], it
|
to build systems like those in, e.g., Vesta and ClearCase [sic?], it
|
||||||
does not rely on operating system extensions.
|
does not rely on operating system extensions.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
|
@ -236,20 +236,20 @@
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Build management.</emphasis> In principle it is already
|
<emphasis>Build management.</emphasis> In principle it is already
|
||||||
possible to do build management using Fix (by writing builders that
|
possible to do build management using Fix (by writing builders that
|
||||||
perform appropriate build steps), but the Fix language is not yet
|
perform appropriate build steps), but the Fix language is not yet
|
||||||
powerful enough to make this pleasant. The <ulink
|
powerful enough to make this pleasant. The <ulink
|
||||||
url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>
|
url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>
|
||||||
should be retargeted to produce Nix expressions, or alternatively,
|
should be retargeted to produce Nix expressions, or alternatively,
|
||||||
extend Fix with Maak's semantics and concrete syntax (since Fix needs
|
extend Fix with Maak's semantics and concrete syntax (since Fix needs
|
||||||
a concrete syntax anyway). Another interesting idea is to write a
|
a concrete syntax anyway). Another interesting idea is to write a
|
||||||
<command>make</command> implementation that uses Nix as a back-end to
|
<command>make</command> implementation that uses Nix as a back-end to
|
||||||
support <ulink
|
support <ulink
|
||||||
url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink>
|
url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink>
|
||||||
build files.
|
build files.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
<refentry>
|
<refentry>
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>fix</refname>
|
<refname>nix-instantiate</refname>
|
||||||
<refpurpose>generate Nix expressions from a high-level description</refpurpose>
|
<refpurpose>generate Nix expressions from a high-level description</refpurpose>
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
|
|
@ -8,8 +8,8 @@
|
||||||
<cmdsynopsis>
|
<cmdsynopsis>
|
||||||
<command>fix</command>
|
<command>fix</command>
|
||||||
<group choice='opt' rep='repeat'>
|
<group choice='opt' rep='repeat'>
|
||||||
<arg><option>--verbose</option></arg>
|
<arg><option>--verbose</option></arg>
|
||||||
<arg><option>-v</option></arg>
|
<arg><option>-v</option></arg>
|
||||||
</group>
|
</group>
|
||||||
<arg rep='repeat'><replaceable>files</replaceable></arg>
|
<arg rep='repeat'><replaceable>files</replaceable></arg>
|
||||||
</cmdsynopsis>
|
</cmdsynopsis>
|
||||||
|
|
@ -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&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
444
doc/manual/nix-store-reference.xml
Normal 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&T's GraphViz package.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
|
||||||
|
</refentry>
|
||||||
|
|
||||||
|
|
||||||
|
<!--
|
||||||
|
local variables:
|
||||||
|
sgml-parent-document: ("book.xml" "refentry")
|
||||||
|
end:
|
||||||
|
-->
|
||||||
Loading…
Reference in a new issue