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