Merge remote-tracking branch 'origin/staging' into systemd-219

Conflicts:
	pkgs/os-specific/linux/kernel/linux-3.4.nix
	pkgs/os-specific/linux/systemd/default.nix

.version

@@ -1 +1 @@
-15.06
+15.07

CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# How to contribute
+
+## Opening issues
+
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* [Submit an issue](https://github.com/NixOS/nixpkgs/issues) - assuming one does not already exist.
+  * Clearly describe the issue including steps to reproduce when it is a bug.
+  * Include information what version of nixpkgs and Nix are you using (nixos-version or git revision).
+
+## Submitting changes
+
+See the nixpkgs manual for details on how to [Submit changes to nixpkgs](http://hydra.nixos.org/job/nixpkgs/trunk/manual/latest/download-by-type/doc/manual#chap-submitting-changes).

README.md

@@ -5,7 +5,7 @@
 [![Issue Stats](http://www.issuestats.com/github/nixos/nixpkgs/badge/issue)](http://www.issuestats.com/github/nixos/nixpkgs)
 
 Nixpkgs is a collection of packages for the [Nix](https://nixos.org/nix/) package
-manager. It is periodically build and tested by the [hydra](http://hydra.nixos.org/)
+manager. It is periodically built and tested by the [hydra](http://hydra.nixos.org/)
 build daemon as so-called channels. To get channel information via git, add
 [nixpkgs-channels](https://github.com/NixOS/nixpkgs-channels.git) as a remote:
 
@@ -15,7 +15,7 @@ build daemon as so-called channels. To get channel information via git, add
 
 For stability and maximum binary package support, it is recommended to maintain
 custom changes on top of one of the channels, e.g. `nixos-14.12` for the latest
-release and `nixos-unstable` for the latest successfully build master:
+release and `nixos-unstable` for the latest successful build of master:
 
 ```
 % git remote update channels
@@ -40,6 +40,3 @@ Communication:
 
 * [Mailing list](http://lists.science.uu.nl/mailman/listinfo/nix-dev)
 * [IRC - #nixos on freenode.net](irc://irc.freenode.net/#nixos)
-
----
-[![Throughput Graph](https://graphs.waffle.io/nixos/nixpkgs/throughput.svg)](https://waffle.io/nixos/nixpkgs/metrics)

doc/coding-conventions.xml

@@ -5,7 +5,7 @@
 <title>Coding conventions</title>
 
 
-<section><title>Syntax</title>
+<section xml:id="sec-syntax"><title>Syntax</title>
 
 <itemizedlist>
 
@@ -207,7 +207,7 @@ args.stdenv.mkDerivation (args // {
 </section>
 
 
-<section><title>Package naming</title>
+<section xml:id="sec-package-naming"><title>Package naming</title>
 
 <para>In Nixpkgs, there are generally three different names associated with a package:
 
@@ -292,7 +292,7 @@ dashes between words — not in camel case.  For instance, it should be
 <filename>allPackages.nix</filename> or
 <filename>AllPackages.nix</filename>.</para>
 
-<section><title>Hierarchy</title>
+<section xml:id="sec-hierarchy"><title>Hierarchy</title>
 
 <para>Each package should be stored in its own directory somewhere in
 the <filename>pkgs/</filename> tree, i.e. in
@@ -451,12 +451,17 @@ splitting up an existing category.</para>
     </listitem>
   </varlistentry>
   <varlistentry>
-    <term>If it’s a <emphasis>desktop environment</emphasis>
-    (including <emphasis>window managers</emphasis>):</term>
+    <term>If it’s a <emphasis>desktop environment</emphasis>:</term>
     <listitem>
       <para><filename>desktops</filename> (e.g. <filename>kde</filename>, <filename>gnome</filename>, <filename>enlightenment</filename>)</para>
     </listitem>
   </varlistentry>
+  <varlistentry>
+    <term>If it’s a <emphasis>window manager</emphasis>:</term>
+    <listitem>
+      <para><filename>applications/window-managers</filename> (e.g. <filename>awesome</filename>, <filename>compiz</filename>, <filename>stumpwm</filename>)</para>
+    </listitem>
+  </varlistentry>
   <varlistentry>
     <term>If it’s an <emphasis>application</emphasis>:</term>
     <listitem>
@@ -620,33 +625,39 @@ evaluate correctly.</para>
     fetchers from <literal>pkgs/build-support/</literal>. As an example going
     from bad to good:
     <itemizedlist>
-      <listitem><para>Uses <literal>git://</literal> which won't be proxied.
-        <programlisting>
-          src = fetchgit {
-            url = "git://github.com/NixOS/nix.git";
-            rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-            sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
-          }
-        </programlisting></para>
+      <listitem>
+        <para>Uses <literal>git://</literal> which won't be proxied.
+<programlisting>
+src = fetchgit {
+  url = "git://github.com/NixOS/nix.git";
+  rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
+  sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
+}
+</programlisting>
+        </para>
       </listitem>
-      <listitem><para>This is ok, but an archive fetch will still be faster.
-        <programlisting>
-          src = fetchgit {
-            url = "https://github.com/NixOS/nix.git";
-            rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-            sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
-          }
-        </programlisting></para>
+      <listitem>
+        <para>This is ok, but an archive fetch will still be faster.
+<programlisting>
+src = fetchgit {
+  url = "https://github.com/NixOS/nix.git";
+  rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
+  sha256 = "1cw5fszffl5pkpa6s6wjnkiv6lm5k618s32sp60kvmvpy7a2v9kg";
+}
+</programlisting>
+        </para>
       </listitem>
-      <listitem><para>Fetches a snapshot archive and you get the rev you want.
-        <programlisting>
-          src = fetchFromGitHub {
-            owner = "NixOS";
-            repo = "nix";
-            rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
-            sha256 = "04yri911rj9j19qqqn6m82266fl05pz98inasni0vxr1cf1gdgv9";
-          }
-        </programlisting></para>
+      <listitem>
+        <para>Fetches a snapshot archive and you get the rev you want.
+<programlisting>
+src = fetchFromGitHub {
+  owner = "NixOS";
+  repo = "nix";
+  rev = "1f795f9f44607cc5bec70d1300150bfefcef2aae";
+  sha256 = "04yri911rj9j19qqqn6m82266fl05pz98inasni0vxr1cf1gdgv9";
+}
+</programlisting>
+        </para>
       </listitem>
     </itemizedlist>
   </para>

doc/contributing.xml

@@ -2,18 +2,19 @@
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="chap-contributing">
 
-<title>Contributing</title>
+<title>Contributing to this documentation</title>
 
-<para>If you make modifications to the manual, it's important to build the manual before contributing:</para>
+<para>The DocBook sources of the Nixpkgs manual are in the <filename
+xlink:href="https://github.com/NixOS/nixpkgs/tree/master/doc">doc</filename>
+subdirectory of the Nixpkgs repository. If you make modifications to
+the manual, it's important to build it before committing. You can do that as follows:
 
-<orderedlist>
+<screen>
+$ cd /path/to/nixpkgs
+$ nix-build doc
+</screen>
 
-  <listitem><para><command>$ git clone git://github.com/NixOS/nixpkgs.git</command></para></listitem>
-
-  <listitem><para><command>$ nix-build -A manual nixpkgs/pkgs/top-level/release.nix</command></para></listitem>
-
-  <listitem><para>Inside the built derivation you shall see <literal>manual/index.html</literal> file.</para></listitem>
-
-</orderedlist>
+If the build succeeds, the manual will be in
+<filename>./result/share/doc/nixpkgs/manual.html</filename>.</para>
 
 </chapter>

doc/default.nix

@@ -36,6 +36,9 @@ stdenv.mkDerivation {
 
     cp ${./style.css} $dst/style.css
 
+    mkdir -p $dst/images/callouts
+    cp ${docbook5_xsl}/xml/xsl/docbook/images/callouts/*.gif $dst/images/callouts/
+
     mkdir -p $out/nix-support
     echo "doc manual $dst manual.html" >> $out/nix-support/hydra-build-products
   '';

doc/functions.xml

@@ -0,0 +1,120 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+	 xmlns:xlink="http://www.w3.org/1999/xlink"
+	 xml:id="chap-functions">
+
+<title>Functions reference</title>
+
+<para>
+  The nixpkgs repository has several utility functions to manipulate Nix expressions.
+</para>
+
+<section xml:id="sec-pkgs-overridePackages">
+  <title>pkgs.overridePackages</title>
+
+  <para>
+    This function inside the nixpkgs expression (<varname>pkgs</varname>)
+    can be used to override the set of packages itself.
+  </para>
+  <para>
+    Warning: this function is expensive and must not be used from within
+    the nixpkgs repository.
+  </para>
+  <para>
+    Example usage:
+
+    <programlisting>let
+  pkgs = import &lt;nixpkgs&gt; {};
+  newpkgs = pkgs.overridePackages (self: super: {
+    foo = super.foo.override { ... };
+  };
+in ...</programlisting>
+  </para>
+
+  <para>
+    The resulting <varname>newpkgs</varname> will have the new <varname>foo</varname>
+    expression, and all other expressions depending on <varname>foo</varname> will also
+    use the new <varname>foo</varname> expression.
+  </para>
+
+  <para>
+    The behavior of this function is similar to <link 
+    linkend="sec-modify-via-packageOverrides">config.packageOverrides</link>.
+  </para>
+
+  <para>
+    The <varname>self</varname> parameter refers to the final package set with the
+    applied overrides. Using this parameter may lead to infinite recursion if not
+    used consciously.
+  </para>
+
+  <para>
+    The <varname>super</varname> parameter refers to the old package set.
+    It's equivalent to <varname>pkgs</varname> in the above example.
+  </para>
+
+</section>
+
+<section xml:id="sec-pkg-override">
+  <title>&lt;pkg&gt;.override</title>
+
+  <para>
+    The function <varname>override</varname> is usually available for all the
+    derivations in the nixpkgs expression (<varname>pkgs</varname>).
+  </para>
+  <para>
+    It is used to override the arguments passed to a function.
+  </para>
+  <para>
+    Example usages:
+
+    <programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting>
+    <programlisting>pkgs.overridePackages (self: super: {
+  foo = super.foo.override { barSupport = true ; };
+})</programlisting>
+    <programlisting>mypkg = pkgs.callPackage ./mypkg.nix {
+  mydep = pkgs.mydep.override { ... };
+})</programlisting>
+  </para>
+
+  <para>
+    In the first example, <varname>pkgs.foo</varname> is the result of a function call
+    with some default arguments, usually a derivation.
+    Using <varname>pkgs.foo.override</varname> will call the same function with
+    the given new arguments.
+  </para>
+
+</section>
+
+<section xml:id="sec-lib-makeOverridable">
+  <title>lib.makeOverridable</title>
+
+  <para>
+    The function <varname>lib.makeOverridable</varname> is used make the result
+    of a function easily customizable. This utility only makes sense for functions
+    that accept an argument set and return an attribute set.
+  </para>
+
+  <para>
+    Example usage:
+
+    <programlisting>f = { a, b }: { result = a+b; }
+c = lib.makeOverridable f { a = 1; b = 2; }</programlisting>
+
+  </para>
+
+  <para>
+    The variable <varname>c</varname> is the value of the <varname>f</varname> function
+    applied with some default arguments. Hence the value of <varname>c.result</varname>
+    is <literal>3</literal>, in this example.
+  </para>
+
+  <para>
+    The variable <varname>c</varname> however also has some additional functions, like
+    <link linkend="sec-pkg-override">c.override</link> which can be used to
+    override the default arguments. In this example the value of
+    <varname>(c.override { a = 4; }).result</varname> is 6.
+  </para>
+
+</section>
+
+</chapter>