about summary refs log tree commit diff
path: root/doc/manual/nix-instantiate.xml
blob: aab2049344eacf7c0745f31f79e9e8b48dfd299f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
<refentry xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink">
  
<refnamediv>
  <refname>nix-instantiate</refname>
  <refpurpose>instantiate store derivations from Nix expressions</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>nix-instantiate</command>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
    <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
    <arg><option>--indirect</option></arg>
    <group choice='opt'>
      <arg choice='plain'><option>--parse-only</option></arg>
      <arg choice='plain'><option>--eval-only</option></arg>
    </group>
    <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>


<refsection><title>Description</title>

<para>The command <command>nix-instantiate</command> generates <link
linkend="gloss-derivation">store derivations</link> from (high-level)
Nix expressions.  It loads and evaluates the Nix expressions in each
of <replaceable>files</replaceable>.  Each top-level expression should
evaluate to a derivation, a list of derivations, or a set of
derivations.  The paths of the resulting store derivations are printed
on standard output.</para>

<para>If <replaceable>files</replaceable> is the character
<literal>-</literal>, then a Nix expression will be read from standard
input.</para>

<para>Most users and developers don’t need to use this command
(<command>nix-env</command> and <command>nix-build</command> perform
store derivation instantiation from Nix expressions automatically).
It is most commonly used for implementing new deployment
policies.</para>

<para>See also <xref linkend="sec-common-options" /> for a list of
common options.</para>

</refsection>


<refsection><title>Options</title>

<variablelist>

  <varlistentry>
    <term><option>--add-root</option> <replaceable>path</replaceable></term>
    <term><option>--indirect</option></term>

    <listitem><para>See the <link linkend="opt-add-root">corresponding
    options</link> in <command>nix-store</command>.</para></listitem>

  </varlistentry>

    
  <varlistentry><term><option>--parse-only</option></term>
  
    <listitem><para>Just parse the input files, and print their
    abstract syntax trees on standard output in ATerm
    format.</para></listitem>
    
  </varlistentry>
      
  <varlistentry><term><option>--eval-only</option></term>
  
    <listitem><para>Just parse and evaluate the input files, and print
    the resulting values on standard output.  No instantiation of
    store derivations takes place.</para></listitem>
    
  </varlistentry>

</variablelist>

</refsection>


<refsection><title>Examples</title>

<screen>
$ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation>
/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv

$ nix-store -r $(nix-instantiate test.nix) <lineannotation>(build)</lineannotation>
<replaceable>...</replaceable>
/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 <lineannotation>(output path)</lineannotation>

$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
...</screen>

</refsection>


</refentry>