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

5 files changed, 191 insertions, 85 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index eedc992a38..56be7e1b88 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -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
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index aa461d7081..6abff02d9e 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -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>
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
index 61b59c1e0a..969faf9d16 100644
--- a/doc/manual/nix-build.xml
+++ b/doc/manual/nix-build.xml
@@ -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 don’t 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:
diff --git a/doc/manual/nix-shell.xml b/doc/manual/nix-shell.xml
new file mode 100644
index 0000000000..4e9735a023
--- /dev/null
+++ b/doc/manual/nix-shell.xml
@@ -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>
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
index 6643b4a3b9..a1132b978e 100644
--- a/doc/manual/release-notes.xml
+++ b/doc/manual/release-notes.xml
@@ -8,6 +8,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>
 
 <para>This is primarily a bug fix release.  The following changes are