diff options
Diffstat (limited to 'doc/manual/nix-store-reference.xml')
| -rw-r--r-- | doc/manual/nix-store-reference.xml | 444 |
1 files changed, 444 insertions, 0 deletions
diff --git a/doc/manual/nix-store-reference.xml b/doc/manual/nix-store-reference.xml new file mode 100644 index 000000000000..686fe4c15643 --- /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: +--> |