diff options
Diffstat (limited to 'doc/manual/nix-store.xml')
| -rw-r--r-- | doc/manual/nix-store.xml | 476 |
1 files changed, 190 insertions, 286 deletions
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index ac803ce5ff8c..d9ef17e26ec3 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -262,321 +262,225 @@ $ nix-store --gc</screen> <!--######################################################################--> - <refsection> - <title>Operation <option>--query</option></title> - - <refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <group choice='req'> - <arg choice='plain'><option>--query</option></arg> - <arg choice='plain'><option>-q</option></arg> - </group> - <group choice='req'> - <arg choice='plain'><option>--list</option></arg> - <arg choice='plain'><option>-l</option></arg> - <arg choice='plain'><option>--requisites</option></arg> - <arg choice='plain'><option>-R</option></arg> - <arg choice='plain'><option>--predecessors</option></arg> - <arg choice='plain'><option>--graph</option></arg> - </group> - <arg><option>--normalise</option></arg> - <arg><option>-n</option></arg> - <arg><option>--force-realise</option></arg> - <arg><option>-f</option></arg> - <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg> - </cmdsynopsis> - </refsection> - - <refsection> - <title>Description</title> +<refsection><title>Operation <option>--query</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-store</command> + <group choice='req'> + <arg choice='plain'><option>--query</option></arg> + <arg choice='plain'><option>-q</option></arg> + </group> + <group choice='req'> + <arg choice='plain'><option>--list</option></arg> + <arg choice='plain'><option>-l</option></arg> + <arg choice='plain'><option>--requisites</option></arg> + <arg choice='plain'><option>-R</option></arg> + <arg choice='plain'><option>--predecessors</option></arg> + <arg choice='plain'><option>--graph</option></arg> + </group> + <arg><option>--normalise</option></arg> + <arg><option>-n</option></arg> + <arg><option>--force-realise</option></arg> + <arg><option>-f</option></arg> + <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> - <para> - The operation <option>--query</option> displays various bits - of information about store expressions or store paths. The - queries are described below. At most one query can be - specified. The default query is <option>--list</option>. - </para> - - </refsection> - - - <refsection> - <title>Common query options</title> - - <variablelist> - - <varlistentry> - <term><option>--normalise</option> / <option>-n</option></term> - <listitem> - <para> - For those queries that take a Nix store expression, this - option causes those expressions to be normalised first. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--force-realise</option> / <option>-f</option></term> - <listitem> - <para> - For those queries that take a Nix store expression, this - option causes those expressions to be realised first. - This is just a short-cut for the common idiom - </para> - <screen> -nix-store --realise /nix/store/bla.store -x=`nix-store --query --normalise /nix/store/bla.store` -<emphasis>(do something with the path $x</emphasis></screen> - <para> - which using this flag can be written as - </para> - <screen> -x=`nix-store --query --normalise --force-realise /nix/store/bla.store` -<emphasis>(do something with the path $x</emphasis></screen> - </listitem> - </varlistentry> - - </variablelist> +<para>The operation <option>--query</option> displays various bits of +information about store paths. The queries are described below. At +most one query can be specified. The default query is +<option>--list</option>.</para> + +</refsection> + + +<refsection><title>Common query options</title> + +<variablelist> + + <varlistentry><term><option>--use-output</option> / <option>-u</option></term> + + <listitem><para>For each argument to the query that is a store + derivation, apply the query to the output path of the derivation + instead.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--force-realise</option> / <option>-f</option></term> + + <listitem><para>Realise each argument to the query first (see + <link linkend="rsec-nix-store-realise"><command>nix-store + --realise</command></link>).</para></listitem> + + </varlistentry> + +</variablelist> - </refsection> +</refsection> - <refsection id='nixref-queries'> - <title>Queries</title> +<refsection id='nixref-queries'><title>Queries</title> - <variablelist> - - <varlistentry> - <term><option>--list</option> / <option>-l</option></term> - <listitem> - <para> - 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> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--requisites</option> / <option>-R</option></term> - <listitem> - <para> - 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 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 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> - This query has a number of options: - </para> - - <variablelist> - - <varlistentry> - <term><option>--exclude-exprs</option></term> - <listitem> - <para> - 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> - - <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>--predecessors</option></term> - <listitem> - <para> - 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> - - <varlistentry> - <term><option>--graph</option></term> - <listitem> - <para> - 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> - - </refsection> - - </refsection> +<variablelist> + + <varlistentry><term><option>--list</option> / <option>-l</option></term> + + <listitem><para>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></listitem> + + </varlistentry> + + <varlistentry><term><option>--requisites</option> / <option>-R</option></term> + + <listitem><para>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 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 + 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>This query has one option:</para> + + <variablelist> + + <varlistentry><term><option>--include-outputs</option></term> + + <listitem><para>Also include the output path of store + derivations, and their closures.</para></listitem> + + </varlistentry> + + </variablelist> + + </listitem> + + </varlistentry> + + + <varlistentry><term><option>--graph</option></term> + + <listitem><para>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> + +</refsection> + + +</refsection> - <!--######################################################################--> +<!--######################################################################--> - <refsection> - <title>Operation <option>--successor</option></title> +<refsection id="rsec-nix-store-reg-val"><title>Operation <option>--register-validity</option></title> - <refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='req'><option>--successor</option></arg> - <arg choice='plain' - rep='repeat'><replaceable>srcpath</replaceable> <replaceable>sucpath</replaceable></arg> - </cmdsynopsis> - </refsection> +<refsection><title>Synopsis</title> - <refsection> - <title>Description</title> +<cmdsynopsis> + <command>nix-store</command> + <arg choice='req'><option>--register-validity</option></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> +<para>TODO</para> + +</refsection> - </refsection> +</refsection> - <!--######################################################################--> +<!--######################################################################--> - <refsection> - <title>Operation <option>--substitute</option></title> +<refsection><title>Operation <option>--substitute</option></title> - <refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='req'><option>--substitute</option></arg> - <arg choice='plain' - rep='repeat'><replaceable>srcpath</replaceable> <replaceable>subpath</replaceable></arg> - </cmdsynopsis> - </refsection> +<refsection><title>Synopsis</title> - <refsection> - <title>Description</title> +<cmdsynopsis> + <command>nix-store</command> + <arg choice='req'><option>--substitute</option></arg> + <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> +<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> - <!--######################################################################--> +<!--######################################################################--> - <refsection> - <title>Operation <option>--verify</option></title> +<refsection><title>Operation <option>--verify</option></title> - <refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='req'><option>--verify</option></arg> - </cmdsynopsis> - </refsection> +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice='req'><option>--verify</option></arg> + </cmdsynopsis> +</refsection> - <refsection> - <title>Description</title> +<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> +<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> +</refsection> |