Rename ‘nix-build --run-env’ to ‘nix-shell’

This commit is contained in:
Eelco Dolstra 2013-07-19 12:02:44 +02:00
parent dc5f2e7da6
commit 2bc5de8635
7 changed files with 201 additions and 92 deletions

View file

@ -16,7 +16,7 @@ dblatex_opts = \
# Note: we use GIF for now, since the PNGs shipped with Docbook aren't
# transparent.
man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
man1_MANS = nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 \
nix-collect-garbage.1 nix-push.1 nix-pull.1 \
nix-prefetch-url.1 nix-channel.1 \
nix-install-package.1 nix-hash.1 nix-copy-closure.1

View file

@ -19,15 +19,15 @@
</author>
<copyright>
<year>2004-2012</year>
<year>2004-2013</year>
<holder>Eelco Dolstra</holder>
</copyright>
<date>May 2012</date>
<date>July 2013</date>
</info>
<xi:include href="introduction.xml" />
<xi:include href="quick-start.xml" />
<xi:include href="installation.xml" />
@ -40,17 +40,18 @@
<title>Command Reference</title>
<xi:include href="opt-common.xml" />
<xi:include href="env-common.xml" />
<section>
<title>Main commands</title>
<xi:include href="nix-env.xml" />
<xi:include href="nix-instantiate.xml" />
<xi:include href="nix-store.xml" />
</section>
<section>
<title>Utilities</title>
<xi:include href="nix-build.xml" />
<xi:include href="nix-shell.xml" />
<xi:include href="nix-channel.xml" />
<xi:include href="nix-collect-garbage.xml" />
<xi:include href="nix-copy-closure.xml" />
@ -66,7 +67,7 @@
<title>Files</title>
<xi:include href="conf-file.xml" />
</section>
</appendix>
<xi:include href="troubleshooting.xml" />
@ -78,5 +79,5 @@
<xi:include href="release-notes.xml"
xpointer="xmlns(x=http://docbook.org/ns/docbook)xpointer(x:article/x:section)" />
</appendix>
</book>

View file

@ -38,12 +38,6 @@
</group>
<replaceable>outlink</replaceable>
</arg>
<arg>
<option>--run-env</option>
<arg><option>--command</option> <replaceable>cmd</replaceable></arg>
<arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
<arg><option>--pure</option></arg>
</arg>
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@ -76,14 +70,6 @@ a root of the Nix garbage collector. This root disappears
automatically when the <filename>result</filename> symlink is deleted
or renamed. So dont rename the symlink.</para></warning>
<para>The subcommand <command>nix-build --run-env</command> will build
the dependencies of the derivation, but not the derivation itself. It
will then start an interactive shell in which all environment
variables defined by the derivation 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>
</refsection>
@ -136,50 +122,12 @@ also <xref linkend="sec-common-options" />.</phrase></para>
</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>
<para>The following options apply to <command>nix-build --run-env</command>.</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>
</refsection>
@ -196,28 +144,6 @@ lrwxrwxrwx <replaceable>...</replaceable> result -> /nix/store/d18hyl92g30l...
$ ls ./result/bin/
firefox firefox-config</screen>
<para>To build the dependencies of the package Pan, and start an
interactive shell in which to build it:
<screen>
$ nix-build '&lt;nixpkgs>' --run-env -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-build '&lt;nixpkgs>' --run-env -A pan --pure \
--command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
</screen>
</para>
<para>If a derivation has multiple outputs,
<command>nix-build</command> will build the default (first) output.
You can also build all outputs:

142
doc/manual/nix-shell.xml Normal file
View file

@ -0,0 +1,142 @@
<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 choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsection><title>Description</title>
<para>The command <command>nix-shell --run-env</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 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>
</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 '&lt;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 '&lt;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>

View file

