diff options
| -rw-r--r-- | doc/manual/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/manual/bugs.xml | 30 | ||||
| -rw-r--r-- | doc/manual/common-options.xml | 13 | ||||
| -rw-r--r-- | doc/manual/manual.xml | 3 | ||||
| -rw-r--r-- | doc/manual/nix-store.xml | 450 | ||||
| -rw-r--r-- | doc/manual/opt-verbose.xml | 73 | ||||
| -rw-r--r-- | doc/manual/troubleshooting.xml | 19 |
7 files changed, 342 insertions, 250 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 8f4c84790613..a0fa19406a93 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -7,8 +7,8 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \ --param html.stylesheet \'style.css\' SOURCES = manual.xml introduction.xml installation.xml overview.xml \ - common-options.xml nix-store.xml nix-instantiate.xml \ - troubleshooting.xml bugs.xml \ + nix-store.xml nix-instantiate.xml \ + troubleshooting.xml bugs.xml opt-verbose.xml \ style.css images manual.is-valid: $(SOURCES) version.xml diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml index fcb69c3641a5..33bd96a02de4 100644 --- a/doc/manual/bugs.xml +++ b/doc/manual/bugs.xml @@ -5,24 +5,20 @@ <listitem> <para> - Nix should automatically remove Berkeley DB logfiles. - </para> - </listitem> - - <listitem> - <para> - Unify the concepts of successors and substitutes into a general notion - of <emphasis>equivalent expressions</emphasis>. Expressions are - equivalent if they have the same target paths with the same - identifiers. However, even though they are functionally equivalent, - they may differ stronly with respect to their <emphasis>performance - characteristics</emphasis>. For example, realising a slice is more - efficient that realising the derivation from which that slice was + Unify the concepts of successors and substitutes into a + general notion of <emphasis>equivalent expressions</emphasis>. + Expressions are equivalent if they have the same target paths + with the same identifiers. However, even though they are + functionally equivalent, they may differ stronly with respect + to their <emphasis>performance characteristics</emphasis>. + For example, realising a closure expression is more efficient + that realising the derivation expression from which it was produced. On the other hand, distributing sources may be more - efficient (storage- or bandwidth-wise) than distributing binaries. So - we need to be able to attach weigths or priorities or performance - annotations to expressions; Nix can then choose the most efficient - expression dependent on the context. + efficient (storage- or bandwidth-wise) than distributing + binaries. So we need to be able to attach weigths or + priorities or performance annotations to expressions; Nix can + then choose the most efficient expression dependent on the + context. </para> </listitem> diff --git a/doc/manual/common-options.xml b/doc/manual/common-options.xml deleted file mode 100644 index d04042993fa0..000000000000 --- a/doc/manual/common-options.xml +++ /dev/null @@ -1,13 +0,0 @@ -<sect1> - <title>Common options</title> - - <para> - </para> - -</sect1> - -<!-- -local variables: -sgml-parent-document: ("book.xml" "sect1") -end: ---> diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 9f88dd4090d4..1df0d1fc9124 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -6,7 +6,7 @@ <!ENTITY introduction SYSTEM "introduction.xml"> <!ENTITY installation SYSTEM "installation.xml"> <!ENTITY overview SYSTEM "overview.xml"> -<!ENTITY common-options SYSTEM "common-options.xml"> +<!ENTITY opt-verbose SYSTEM "opt-verbose.xml"> <!ENTITY nix-store SYSTEM "nix-store.xml"> <!ENTITY nix-instantiate SYSTEM "nix-instantiate.xml"> <!ENTITY troubleshooting SYSTEM "troubleshooting.xml"> @@ -36,7 +36,6 @@ <appendix> <title>Command Reference</title> - &common-options; <sect1> <title>nix-store</title> &nix-store; diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index 686fe4c15643..36abf7af3659 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -7,10 +7,6 @@ <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> @@ -25,180 +21,148 @@ </cmdsynopsis> </refsynopsisdiv> - <refsect1> + <refsection> <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. + The command <command>nix-store</command> performs primitive + operations on the Nix store. You generally do not need to run + this command manually. </para> <para> - <command>nix</command> has many subcommands called - <emphasis>operations</emphasis>. These are individually documented - below. Exactly one operation must always be provided. + <command>nix-store</command> takes exactly one + <emphasis>operation</emphasis> flag which indicated the + subcommand to be performed. These are individually + documented below. </para> - </refsect1> + </refsection> - <refsect1> - <title>Common Options</title> + <refsection> + <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). + This section lists the options that are common to all Nix + operations. These options are allowed for every subcommand, + though they may not always have an effect. </para> <variablelist> + &opt-verbose; + <varlistentry> - <term><option>--path</option></term> + <term><option>--keep-failed</option></term> <listitem> <para> - Indicates that any identifier arguments to the operation are paths - in the store rather than identifiers. + 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> - <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> + </variablelist> - <para> - This option may be specified repeatedly. Currently, the following - verbosity levels exist: - </para> + </refsection> - <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> + <refsection> + <title>Environment variables</title> + + <para> + The following environment variables affect the behaviour of + <command>nix-store</command>. + </para> + + <variablelist> <varlistentry> - <term><option>--keep-failed</option></term> + <term><envar>TMPDIR</envar>=<replaceable>path</replaceable></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. + Use the directory <replaceable>path</replaceable> to store + temporary files. In particular, this includes temporary + build directories; these can take up substantial amounts + of disk space. The default is <filename>/tmp</filename>. </para> </listitem> </varlistentry> </variablelist> + + </refsection> - </refsect1> - + <!--######################################################################--> - <refsect1> - <title>Operation <option>--install</option></title> + <refsection> + <title>Operation <option>--realise</option></title> - <refsect2> + <refsection> <title>Synopsis</title> <cmdsynopsis> - <command>nix</command> + <command>nix-store</command> <group> - <arg><option>--install</option></arg> - <arg><option>-i</option></arg> + <arg><option>--realise</option></arg> + <arg><option>-r</option></arg> </group> - <arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg> + <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> </cmdsynopsis> - </refsect2> + </refsection> - <refsect2> + <refsection> <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. + The operation <option>--install</option> realises in the file + system the store expressions stored in + <replaceable>paths</replaceable>. If these expressions are + derivation expressions, they are first + <emphasis>normalised</emphasis> into a closure expression. + This may happen in two ways. First, the corresponding closure + expression (the <emphasis>successor</emphasis>) may already + known (either because the build has already been performed, or + because a successor was explicitly registered through the + <option>--successor</option> operation). Otherwise, the build + action described by the derivation is performed, and a closure + expression is computed by scanning the result of the build for + references to other paths in the store. </para> <para> - The identifiers of the normal forms of the given Nix expressions are - printed on standard output. + The paths of the closure expression corresponding to each + expression in <replaceable>paths</replaceable> is printed on + standard output. </para> - </refsect2> + </refsection> - </refsect1> + </refsection> + <!--######################################################################--> - <refsect1> + <refsection> <title>Operation <option>--delete</option></title> - <refsect2> + <refsection> <title>Synopsis</title> <cmdsynopsis> - <command>nix</command> + <command>nix-store</command> <group> <arg><option>--delete</option></arg> <arg><option>-d</option></arg> </group> <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> </cmdsynopsis> - </refsect2> + </refsection> - <refsect2> + <refsection> <title>Description</title> <para> @@ -215,24 +179,24 @@ 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> + </refsection> - </refsect1> + </refsection> + <!--######################################################################--> - <refsect1> + <refsection> <title>Operation <option>--query</option></title> - <refsect2> + <refsection> <title>Synopsis</title> <cmdsynopsis> - <command>nix</command> + <command>nix-store</command> <group> <arg><option>--query</option></arg> <arg><option>-q</option></arg> @@ -244,34 +208,28 @@ </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> + <arg><option>-R</option></arg> </group> + <arg><option>--predecessors</option></arg> + <arg><option>--graph</option></arg> </group> <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg> </cmdsynopsis> - </refsect2> + </refsection> - <refsect2> + <refsection> <title>Description</title> <para> The operation <option>--query</option> displays various bits of - information about Nix expressions or paths in the store. The queries + information about store expressions or store paths. The queries are described in <xref linkend='nixref-queries' />. At most one query - can be specified; the default query is <option>--list</option>. + can be specified. The default query is <option>--list</option>. </para> - </refsect2> + </refsection> - <refsect2 id='nixref-queries'> + <refsection id='nixref-queries'> <title>Queries</title> <variablelist> @@ -280,34 +238,15 @@ <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). + Prints out the <emphasis>output paths</emphasis> of the + store expressions indicated by the identifiers + <replaceable>args</replaceable>. In the case of a + derivation expression, these are the paths that will be + produced when the derivation is realised. In the case + of a closure expression, these are the paths that were + produced the derivation expression of which the closure + expression is a successor. </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> @@ -315,40 +254,42 @@ <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). + Prints out the requisite paths of the store 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. + The notion of requisite paths is very useful when one + wants to distribute store 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. + This query is generally used to implement various kinds + of deployment. A <emphasis>source deployment</emphasis> + is obtained by distributing the requisite paths of a + derivation expression. A <emphasis>binary + deployment</emphasis> is obtained by distributing the + requisite paths of a closure expression. A + <emphasis>cache deployment</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 + deployment, 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> @@ -361,9 +302,10 @@ <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. + Causes the requisite paths of the + <emphasis>successor</emphasis> of the given store + expressions to be printed, rather than the + requisite paths of the expressions themselves. </para> </listitem> </varlistentry> @@ -372,9 +314,10 @@ <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. + Excludes the paths of store 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> @@ -406,12 +349,16 @@ </varlistentry> <varlistentry> - <term><option>--expansion</option></term> + <term><option>--predecessors</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. + For each store expression stored at paths + <replaceable>args</replaceable>, prints its + <emphasis>predecessors</emphasis>. A derivation + expression <varname>p</varname> is a predecessor of a + store expression <varname>q</varname> iff + <varname>q</varname> is a successor of + <varname>p</varname>. </para> </listitem> </varlistentry> @@ -420,18 +367,121 @@ <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. + Prints a graph of the closure of the store 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> + </refsection> + + </refsection> + + + + <!--######################################################################--> + + <refsection> + <title>Operation <option>--successor</option></title> + + <refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <group> + <arg><option>--successor</option></arg> + </group> + <arg choice='plain' + rep='repeat'><replaceable>srcpath</replaceable> <replaceable>sucpath</replaceable></arg> + </cmdsynopsis> + </refsection> + + <refsection> + <title>Description</title> + + <para> + The operation <option>--successor</option> registers that the + closure expression in <replaceable>sucpath</replaceable> is a + successor of the derivation expression in + <replaceable>srcpath</replaceable>. This is used to implement + binary deployment. + </para> + + </refsection> + + </refsection> + + + + <!--######################################################################--> + + <refsection> + <title>Operation <option>--substitute</option></title> + + <refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <group> + <arg><option>--substitute</option></arg> + </group> + <arg choice='plain' + rep='repeat'><replaceable>srcpath</replaceable> <replaceable>subpath</replaceable></arg> + </cmdsynopsis> + </refsection> + + <refsection> + <title>Description</title> + + <para> + The operation <option>--substitute</option> registers that the + store path <replaceable>srcpath</replaceable> can be built by + realising the derivation expression in + <replaceable>subpath</replaceable>. This is used to implement + binary deployment. + </para> + + </refsection> + + </refsection> + + + + <!--######################################################################--> + + <refsection> + <title>Operation <option>--verify</option></title> + + <refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <group> + <arg><option>--verify</option></arg> + </group> + </cmdsynopsis> + </refsection> + + <refsection> + <title>Description</title> + + <para> + The operation <option>--verify</option> verifies the internal + consistency of the Nix database, and the consistency between + the Nix database and the Nix store. Any inconsistencies + encountered are automatically repaired. Inconsistencies are + generally the result of the Nix store or database being + modified by non-Nix tools, or of bugs in Nix itself. + </para> + + </refsection> + + </refsection> - </refsect1> </refentry> diff --git a/doc/manual/opt-verbose.xml b/doc/manual/opt-verbose.xml new file mode 100644 index 000000000000..5a1007a6a33d --- /dev/null +++ b/doc/manual/opt-verbose.xml @@ -0,0 +1,73 @@ +<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; 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> + <quote>Errors only</quote>: only print messages explaining + why the Nix invocation failed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>1</term> + <listitem> + <para> + <quote>Informational</quote>: print + <emphasis>useful</emphasis> messages about what Nix is + doing. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>2</term> + <listitem> + <para> + <quote>Talkative</quote>: print more informational messages. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>3</term> + <listitem> + <para> + <quote>Chatty</quote>: print even more informational messages. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>4</term> + <listitem> + <para> + <quote>Debug</quote>: print debug information: + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>5</term> + <listitem> + <para> + <quote>Vomit</quote>: print vast amounts of debug + information. + </para> + </listitem> + </varlistentry> + </variablelist> + + </listitem> +</varlistentry> diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml index 1e35c6079538..529943f91fa6 100644 --- a/doc/manual/troubleshooting.xml +++ b/doc/manual/troubleshooting.xml @@ -1,22 +1,9 @@ <appendix> <title>Troubleshooting</title> - <sect1> - <title>Database logfile removal</title> - - <para> - Every time a Nix database transaction takes place, Nix writes a record of - this transaction to a <emphasis>log</emphasis> in its database directory - to ensure that the operation can be replayed in case of a application or - system crash. However, without manual intervention, the log grows - indefinitely. Hence, unused log files should be deleted periodically. - This can be accomplished using the following command: - </para> - - <screen> - $ rm `db_archive -a -h <replaceable>prefix</replaceable>/var/nix/db`</screen> - - </sect1> + <para> + (Nothing.) + </para> </appendix> |