e81d38c02b
Since normal builds don't execute shellHook, this allows nix-shell specific customisation. Suggested by Domen.
164 lines
5.4 KiB
XML
164 lines
5.4 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"
|
|
xml:id="sec-nix-shell">
|
|
|
|
<refmeta>
|
|
<refentrytitle>nix-shell</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="source">Nix</refmiscinfo>
|
|
<refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>nix-shell</refname>
|
|
<refpurpose>start an interactive shell based on a Nix expression</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>nix-shell</command>
|
|
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
|
|
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
|
|
<arg><option>--argstr</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>--command</option> <replaceable>cmd</replaceable></arg>
|
|
<arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
|
|
<arg><option>--pure</option></arg>
|
|
<arg><replaceable>path</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection><title>Description</title>
|
|
|
|
<para>The command <command>nix-shell</command> will build the
|
|
dependencies of the specified derivation, but not the derivation
|
|
itself. It will then start an interactive shell in which all
|
|
environment variables defined by the derivation
|
|
<replaceable>path</replaceable> have been set to their corresponding
|
|
values, and the script <literal>$stdenv/setup</literal> has been
|
|
sourced. This is useful for reproducing the environment of a
|
|
derivation for development.</para>
|
|
|
|
<para>If <replaceable>path</replaceable> is not given,
|
|
<command>nix-shell</command> defaults to
|
|
<filename>shell.nix</filename> if it exists, and
|
|
<filename>default.nix</filename> otherwise.</para>
|
|
|
|
<para>If the derivation defines the variable
|
|
<varname>shellHook</varname>, it will be evaluated after
|
|
<literal>$stdenv/setup</literal> has been sourced. Since this hook is
|
|
not executed by regular Nix builds, it allows you to perform
|
|
initialisation specific to <command>nix-shell</command>. For example,
|
|
the derivation attribute
|
|
|
|
<programlisting>
|
|
shellHook =
|
|
''
|
|
echo "Hello shell!"
|
|
'';
|
|
</programlisting>
|
|
|
|
will cause <command>nix-shell</command> to print <literal>Hello shell!</literal>.</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection><title>Options</title>
|
|
|
|
<para>All options not listed here are passed to <command>nix-store
|
|
--realise</command>, except for <option>--arg</option> and
|
|
<option>--attr</option> / <option>-A</option> which are passed to
|
|
<command>nix-instantiate</command>. <phrase condition="manual">See
|
|
also <xref linkend="sec-common-options" />.</phrase></para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>
|
|
|
|
<listitem><para>In the environment of the derivation, run the
|
|
shell command <replaceable>cmd</replaceable> instead of starting
|
|
an interactive shell. However, if you end the shell command with
|
|
<literal>return</literal>, you still get an interactive shell.
|
|
This can be useful for doing any additional
|
|
initialisation.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term>
|
|
|
|
<listitem><para>Do not build any dependencies whose store path
|
|
matches the regular expression <replaceable>regexp</replaceable>.
|
|
This option may be specified multiple times.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--pure</option></term>
|
|
|
|
<listitem><para>If this flag is specified, the environment is
|
|
almost entirely cleared before the interactive shell is started,
|
|
so you get an environment that more closely corresponds to the
|
|
“real” Nix build. A few variables, in particular
|
|
<envar>HOME</envar>, <envar>USER</envar> and
|
|
<envar>DISPLAY</envar>, are retained. Note that
|
|
<filename>~/.bashrc</filename> and (depending on your Bash
|
|
installation) <filename>/etc/bashrc</filename> are still sourced,
|
|
so any variables set there will affect the interactive
|
|
shell.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<para>The following common options are supported:</para>
|
|
|
|
<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>To build the dependencies of the package Pan, and start an
|
|
interactive shell in which to build it:
|
|
|
|
<screen>
|
|
$ nix-shell '<nixpkgs>' -A pan
|
|
$ unpackPhase
|
|
$ cd pan-*
|
|
$ configurePhase
|
|
$ buildPhase
|
|
$ ./pan/gui/pan
|
|
</screen>
|
|
|
|
To clear the environment first, and do some additional automatic
|
|
initialisation of the interactive shell:
|
|
|
|
<screen>
|
|
$ nix-shell '<nixpkgs>' -A pan --pure \
|
|
--command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
|
|
</screen>
|
|
|
|
</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>
|