7994fd1d54
git-subtree-dir: third_party/nix
git-subtree-mainline: cf8cd640c1
git-subtree-split: be66c7a6b24e3c3c6157fd37b86c7203d14acf10
397 lines
13 KiB
XML
397 lines
13 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-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>
|
|
<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>--run</option> <replaceable>cmd</replaceable></arg>
|
|
<arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
|
|
<arg><option>--pure</option></arg>
|
|
<arg><option>--keep</option> <replaceable>name</replaceable></arg>
|
|
<group choice='req'>
|
|
<arg choice='plain'>
|
|
<group choice='req'>
|
|
<arg choice='plain'><option>--packages</option></arg>
|
|
<arg choice='plain'><option>-p</option></arg>
|
|
</group>
|
|
<arg choice='plain' rep='repeat'><replaceable>packages</replaceable></arg>
|
|
</arg>
|
|
<arg><replaceable>path</replaceable></arg>
|
|
</group>
|
|
</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 <replaceable>path</replaceable> starts with
|
|
<literal>http://</literal> or <literal>https://</literal>, it is
|
|
interpreted as the URL of a tarball that will be downloaded and
|
|
unpacked to a temporary location. The tarball must include a single
|
|
top-level directory containing at least a file named
|
|
<filename>default.nix</filename>.</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>. This command is
|
|
executed in an interactive shell. (Use <option>--run</option> to
|
|
use a non-interactive shell instead.) However, a call to
|
|
<literal>exit</literal> is implicitly added to the command, so the
|
|
shell will exit after running the command. To prevent this, add
|
|
<literal>return</literal> at the end; e.g. <literal>--command
|
|
"echo Hello; return"</literal> will print <literal>Hello</literal>
|
|
and then drop you into the interactive shell. This can be useful
|
|
for doing any additional initialisation.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--run</option> <replaceable>cmd</replaceable></term>
|
|
|
|
<listitem><para>Like <option>--command</option>, but executes the
|
|
command in a non-interactive shell. This means (among other
|
|
things) that if you hit Ctrl-C while the command is running, the
|
|
shell exits.</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>
|
|
|
|
<varlistentry><term><option>--packages</option> / <option>-p</option> <replaceable>packages</replaceable>…</term>
|
|
|
|
<listitem><para>Set up an environment in which the specified
|
|
packages are present. The command line arguments are interpreted
|
|
as attribute names inside the Nix Packages collection. Thus,
|
|
<literal>nix-shell -p libjpeg openjdk</literal> will start a shell
|
|
in which the packages denoted by the attribute names
|
|
<varname>libjpeg</varname> and <varname>openjdk</varname> are
|
|
present.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>-i</option> <replaceable>interpreter</replaceable></term>
|
|
|
|
<listitem><para>The chained script interpreter to be invoked by
|
|
<command>nix-shell</command>. Only applicable in
|
|
<literal>#!</literal>-scripts (described <link
|
|
linkend="ssec-nix-shell-shebang">below</link>).</para>
|
|
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>--keep</option> <replaceable>name</replaceable></term>
|
|
|
|
<listitem><para>When a <option>--pure</option> shell is started,
|
|
keep the listed environment variables.</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>Environment variables</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry><term><envar>NIX_BUILD_SHELL</envar></term>
|
|
|
|
<listitem><para>Shell used to start the interactive environment.
|
|
Defaults to the <command>bash</command> found in <envar>PATH</envar>.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</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
|
|
[nix-shell]$ unpackPhase
|
|
[nix-shell]$ cd pan-*
|
|
[nix-shell]$ configurePhase
|
|
[nix-shell]$ buildPhase
|
|
[nix-shell]$ ./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>
|
|
|
|
Nix expressions can also be given on the command line. For instance,
|
|
the following starts a shell containing the packages
|
|
<literal>sqlite</literal> and <literal>libX11</literal>:
|
|
|
|
<screen>
|
|
$ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'
|
|
</screen>
|
|
|
|
A shorter way to do the same is:
|
|
|
|
<screen>
|
|
$ nix-shell -p sqlite xorg.libX11
|
|
[nix-shell]$ echo $NIX_LDFLAGS
|
|
… -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …
|
|
</screen>
|
|
|
|
The <command>-p</command> flag looks up Nixpkgs in the Nix search
|
|
path. You can override it by passing <option>-I</option> or setting
|
|
<envar>NIX_PATH</envar>. For example, the following gives you a shell
|
|
containing the Pan package from a specific revision of Nixpkgs:
|
|
|
|
<screen>
|
|
$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
|
|
|
|
[nix-shell:~]$ pan --version
|
|
Pan 0.139
|
|
</screen>
|
|
|
|
</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection xml:id="ssec-nix-shell-shebang"><title>Use as a <literal>#!</literal>-interpreter</title>
|
|
|
|
<para>You can use <command>nix-shell</command> as a script interpreter
|
|
to allow scripts written in arbitrary languages to obtain their own
|
|
dependencies via Nix. This is done by starting the script with the
|
|
following lines:
|
|
|
|
<programlisting>
|
|
#! /usr/bin/env nix-shell
|
|
#! nix-shell -i <replaceable>real-interpreter</replaceable> -p <replaceable>packages</replaceable>
|
|
</programlisting>
|
|
|
|
where <replaceable>real-interpreter</replaceable> is the “real” script
|
|
interpreter that will be invoked by <command>nix-shell</command> after
|
|
it has obtained the dependencies and initialised the environment, and
|
|
<replaceable>packages</replaceable> are the attribute names of the
|
|
dependencies in Nixpkgs.</para>
|
|
|
|
<para>The lines starting with <literal>#! nix-shell</literal> specify
|
|
<command>nix-shell</command> options (see above). Note that you cannot
|
|
write <literal>#! /usr/bin/env nix-shell -i ...</literal> because
|
|
many operating systems only allow one argument in
|
|
<literal>#!</literal> lines.</para>
|
|
|
|
<para>For example, here is a Python script that depends on Python and
|
|
the <literal>prettytable</literal> package:
|
|
|
|
<programlisting>
|
|
#! /usr/bin/env nix-shell
|
|
#! nix-shell -i python -p python pythonPackages.prettytable
|
|
|
|
import prettytable
|
|
|
|
# Print a simple table.
|
|
t = prettytable.PrettyTable(["N", "N^2"])
|
|
for n in range(1, 10): t.add_row([n, n * n])
|
|
print t
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>Similarly, the following is a Perl script that specifies that it
|
|
requires Perl and the <literal>HTML::TokeParser::Simple</literal> and
|
|
<literal>LWP</literal> packages:
|
|
|
|
<programlisting>
|
|
#! /usr/bin/env nix-shell
|
|
#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP
|
|
|
|
use HTML::TokeParser::Simple;
|
|
|
|
# Fetch nixos.org and print all hrefs.
|
|
my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
|
|
|
|
while (my $token = $p->get_tag("a")) {
|
|
my $href = $token->get_attr("href");
|
|
print "$href\n" if $href;
|
|
}
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>Sometimes you need to pass a simple Nix expression to customize
|
|
a package like Terraform:
|
|
|
|
<programlisting><![CDATA[
|
|
#! /usr/bin/env nix-shell
|
|
#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])"
|
|
|
|
terraform apply
|
|
]]></programlisting>
|
|
|
|
<note><para>You must use double quotes (<literal>"</literal>) when
|
|
passing a simple Nix expression in a nix-shell shebang.</para></note>
|
|
</para>
|
|
|
|
<para>Finally, using the merging of multiple nix-shell shebangs the
|
|
following Haskell script uses a specific branch of Nixpkgs/NixOS (the
|
|
18.03 stable branch):
|
|
|
|
<programlisting><![CDATA[
|
|
#! /usr/bin/env nix-shell
|
|
#! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])"
|
|
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-18.03.tar.gz
|
|
|
|
import Network.HTTP
|
|
import Text.HTML.TagSoup
|
|
|
|
-- Fetch nixos.org and print all hrefs.
|
|
main = do
|
|
resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
|
|
body <- getResponseBody resp
|
|
let tags = filter (isTagOpenName "a") $ parseTags body
|
|
let tags' = map (fromAttrib "href") tags
|
|
mapM_ putStrLn $ filter (/= "") tags'
|
|
]]></programlisting>
|
|
|
|
If you want to be even more precise, you can specify a specific
|
|
revision of Nixpkgs:
|
|
|
|
<programlisting>
|
|
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>The examples above all used <option>-p</option> to get
|
|
dependencies from Nixpkgs. You can also use a Nix expression to build
|
|
your own dependencies. For example, the Python example could have been
|
|
written as:
|
|
|
|
<programlisting>
|
|
#! /usr/bin/env nix-shell
|
|
#! nix-shell deps.nix -i python
|
|
</programlisting>
|
|
|
|
where the file <filename>deps.nix</filename> in the same directory
|
|
as the <literal>#!</literal>-script contains:
|
|
|
|
<programlisting>
|
|
with import <nixpkgs> {};
|
|
|
|
runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
|
|
</programlisting>
|
|
|
|
</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>
|