lix/doc/manual/src/command-ref/nix-shell.md

289 lines
9.3 KiB
Markdown
Raw Normal View History

2020-07-24 10:56:19 +00:00
# Name
2020-07-23 10:58:42 +00:00
2020-07-24 10:56:19 +00:00
`nix-shell` - start an interactive shell based on a Nix expression
2020-07-23 10:58:42 +00:00
2020-07-24 10:56:19 +00:00
# Synopsis
2020-07-23 10:58:42 +00:00
2020-07-24 10:56:19 +00:00
`nix-shell`
[`--arg` *name* *value*]
[`--argstr` *name* *value*]
[{`--attr` | `-A`} *attrPath*]
[`--command` *cmd*]
[`--run` *cmd*]
[`--exclude` *regexp*]
[`--pure`]
[`--keep` *name*]
2020-07-24 10:56:19 +00:00
{{`--packages` | `-p`} {*packages* | *expressions*} … | [*path*]}
2020-07-23 10:58:42 +00:00
# Disambiguation
This man page describes the command `nix-shell`, which is distinct from `nix
shell`. For documentation on the latter, run `nix shell --help` or see `man
nix3-shell`.
2020-07-23 10:58:42 +00:00
# Description
The command `nix-shell` 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 *path* have been set to their corresponding values, and the
2020-07-23 10:58:42 +00:00
script `$stdenv/setup` has been sourced. This is useful for reproducing
the environment of a derivation for development.
If *path* is not given, `nix-shell` defaults to `shell.nix` if it
exists, and `default.nix` otherwise.
2020-07-23 10:58:42 +00:00
If *path* starts with `http://` or `https://`, it is interpreted as the
2020-07-23 10:58:42 +00:00
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 `default.nix`.
If the derivation defines the variable `shellHook`, it will be run
2020-07-23 10:58:42 +00:00
after `$stdenv/setup` has been sourced. Since this hook is not executed
by regular Nix builds, it allows you to perform initialisation specific
to `nix-shell`. For example, the derivation attribute
2020-07-31 13:43:25 +00:00
```nix
shellHook =
''
echo "Hello shell"
2020-10-30 10:12:28 +00:00
export SOME_API_TOKEN="$(cat ~/.config/some-app/api-token)"
2020-07-31 13:43:25 +00:00
'';
```
2020-07-23 10:58:42 +00:00
2020-10-30 10:12:28 +00:00
will cause `nix-shell` to print `Hello shell` and set the `SOME_API_TOKEN`
environment variable to a user-configured value.
2020-07-23 10:58:42 +00:00
# Options
All options not listed here are passed to `nix-store
--realise`, except for `--arg` and `--attr` / `-A` which are passed to
2020-07-24 12:31:33 +00:00
`nix-instantiate`.
2020-07-23 10:58:42 +00:00
- `--command` *cmd*\
In the environment of the derivation, run the shell command *cmd*.
2020-07-23 10:58:42 +00:00
This command is executed in an interactive shell. (Use `--run` to
use a non-interactive shell instead.) However, a call to `exit` is
implicitly added to the command, so the shell will exit after
2020-07-24 10:56:19 +00:00
running the command. To prevent this, add `return` at the end;
e.g. `--command "echo Hello; return"` will print `Hello` and then
drop you into the interactive shell. This can be useful for doing
any additional initialisation.
2020-07-23 10:58:42 +00:00
- `--run` *cmd*\
2020-07-23 10:58:42 +00:00
Like `--command`, 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.
- `--exclude` *regexp*\
2020-07-23 10:58:42 +00:00
Do not build any dependencies whose store path matches the regular
expression *regexp*. This option may be specified multiple times.
2020-07-23 10:58:42 +00:00
- `--pure`\
2020-07-23 10:58:42 +00:00
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 `HOME`, `USER` and `DISPLAY`, are
retained.
2020-07-23 10:58:42 +00:00
- `--packages` / `-p` *packages*…\
2020-07-23 10:58:42 +00:00
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, `nix-shell -p libjpeg openjdk`
will start a shell in which the packages denoted by the attribute
names `libjpeg` and `openjdk` are present.
- `-i` *interpreter*\
2020-07-23 10:58:42 +00:00
The chained script interpreter to be invoked by `nix-shell`. Only
2020-07-24 10:56:19 +00:00
applicable in `#!`-scripts (described below).
2020-07-23 10:58:42 +00:00
- `--keep` *name*\
2020-07-23 10:58:42 +00:00
When a `--pure` shell is started, keep the listed environment
variables.
The following common options are supported:
# Environment variables
- `NIX_BUILD_SHELL`\
2020-07-23 10:58:42 +00:00
Shell used to start the interactive environment. Defaults to the
`bash` found in `<nixpkgs>`, falling back to the `bash` found in
`PATH` if not found.
2020-07-23 10:58:42 +00:00
# Examples
To build the dependencies of the package Pan, and start an interactive
shell in which to build it:
2020-07-31 14:02:37 +00:00
```console
2020-07-31 13:43:25 +00:00
$ nix-shell '<nixpkgs>' -A pan
[nix-shell]$ eval ${unpackPhase:-unpackPhase}
2020-07-31 13:43:25 +00:00
[nix-shell]$ cd pan-*
[nix-shell]$ eval ${configurePhase:-configurePhase}
[nix-shell]$ eval ${buildPhase:-buildPhase}
2020-07-31 13:43:25 +00:00
[nix-shell]$ ./pan/gui/pan
```
2020-07-23 10:58:42 +00:00
The reason we use form `eval ${configurePhase:-configurePhase}` here is because
those packages that override these phases do so by exporting the overridden
values in the environment variable of the same name.
Here bash is being told to either evaluate the contents of 'configurePhase',
if it exists as a variable, otherwise evaluate the configurePhase function.
2020-07-23 10:58:42 +00:00
To clear the environment first, and do some additional automatic
initialisation of the interactive shell:
2020-07-31 14:02:37 +00:00
```console
2020-07-31 13:43:25 +00:00
$ nix-shell '<nixpkgs>' -A pan --pure \
--command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
```
2020-07-23 10:58:42 +00:00
Nix expressions can also be given on the command line using the `-E` and
`-p` flags. For instance, the following starts a shell containing the
packages `sqlite` and `libX11`:
2020-07-31 14:02:37 +00:00
```console
2020-07-31 13:43:25 +00:00
$ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'
```
2020-07-23 10:58:42 +00:00
A shorter way to do the same is:
2020-07-31 14:02:37 +00:00
```console
2020-07-31 13:43:25 +00:00
$ 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 …
```
2020-07-23 10:58:42 +00:00
Note that `-p` accepts multiple full nix expressions that are valid in
the `buildInputs = [ ... ]` shown above, not only package names. So the
following is also legal:
2020-07-31 14:02:37 +00:00
```console
2020-07-31 13:43:25 +00:00
$ nix-shell -p sqlite 'git.override { withManual = false; }'
```
2020-07-23 10:58:42 +00:00
The `-p` flag looks up Nixpkgs in the Nix search path. You can override
it by passing `-I` or setting `NIX_PATH`. For example, the following
gives you a shell containing the Pan package from a specific revision of
Nixpkgs:
2020-07-31 14:02:37 +00:00
```console
2020-07-31 13:43:25 +00:00
$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
2020-07-24 10:56:19 +00:00
2020-07-31 13:43:25 +00:00
[nix-shell:~]$ pan --version
Pan 0.139
```
2020-07-23 10:58:42 +00:00
# Use as a `#!`-interpreter
You can use `nix-shell` 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:
2020-07-31 13:43:25 +00:00
```bash
#! /usr/bin/env nix-shell
#! nix-shell -i real-interpreter -p packages
```
2020-07-23 10:58:42 +00:00
where *real-interpreter* is the “real” script interpreter that will be
2020-07-23 10:58:42 +00:00
invoked by `nix-shell` after it has obtained the dependencies and
initialised the environment, and *packages* are the attribute names of
the dependencies in Nixpkgs.
2020-07-23 10:58:42 +00:00
The lines starting with `#! nix-shell` specify `nix-shell` options (see
above). Note that you cannot write `#! /usr/bin/env nix-shell -i ...`
because many operating systems only allow one argument in `#!` lines.
For example, here is a Python script that depends on Python and the
`prettytable` package:
2020-07-31 13:43:25 +00:00
```python
#! /usr/bin/env nix-shell
#! nix-shell -i python -p python pythonPackages.prettytable
2020-07-24 10:56:19 +00:00
2020-07-31 13:43:25 +00:00
import prettytable
2020-07-24 10:56:19 +00:00
2020-07-31 13:43:25 +00:00
# Print a simple table.
t = prettytable.PrettyTable(["N", "N^2"])
for n in range(1, 10): t.add_row([n, n * n])
print t
```
2020-07-23 10:58:42 +00:00
Similarly, the following is a Perl script that specifies that it
requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages:
2020-07-31 13:43:25 +00:00
```perl
#! /usr/bin/env nix-shell
#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP
2020-07-24 10:56:19 +00:00
2020-07-31 13:43:25 +00:00
use HTML::TokeParser::Simple;
2020-07-24 10:56:19 +00:00
2020-07-31 13:43:25 +00:00
# Fetch nixos.org and print all hrefs.
my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
2020-07-24 10:56:19 +00:00
2020-07-31 13:43:25 +00:00
while (my $token = $p->get_tag("a")) {
my $href = $token->get_attr("href");
print "$href\n" if $href;
}
```
2020-07-23 10:58:42 +00:00
Sometimes you need to pass a simple Nix expression to customize a
package like Terraform:
2020-07-31 13:43:25 +00:00
```bash
#! /usr/bin/env nix-shell
#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])"
2020-07-24 10:56:19 +00:00
2020-07-31 13:43:25 +00:00
terraform apply
```
2020-07-23 10:58:42 +00:00
> **Note**
2020-07-24 10:56:19 +00:00
>
2020-07-23 10:58:42 +00:00
> You must use double quotes (`"`) when passing a simple Nix expression
> in a nix-shell shebang.
Finally, using the merging of multiple nix-shell shebangs the following
Haskell script uses a specific branch of Nixpkgs/NixOS (the 20.03 stable
2020-07-23 10:58:42 +00:00
branch):
2020-07-31 13:43:25 +00:00
```haskell
#! /usr/bin/env nix-shell
#! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.download-curl ps.tagsoup])"
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-20.03.tar.gz
2020-07-24 10:56:19 +00:00
import Network.Curl.Download
2020-07-31 13:43:25 +00:00
import Text.HTML.TagSoup
import Data.Either
import Data.ByteString.Char8 (unpack)
2020-07-24 10:56:19 +00:00
2020-07-31 13:43:25 +00:00
-- Fetch nixos.org and print all hrefs.
main = do
resp <- openURI "https://nixos.org/"
let tags = filter (isTagOpenName "a") $ parseTags $ unpack $ fromRight undefined resp
2020-07-31 13:43:25 +00:00
let tags' = map (fromAttrib "href") tags
mapM_ putStrLn $ filter (/= "") tags'
```
2020-07-23 10:58:42 +00:00
If you want to be even more precise, you can specify a specific revision
of Nixpkgs:
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz
The examples above all used `-p` 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:
2020-07-31 13:43:25 +00:00
```python
#! /usr/bin/env nix-shell
#! nix-shell deps.nix -i python
```
2020-07-23 10:58:42 +00:00
where the file `deps.nix` in the same directory as the `#!`-script
contains:
2020-07-31 13:43:25 +00:00
```nix
with import <nixpkgs> {};
2020-07-23 10:58:42 +00:00
2020-07-31 13:43:25 +00:00
runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
```