@ -6,6 +6,43 @@
<!--==================================================================-->
<section xml:id="ssec-relnotes-1.6.0"><title>Release 1.6.0 (TBA)</title>
<itemizedlist>
<listitem>
<para>The command <command>nix-build --run-env</command> has been
renamed to <command>nix-shell</command>.</para>
</listitem>
<listitem>
<para><command>nix-shell</command> now sources
<filename>$stdenv/setup</filename> <emphasis>inside</emphasis> the
interactive shell, rather than in a parent shell. This ensures
that shell functions defined by <literal>stdenv</literal> can be
used in the interactive shell.</para>
</listitem>
<listitem>
<para><command>nix-shell</command> has a new flag
<option>--pure</option> to clear the environment, so you get an
environment that more closely corresponds to the “real” Nix build.
</para>
</listitem>
<listitem>
<para><command>nix-shell</command> now sets the shell prompt
(<envar>PS1</envar>) to ensure that Nix shells are distinguishable
from your regular shells.</para>
</listitem>
</itemizedlist>
</section>
<!--==================================================================-->
<section xml:id="ssec-relnotes-1.5.3"><title>Release 1.5.3 (June 17, 2013)</title>

View file

@ -18,6 +18,7 @@ install-exec-local: download-using-manifests.pl copy-from-other-stores.pl downlo
$(INSTALL) -d $(DESTDIR)$(libexecdir)/nix/substituters
$(INSTALL_PROGRAM) download-using-manifests.pl copy-from-other-stores.pl download-from-binary-cache.pl $(DESTDIR)$(libexecdir)/nix/substituters
$(INSTALL) -d $(DESTDIR)$(sysconfdir)/nix
ln -sf nix-build $(DESTDIR)$(bindir)/nix-shell
include ../substitute.mk

View file

@ -9,7 +9,7 @@ use File::Temp qw(tempdir);
my $dryRun = 0;
my $verbose = 0;
my $runEnv = 0;
my $runEnv = $0 =~ /nix-shell$/;
my $pure = 0;
my @instArgs = ();
@ -20,8 +20,10 @@ my $shell = $ENV{SHELL} || "/bin/sh";
my $envCommand = ""; # interactive shell
my @envExclude = ();
my $myName = $runEnv ? "nix-shell" : "nix-build";
my $tmpDir = tempdir("nix-build.XXXXXX", CLEANUP => 1, TMPDIR => 1)
my $tmpDir = tempdir("$myName.XXXXXX", CLEANUP => 1, TMPDIR => 1)
or die "cannot create a temporary directory";
my $outLink = "./result";
@ -35,11 +37,11 @@ for (my $n = 0; $n < scalar @ARGV; $n++) {
my $arg = $ARGV[$n];
if ($arg eq "--help") {
exec "man nix-build" or die;
exec "man $myName" or die;
}
elsif ($arg eq "--version") {
print "nix-build (Nix) $Nix::Config::version\n";
print "$myName (Nix) $Nix::Config::version\n";
exit 0;
}
@ -119,7 +121,7 @@ for (my $n = 0; $n < scalar @ARGV; $n++) {
push @instArgs, $arg;
}
elsif ($arg eq "--run-env") {
elsif ($arg eq "--run-env") { # obsolete
$runEnv = 1;
}
@ -164,7 +166,7 @@ foreach my $expr (@exprs) {
}
if ($runEnv) {
die "$0: --run-env requires a single derivation\n" if scalar @drvPaths != 1;
die "$0: a single derivation is required\n" if scalar @drvPaths != 1;
my $drvPath = readlink $drvPaths[0] or die "cannot read symlink `$drvPaths[0]'";
my $drv = derivationFromPath($drvPath);
@ -197,7 +199,7 @@ foreach my $expr (@exprs) {
'[ -e $stdenv/setup ] && source $stdenv/setup; ' .
($pure ? '' : 'PATH=$PATH:$p; ') .
'set +e; ' .
'PS1="\n\[\033[1;32m\][nix-build:\w]$\[\033[0m\] "; ' .
'PS1="\n\[\033[1;32m\][nix-shell:\w]$\[\033[0m\] "; ' .
$envCommand);
exec($ENV{NIX_BUILD_SHELL} // "bash", "--rcfile", $rcfile);
die;