mirror of
https://github.com/NixOS/nix.git
synced 2024-11-25 16:23:02 +00:00
* Documented the `--query' operation.
This commit is contained in:
parent
b4f88d0ec3
commit
c34a153ae5
@ -15,6 +15,23 @@
|
||||
</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
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
|
||||
</appendix>
|
||||
|
@ -126,6 +126,8 @@
|
||||
</refsect1>
|
||||
|
||||
|
||||
<!--######################################################################-->
|
||||
|
||||
<refsect1>
|
||||
<title>Operation <option>--install</option></title>
|
||||
|
||||
@ -162,6 +164,8 @@
|
||||
</refsect1>
|
||||
|
||||
|
||||
<!--######################################################################-->
|
||||
|
||||
<refsect1>
|
||||
<title>Operation <option>--delete</option></title>
|
||||
|
||||
@ -203,6 +207,216 @@
|
||||
</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>
|
||||
|
||||
|
||||
|
@ -35,8 +35,7 @@
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
$ rm `db_archive -a -h
|
||||
<replaceable>prefix</replaceable>/var/nix/db`</screen>
|
||||
$ rm `db_archive -a -h <replaceable>prefix</replaceable>/var/nix/db`</screen>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user