68b5306c56
This builds on edef's work with depot-scan by adding a dedicated flag to the command. We piggyback on upstream's restricted-mode implementation, the checkSourcePath function. Change-Id: I52bb613549f40dbca1e8caa036635910c1a3d6d0 Reviewed-on: https://cl.tvl.fyi/c/depot/+/1654 Tested-by: BuildkiteCI Reviewed-by: glittershark <grfn@gws.fyi>
278 lines
8.5 KiB
XML
278 lines
8.5 KiB
XML
<refentry xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||
version="5.0"
|
||
xml:id="sec-nix-instantiate">
|
||
|
||
<refmeta>
|
||
<refentrytitle>nix-instantiate</refentrytitle>
|
||
<manvolnum>1</manvolnum>
|
||
<refmiscinfo class="source">Nix</refmiscinfo>
|
||
<refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>nix-instantiate</refname>
|
||
<refpurpose>instantiate store derivations from Nix expressions</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsynopsisdiv>
|
||
<cmdsynopsis>
|
||
<command>nix-instantiate</command>
|
||
<group>
|
||
<arg choice='plain'><option>--parse</option></arg>
|
||
<arg choice='plain'>
|
||
<option>--eval</option>
|
||
<arg><option>--strict</option></arg>
|
||
<arg><option>--json</option></arg>
|
||
<arg><option>--xml</option></arg>
|
||
</arg>
|
||
</group>
|
||
<arg><option>--read-write-mode</option></arg>
|
||
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
|
||
<arg>
|
||
<group choice='req'>
|
||
<arg choice='plain'><option>--attr</option></arg>
|
||
<arg choice='plain'><option>-A</option></arg>
|
||
</group>
|
||
<replaceable>attrPath</replaceable>
|
||
</arg>
|
||
<arg><option>--add-root</option> <replaceable>path</replaceable></arg>
|
||
<arg><option>--indirect</option></arg>
|
||
<arg><option>--<arg>no</arg>trace-file-access</option></arg>
|
||
<group>
|
||
<arg choice='plain'><option>--expr</option></arg>
|
||
<arg choice='plain'><option>-E</option></arg>
|
||
</group>
|
||
<arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
|
||
</cmdsynopsis>
|
||
<cmdsynopsis>
|
||
<command>nix-instantiate</command>
|
||
<arg choice='plain'><option>--find-file</option></arg>
|
||
<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 evaluates the Nix expressions in each of
|
||
<replaceable>files</replaceable> (which defaults to
|
||
<replaceable>./default.nix</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 condition="manual">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</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</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>
|
||
|
||
<varlistentry><term><option>--find-file</option></term>
|
||
|
||
<listitem><para>Look up the given files in Nix’s search path (as
|
||
specified by the <envar linkend="env-NIX_PATH">NIX_PATH</envar>
|
||
environment variable). If found, print the corresponding absolute
|
||
paths on standard output. For instance, if
|
||
<envar>NIX_PATH</envar> is
|
||
<literal>nixpkgs=/home/alice/nixpkgs</literal>, then
|
||
<literal>nix-instantiate --find-file nixpkgs/default.nix</literal>
|
||
will print
|
||
<literal>/home/alice/nixpkgs/default.nix</literal>.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--strict</option></term>
|
||
|
||
<listitem><para>When used with <option>--eval</option>,
|
||
recursively evaluate list elements and attributes. Normally, such
|
||
sub-expressions are left unevaluated (since the Nix expression
|
||
language is lazy).</para>
|
||
|
||
<warning><para>This option can cause non-termination, because lazy
|
||
data structures can be infinitely large.</para></warning>
|
||
|
||
</listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--<arg>no</arg>trace-file-access</option></term>
|
||
<listitem><para>While instantiating the expression, the evaluator will
|
||
print the full path to any files it reads with the prefix
|
||
<envar>trace-file-access: </envar> to the standard error.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--json</option></term>
|
||
|
||
<listitem><para>When used with <option>--eval</option>, print the resulting
|
||
value as an JSON representation of the abstract syntax tree rather
|
||
than as an ATerm.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--xml</option></term>
|
||
|
||
<listitem><para>When used with <option>--eval</option>, print the resulting
|
||
value as an XML representation of the abstract syntax tree rather than as
|
||
an ATerm. The schema is the same as that used by the <link
|
||
linkend="builtin-toXML"><function>toXML</function> built-in</link>.
|
||
</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><option>--read-write-mode</option></term>
|
||
|
||
<listitem><para>When used with <option>--eval</option>, perform
|
||
evaluation in read/write mode so nix language features that
|
||
require it will still work (at the cost of needing to do
|
||
instantiation of every evaluated derivation). If this option is
|
||
not enabled, there may be uninstantiated store paths in the final
|
||
output.</para>
|
||
|
||
</listitem>
|
||
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
<variablelist condition="manpage">
|
||
<xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
|
||
</variablelist>
|
||
|
||
</refsection>
|
||
|
||
|
||
<refsection><title>Examples</title>
|
||
|
||
<para>Instantiating store derivations from a Nix expression, and
|
||
building them using <command>nix-store</command>:
|
||
|
||
<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>
|
||
|
||
</para>
|
||
|
||
<para>You can also give a Nix expression on the command line:
|
||
|
||
<screen>
|
||
$ nix-instantiate -E 'with import <nixpkgs> { }; hello'
|
||
/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
|
||
</screen>
|
||
|
||
This is equivalent to:
|
||
|
||
<screen>
|
||
$ nix-instantiate '<nixpkgs>' -A hello
|
||
</screen>
|
||
|
||
</para>
|
||
|
||
<para>Parsing and evaluating Nix expressions:
|
||
|
||
<screen>
|
||
$ nix-instantiate --parse -E '1 + 2'
|
||
1 + 2
|
||
|
||
$ nix-instantiate --eval -E '1 + 2'
|
||
3
|
||
|
||
$ nix-instantiate --eval --xml -E '1 + 2'
|
||
<![CDATA[<?xml version='1.0' encoding='utf-8'?>
|
||
<expr>
|
||
<int value="3" />
|
||
</expr>]]></screen>
|
||
|
||
</para>
|
||
|
||
<para>The difference between non-strict and strict evaluation:
|
||
|
||
<screen>
|
||
$ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
|
||
<replaceable>...</replaceable><![CDATA[
|
||
<attr name="x">
|
||
<string value="foo" />
|
||
</attr>
|
||
<attr name="y">
|
||
<unevaluated />
|
||
</attr>]]>
|
||
<replaceable>...</replaceable></screen>
|
||
|
||
Note that <varname>y</varname> is left unevaluated (the XML
|
||
representation doesn’t attempt to show non-normal forms).
|
||
|
||
<screen>
|
||
$ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }'
|
||
<replaceable>...</replaceable><![CDATA[
|
||
<attr name="x">
|
||
<string value="foo" />
|
||
</attr>
|
||
<attr name="y">
|
||
<string value="foo" />
|
||
</attr>]]>
|
||
<replaceable>...</replaceable></screen>
|
||
|
||
</para>
|
||
|
||
</refsection>
|
||
|
||
<refsection><title>Conformance</title>
|
||
<para>The <option>--trace-file-access</option> option is a nonstandard
|
||
extension added by Tvix in 2020.</para>
|
||
</refsection>
|
||
|
||
<refsection condition="manpage"><title>Environment variables</title>
|
||
|
||
<variablelist>
|
||
<xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
|
||
</variablelist>
|
||
|
||
</refsection>
|
||
|
||
|
||
</refentry>
|