Merge remote-tracking branch 'upstream/master' into hardened-stdenv

8 files changed, 78 insertions, 46 deletions

diff --git a/doc/configuration.xml b/doc/configuration.xml
index ffeb7cf554bd..caff1e510cdd 100644
--- a/doc/configuration.xml
+++ b/doc/configuration.xml
@@ -46,10 +46,10 @@ $ export NIXPKGS_ALLOW_UNFREE=1
 allowUnfreePredicate = (pkg: ...);
 </programlisting>
 
-    Example to allow flash player only:
+    Example to allow flash player and visual studio code only:
 
 <programlisting>
-allowUnfreePredicate = (pkg: pkgs.lib.hasPrefix "flashplayer-" pkg.name);
+allowUnfreePredicate = with builtins; (pkg: elem (parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);
 </programlisting>
 
     </para>
diff --git a/doc/default.nix b/doc/default.nix
index ddbee65f1ac4..6a44587a31b1 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -27,6 +27,7 @@ stdenv.mkDerivation {
     in ''
       {
         pandoc '${inputFile}' -w docbook ${optionalString useChapters "--chapters"} \
+          --smart \
           | sed -e 's|<ulink url=|<link xlink:href=|' \
               -e 's|</ulink>|</link>|' \
               -e 's|<sect. id=|<section xml:id=|' \
@@ -52,9 +53,8 @@ stdenv.mkDerivation {
       outputFile = "./languages-frameworks/python.xml";
     }
   + toDocbook {
-      inputFile = ./haskell-users-guide.md;
-      outputFile = "haskell-users-guide.xml";
-      useChapters = true;
+      inputFile = ./languages-frameworks/haskell.md;
+      outputFile = "./languages-frameworks/haskell.xml";
     }
   + toDocbook {
       inputFile = ./../pkgs/development/idris-modules/README.md;
diff --git a/doc/functions.xml b/doc/functions.xml
index 7d250824f785..e6bb6b7deefb 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -92,7 +92,14 @@ in ...</programlisting>
     <para>Do not use this function in Nixpkgs. Because it breaks
     package abstraction and doesn’t provide error checking for
     function arguments, it is only intended for ad-hoc customisation
-    (such as in <filename>~/.nixpkgs/config.nix</filename>).</para>
+    (such as in <filename>~/.nixpkgs/config.nix</filename>).
+   </para>
+
+   <para>
+    Additionally, <varname>overrideDerivation</varname> forces an evaluation
+    of the Derivation which can be quite a performance penalty if there are many
+    overrides used.
+   </para>
   </warning>
 
   <para>
diff --git a/doc/beam-users-guide.xml b/doc/languages-frameworks/beam.xml
index c1a4c90bc27c..2dc5aa63e458 100644
--- a/doc/beam-users-guide.xml
+++ b/doc/languages-frameworks/beam.xml
@@ -1,10 +1,10 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
+<section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="users-guide-to-the-erlang-infrastructure">
+         xml:id="sec-beam">
 
-  <title>User's Guide to the Beam Infrastructure</title>
+  <title>Beam Languages (Erlang &amp; Elixir)</title>
   <section xml:id="beam-introduction">
-    <title>Beam Languages (Erlang &amp; Elixir) on Nix</title>
+    <title>Introduction</title>
     <para>
       In this document and related Nix expressions we use the term
       <emphasis>Beam</emphasis> to describe the environment. Beam is
@@ -373,4 +373,4 @@ $ nix-build -A beamPackages
       that.
     </para>
 </section>
-</chapter>
+</section>
diff --git a/doc/haskell-users-guide.md b/doc/languages-frameworks/haskell.md
index b981466bf2e0..e066ad110bec 100644
--- a/doc/haskell-users-guide.md
+++ b/doc/languages-frameworks/haskell.md
@@ -329,7 +329,7 @@ workarounds.
 
 ### How to build a Haskell project using Stack
 
-[Stack][http://haskellstack.org] is a popular build tool for Haskell projects.
+[Stack](http://haskellstack.org) is a popular build tool for Haskell projects.
 It has first-class support for Nix. Stack can optionally use Nix to
 automatically select the right version of GHC and other build tools to build,
 test and execute apps in an existing project downloaded from somewhere on the
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 395d46880217..8076c33f1b3f 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -13,19 +13,20 @@ in Nixpkgs to easily build packages for other programming languages,
 such as Perl or Haskell.  These are described in this chapter.</para>
 
 
-<xi:include href="perl.xml" />
-<xi:include href="python.xml" />
-<xi:include href="ruby.xml" />
+<xi:include href="beam.xml" />
+<xi:include href="bower.xml" />
+<xi:include href="coq.xml" />
 <xi:include href="go.xml" />
+<xi:include href="haskell.xml" />
+<xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md  -->
 <xi:include href="java.xml" />
 <xi:include href="lua.xml" />
-<xi:include href="coq.xml" />
-<xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md  -->
-<xi:include href="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md  -->
+<xi:include href="perl.xml" />
+<xi:include href="python.xml" />
 <xi:include href="qt.xml" />
+<xi:include href="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md  -->
+<xi:include href="ruby.xml" />
 <xi:include href="texlive.xml" />
-<xi:include href="bower.xml" />
 
 
 </chapter>
-
diff --git a/doc/languages-frameworks/python.md b/doc/languages-frameworks/python.md
index c6d38c6989a7..dd9af4e827e2 100644
--- a/doc/languages-frameworks/python.md
+++ b/doc/languages-frameworks/python.md
@@ -78,18 +78,16 @@ containing
 ```nix
 with import <nixpkgs> {};
 
-(pkgs.python35.buildEnv.override  {
-  extraLibs = with pkgs.python35Packages; [ numpy toolz ];
-}).env
+(pkgs.python35.withPackages (ps: [ps.numpy ps.toolz])).env
 ```
 executing `nix-shell` gives you again a Nix shell from which you can run Python.
 
 What's happening here?
 
 1. We begin with importing the Nix Packages collections. `import <nixpkgs>` import the `<nixpkgs>` function, `{}` calls it and the `with` statement brings all attributes of `nixpkgs` in the local scope. Therefore we can now use `pkgs`.
-2. Then we create a Python 3.5 environment with `pkgs.buildEnv`. Because we want to use it with a custom set of Python packages, we override it.
-3. The `extraLibs` argument of the original `buildEnv` function can be used to specify which packages should be included. We want `numpy` and `toolz`. Again, we use the `with` statement to bring a set of attributes into the local scope.
-4. And finally, for in interactive use we return the environment.
+2. Then we create a Python 3.5 environment with the `withPackages` function.
+3. The `withPackages` function expects us to provide a function as an argument that takes the set of all python packages and returns a list of packages to include in the environment. Here, we select the packages `numpy` and `toolz` from the package set.
+4. And finally, for in interactive use we return the environment by using the `env` attribute.
 
 ### Developing with Python
 
@@ -187,10 +185,7 @@ with import <nixpkgs> {};
       };
     };
 
-  in pkgs.python35.buildEnv.override rec {
-
-    extraLibs = [ pkgs.python35Packages.numpy toolz ];
-}
+  in pkgs.python35.withPackages (ps: [ps.numpy toolz])
 ).env
 ```
 
@@ -199,8 +194,11 @@ locally defined package as well as `numpy` which is build according to the
 definition in Nixpkgs. What did we do here? Well, we took the Nix expression
 that we used earlier to build a Python environment, and said that we wanted to
 include our own version of `toolz`. To introduce our own package in the scope of
-`buildEnv.override` we used a
+`withPackages` we used a
 [`let`](http://nixos.org/nix/manual/#sec-constructs) expression.
+You can see that we used `ps.numpy` to select numpy from the nixpkgs package set (`ps`).
+But we do not take `toolz` from the nixpkgs package set this time.
+Instead, `toolz` will resolve to our local definition that we introduced with `let`.
 
 ### Handling dependencies
 
@@ -359,7 +357,7 @@ own packages. The important functions here are `import` and `callPackage`.
 
 ### Including a derivation using `callPackage`
 
-Earlier we created a Python environment using `buildEnv`, and included the
+Earlier we created a Python environment using `withPackages`, and included the
 `toolz` package via a `let` expression.
 Let's split the package definition from the environment definition.
 
@@ -394,9 +392,7 @@ with import <nixpkgs> {};
 
 ( let
     toolz = pkgs.callPackage ~/path/to/toolz/release.nix { pkgs=pkgs; buildPythonPackage=pkgs.python35Packages.buildPythonPackage; };
-  in pkgs.python35.buildEnv.override rec {
-    extraLibs = [ pkgs.python35Packages.numpy  toolz ];
-}
+  in pkgs.python35.withPackages (ps: [ ps.numpy toolz ])
 ).env
 ```
 
@@ -450,6 +446,7 @@ Each interpreter has the following attributes:
 - `libPrefix`. Name of the folder in `${python}/lib/` for corresponding interpreter.
 - `interpreter`. Alias for `${python}/bin/${executable}`.
 - `buildEnv`. Function to build python interpreter environments with extra packages bundled together. See section *python.buildEnv function* for usage and documentation.
+- `withPackages`. Simpler interface to `buildEnv`. See section *python.withPackages function* for usage and documentation.
 - `sitePackages`. Alias for `lib/${libPrefix}/site-packages`.
 - `executable`. Name of the interpreter executable, ie `python3.4`.
 
@@ -548,7 +545,7 @@ Python environments can be created using the low-level `pkgs.buildEnv` function.
 This example shows how to create an environment that has the Pyramid Web Framework.
 Saving the following as `default.nix`
 
-    with import {};
+    with import <nixpkgs> {};
 
     python.buildEnv.override {
       extraLibs = [ pkgs.pythonPackages.pyramid ];
@@ -565,7 +562,7 @@ You can also use the `env` attribute to create local environments with needed
 packages installed. This is somewhat comparable to `virtualenv`. For example,
 running `nix-shell` with the following `shell.nix`
 
-    with import {};
+    with import <nixpkgs> {};
 
     (python3.buildEnv.override {
       extraLibs = with python3Packages; [ numpy requests ];
@@ -581,6 +578,37 @@ specified packages in its path.
 * `postBuild`: Shell command executed after the build of environment.
 * `ignoreCollisions`: Ignore file collisions inside the environment (default is `false`).
 
+#### python.withPackages function
+
+The `python.withPackages` function provides a simpler interface to the `python.buildEnv` functionality.
+It takes a function as an argument that is passed the set of python packages and returns the list 
+of the packages to be included in the environment. Using the `withPackages` function, the previous
+example for the Pyramid Web Framework environment can be written like this:
+
+    with import <nixpkgs> {};
+
+    python.withPackages (ps: [ps.pyramid])
+
+`withPackages` passes the correct package set for the specific interpreter version as an 
+argument to the function. In the above example, `ps` equals `pythonPackages`.
+But you can also easily switch to using python3:
+    
+    with import <nixpkgs> {};
+
+    python3.withPackages (ps: [ps.pyramid])
+
+Now, `ps` is set to `python3Packages`, matching the version of the interpreter.
+
+As `python.withPackages` simply uses `python.buildEnv` under the hood, it also supports the `env`
+attribute. The `shell.nix` file from the previous section can thus be also written like this:
+
+    with import <nixpkgs> {};
+
+    (python33.withPackages (ps: [ps.numpy ps.requests])).env
+
+In contrast to `python.buildEnv`, `python.withPackages` does not support the more advanced options
+such as `ignoreCollisions = true` or `postBuild`. If you need them, you have to use `python.buildEnv`.
+
 ### Development mode
 
 Development or editable mode is supported. To develop Python packages
@@ -591,7 +619,7 @@ Warning: `shellPhase` is executed only if `setup.py` exists.
 
 Given a `default.nix`:
 
-    with import {};
+    with import <nixpkgs> {};
 
     buildPythonPackage { name = "myproject";
 
@@ -649,9 +677,8 @@ newpkgs = pkgs.overridePackages(self: super: rec {
     self = python35Packages // { pandas = python35Packages.pandas.override{name="foo";};};
   };
 });
-in newpkgs.python35.buildEnv.override{
-  extraLibs = [newpkgs.python35Packages.blaze ];
-}).env
+in newpkgs.python35.withPackages (ps: [ps.blaze])
+).env
 ```
 A typical use case is to switch to another version of a certain package. For example, in the Nixpkgs repository we have multiple versions of `django` and `scipy`.
 In the following example we use a different version of `scipy`. All packages in `newpkgs` will now use the updated `scipy` version.
@@ -665,9 +692,8 @@ newpkgs = pkgs.overridePackages(self: super: rec {
     self = python35Packages // { scipy = python35Packages.scipy_0_16;};
   };
 });
-in pkgs.python35.buildEnv.override{
-  extraLibs = [newpkgs.python35Packages.blaze ];
-}).env
+in newpkgs.python35.withPackages (ps: [ps.blaze])
+).env
 ```
 The requested package `blaze` depends upon `pandas` which itself depends on `scipy`.
 
diff --git a/doc/manual.xml b/doc/manual.xml
index 1045d0d4f815..32e94e8e59c5 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -20,8 +20,6 @@
   <xi:include href="package-notes.xml" />
   <xi:include href="coding-conventions.xml" />
   <xi:include href="submitting-changes.xml" />
-  <xi:include href="haskell-users-guide.xml" />
-  <xi:include href="beam-users-guide.xml" />
   <xi:include href="contributing.xml" />
 
 </book>