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