diff options
Diffstat (limited to 'doc/manual/command-ref/nix-shell.xml')
| -rw-r--r-- | doc/manual/command-ref/nix-shell.xml | 411 |
1 files changed, 0 insertions, 411 deletions
diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml deleted file mode 100644 index 2fef323c5..000000000 --- a/doc/manual/command-ref/nix-shell.xml +++ /dev/null @@ -1,411 +0,0 @@ -<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'> - <group choice='req'> - <arg choice="plain"><replaceable>packages</replaceable></arg> - <arg choice="plain"><replaceable>expressions</replaceable></arg> - </group> - </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 using the -<command>-E</command> and <command>-p</command> flags. -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> - -Note that <command>-p</command> accepts multiple full nix expressions that -are valid in the <literal>buildInputs = [ ... ]</literal> shown above, -not only package names. So the following is also legal: - -<screen> -$ nix-shell -p sqlite 'git.override { withManual = false; }' -</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/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/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/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> |