lix-releng-staging/doc/manual/nix-reference.xml

<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&amp;T's GraphViz package.
	    </para>
	  </listitem>
	</varlistentry>

      </variablelist>

    </refsect2>

  </refsect1>


</refentry>


<!--
local variables:
sgml-parent-document: ("book.xml" "refentry")
end:
-->