WIP: splitting packages into multiple outputs

.github/ISSUE_TEMPLATE.md

@@ -1,17 +1,13 @@
-## Basic info
+## Issue description
 
-To make sure that we are on the same page:
 
-* Kernel: (run `uname -a`)
-* System: (NixOS: `nixos-version`, Ubuntu/Fedora: `lsb_release -a`, ...)
-* Nix version: (run `nix-env --version`)
-* Nixpkgs version: (run `nix-instantiate --eval '<nixpkgs>' -A lib.nixpkgsVersion`)
 
-## Describe your issue here
+### Steps to reproduce
 
-### Expected result
 
-### Actual result
 
-### Steps to reproduce
+## Technical details
 
+* System: (NixOS: `nixos-version`, Ubuntu/Fedora: `lsb_release -a`, ...)
+* Nix version: (run `nix-env --version`)
+* Nixpkgs version: (run `nix-instantiate --eval '<nixpkgs>' -A lib.nixpkgsVersion`)

README.md

@@ -14,12 +14,12 @@ 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-15.09` for the latest
+custom changes on top of one of the channels, e.g. `nixos-16.03` for the latest
 release and `nixos-unstable` for the latest successful build of master:
 
 ```
 % git remote update channels
-% git rebase channels/nixos-15.09
+% git rebase channels/nixos-16.03
 ```
 
 For pull-requests, please rebase onto nixpkgs `master`.
@@ -33,9 +33,9 @@ For pull-requests, please rebase onto nixpkgs `master`.
 * [Manual (NixOS)](https://nixos.org/nixos/manual/)
 * [Nix Wiki](https://nixos.org/wiki/)
 * [Continuous package builds for unstable/master](https://hydra.nixos.org/jobset/nixos/trunk-combined)
-* [Continuous package builds for 15.09 release](https://hydra.nixos.org/jobset/nixos/release-15.09)
+* [Continuous package builds for 16.03 release](https://hydra.nixos.org/jobset/nixos/release-16.03)
 * [Tests for unstable/master](https://hydra.nixos.org/job/nixos/trunk-combined/tested#tabs-constituents)
-* [Tests for 15.09 release](https://hydra.nixos.org/job/nixos/release-15.09/tested#tabs-constituents)
+* [Tests for 16.03 release](https://hydra.nixos.org/job/nixos/release-16.03/tested#tabs-constituents)
 
 Communication:
 

doc/introduction.md

@@ -6,43 +6,48 @@ date: 2015-11-25
 
 # Introduction
 
-The Nix Packages collection (Nixpkgs) is a set of over 30,000 packages for the
-[Nix package manager](http://nixos.org/nix/), released under a [permissive MIT/X11 license](https://github.com/NixOS/nixpkgs/blob/master/COPYING).
-Packages are available for several architectures, and can be used with the Nix package manager
-on most GNU/Linux distributions as well as NixOS.
-
-This manual describes how to write packages for the Nix Packages collection
-(Nixpkgs). Thus it’s for packagers and developers who want to add packages to
+The Nix Packages collection (Nixpkgs) is a set of thousands of packages for the
+[Nix package manager](http://nixos.org/nix/), released under a
+[permissive MIT/X11 license](https://github.com/NixOS/nixpkgs/blob/master/COPYING).
+Packages are available for several platforms, and can be used with the Nix
+package manager on most GNU/Linux distributions as well as NixOS.
+
+This manual primarily describes how to write packages for the Nix Packages collection
+(Nixpkgs). Thus it’s mainly for packagers and developers who want to add packages to
 Nixpkgs. If you like to learn more about the Nix package manager and the Nix
 expression language, then you are kindly referred to the [Nix manual](http://nixos.org/nix/manual/).
 
 ## Overview of Nixpkgs
 
 Nix expressions describe how to build packages from source and are collected in
 the [nixpkgs repository](https://github.com/NixOS/nixpkgs). Also included in the
-collection are Nix expressions for [NixOS modules](http://nixos.org/nixos/manual/index.html#sec-writing-modules). With
-these expressions the Nix package manager can build binary packages.
+collection are Nix expressions for
+[NixOS modules](http://nixos.org/nixos/manual/index.html#sec-writing-modules).
+With these expressions the Nix package manager can build binary packages.
 
 Packages, including the Nix packages collection, are distributed through
 [channels](http://nixos.org/nix/manual/#sec-channels). The collection is
 distributed for users of Nix on non-NixOS distributions through the channel
 `nixpkgs`. Users of NixOS generally use one of the `nixos-*` channels, e.g.
-`nixos-15.09`, which includes all packages and modules for the stable NixOS
-15.09. The channels of the stable NixOS releases are generally only given
+`nixos-16.03`, which includes all packages and modules for the stable NixOS
+16.03. The purpose of stable NixOS releases are generally only given
 security updates. More up to date packages and modules are available via the
 `nixos-unstable` channel.
 
 Both `nixos-unstable` and `nixpkgs` follow the `master` branch of the Nixpkgs
-repository, although both do lag the `master` branch by generally [a couple of days](http://howoldis.herokuapp.com/). Updates to a channel are distributed as
-soon as all tests for that channel pass, e.g. [this table](http://hydra.nixos.org/job/nixpkgs/trunk/unstable#tabs-constituents)
+repository, although both do lag the `master` branch by generally
+[a couple of days](http://howoldis.herokuapp.com/). Updates to a channel are
+distributed as soon as all tests for that channel pass, e.g.
+[this table](http://hydra.nixos.org/job/nixpkgs/trunk/unstable#tabs-constituents)
 shows the status of tests for the `nixpkgs` channel.
 
 The tests are conducted by a cluster called [Hydra](http://nixos.org/hydra/),
-which also builds binary packages from the Nix expressions in Nixpkgs. As soon
-as a channel is updated, the binaries are made available via a [binary cache](https://cache.nixos.org). Until the channel updates, binaries that have
-already been built, are available via [Hydra's binary cache](https://hydra.nixos.org).
+which also builds binary packages from the Nix expressions in Nixpkgs for
+`x86_64-linux`, `i686-linux` and `x86_64-darwin`.
+The binaries are made available via a [binary cache](https://cache.nixos.org).
 
 The current Nix expressions of the channels are available in the
 [`nixpkgs-channels`](https://github.com/NixOS/nixpkgs-channels) repository,
 which has branches corresponding to the available channels. There is also the
-Nixpkgs Monitor which keeps track of updates and security vulnerabilities.
+[Nixpkgs Monitor](http://monitor.nixos.org) which keeps track of updates
+and security vulnerabilities.

doc/manual.xml

@@ -12,6 +12,7 @@
   <xi:include href="introduction.xml" />
   <xi:include href="quick-start.xml" />
   <xi:include href="stdenv.xml" />
+  <xi:include href="multiple-output.xml" />
   <xi:include href="configuration.xml" />
   <xi:include href="functions.xml" />
   <xi:include href="meta.xml" />

doc/multiple-output.xml

@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter [
+  <!ENTITY ndash "&#x2013;"> <!-- @vcunat likes to use this one ;-) -->
+]>
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="chap-multiple-output">
+
+<title>Multiple-output packages</title>
+
+<section><title>Introduction</title>
+  <para>The Nix language allows a derivation to produce multiple outputs, which is similar to what is utilized by other Linux distribution packaging systems.  The outputs reside in separate nix store paths, so they can be mostly handled independently of each other, including passing to build inputs, garbage collection or binary substitution.  The exception is that building from source always produces all the outputs.</para>
+  <para>The main motivation is to save disk space by reducing runtime closure sizes; consequently also sizes of substituted binaries get reduced.  Splitting can be used to have more granular runtime dependencies, for example the typical reduction is to split away development-only files, as those are typically not needed during runtime.  As a result, closure sizes of many packages can get reduced to a half or even much less.</para>
+  <note><para>The reduction effects could be instead achieved by building the parts in completely separate derivations.  That would often additionally reduce build-time closures, but it tends to be much harder to write such derivations, as build systems typically assume all parts are being built at once.  This compromise approach of single source package producing multiple binary packages is also utilized often by rpm and deb.</para></note>
+</section>
+
+<section><title>Installing a split package</title>
+  <para>When installing a package via <varname>systemPackages</varname> or <command>nix-env</command> you have several options:</para>
+  <warning><para>Currently <command>nix-env</command> almost always installs all outputs until https://github.com/NixOS/nix/pull/815 gets merged.</para></warning>
+  <itemizedlist>
+    <listitem><para>You can install particular outputs explicitly, as each is available in the Nix language as an attribute of the package.  The <varname>outputs</varname> attribute contains a list of output names.</para></listitem>
+    <listitem><para>You can let it use the default outputs.  These are handled by <varname>meta.outputsToInstall</varname> attribute that contains a list of output names.</para>
+      <para>TODO: more about tweaking the attribute, etc.</para></listitem>
+    <listitem><para>NixOS provides configuration option <varname>environment.extraOutputsToInstall</varname> that allows adding extra outputs of <varname>environment.systemPackages</varname> atop the default ones.  It's mainly meant for documentation and debug symbols, and it's also modified by specific options.</para>
+      <note><para>At this moment there is no similar configurability for packages installed by <command>nix-env</command>.  You can still use approach from <xref linkend="sec-modify-via-packageOverrides" /> to override <varname>meta.outputsToInstall</varname> attributes, but that's a rather inconvenient way.</para></note>
+    </listitem>
+  </itemizedlist>
+</section>
+
+<section><title>Using a split package</title>
+  <para>In the Nix language the individual outputs can be reached explicitly as attributes, e.g. <varname>coreutils.info</varname>, but the typical case is just using packages as build inputs.</para>
+  <para>When a multiple-output derivation gets into a build input of another derivation, the first output is added (<varname>.dev</varname> by convention) and also <varname>propagatedBuildOutputs</varname> of that package which by default contain <varname>$outputBin</varname> and <varname>$outputLib</varname>. (See <xref linkend="multiple-output-file-type-groups" />.)</para>
+</section>
+
+
+<section><title>Writing a split derivation</title>
+  <para>Here you find how to write a derivation that produces multiple outputs.</para>
+  <para>In nixpkgs there is a framework supporting multiple-output derivations. It tries to cover most cases by default behavior.  You can find the source separated in &lt;<filename>nixpkgs/pkgs/build-support/setup-hooks/multiple-outputs.sh</filename>&gt;; it's relatively well-readable.  The whole machinery is triggered by defining the <varname>outputs</varname> attribute to contain the list of desired output names (strings).</para>
+  <programlisting>outputs = [ "dev" "out" "bin" "doc" ];</programlisting>
+  <para>Often such a single line is enough.  For each output an equally named environment variable is passed to the builder and contains the path in nix store for that output.  By convention, the first output should usually be <varname>dev</varname>; typically you also want to have the main <varname>out</varname> output, as it catches any files that didn't get elsewhere.</para>
+
+  <note><para>There is a special handling of the <varname>debug</varname> output, described at <xref linkend="stdenv-separateDebugInfo" />.</para></note>
+
+  <section xml:id="multiple-output-file-type-groups">
+    <title>File type groups</title>
+    <para>The support code currently recognizes some particular kinds of outputs and either instructs the build system of the package to put files into their desired outputs or it moves the files during the fixup phase.  Each group of file types has an <varname>outputFoo</varname> variable specifying the output name where they should go.  If that variable isn't defined by the derivation writer, it is guessed &ndash; a default output name is defined, falling back to other possibilities if the output isn't defined.</para>
+    <variablelist>
+      <varlistentry><term><varname>
+         $outputDev</varname></term><listitem><para>
+         is for development-only files. These include C(++) headers, pkg-config, cmake and aclocal files.  They go to <varname>dev</varname> or <varname>out</varname> by default.
+        </para></listitem></varlistentry>
+      <varlistentry><term><varname>
+        $outputBin</varname></term><listitem><para>
+        is meant for user-facing binaries, typically residing in bin/.  They go to <varname>bin</varname> or <varname>out</varname> by default.
+        </para></listitem></varlistentry>
+      <varlistentry><term><varname>
+        $outputLib</varname></term><listitem><para>
+        is meant for libraries, typically residing in <filename>lib/</filename> and <filename>libexec/</filename>.  They go to <varname>lib</varname> or <varname>out</varname> by default.
+        </para></listitem></varlistentry>
+      <varlistentry><term><varname>
+        $outputDoc</varname></term><listitem><para>
+        is for user documentation, typically residing in <filename>share/doc/</filename>.  It goes to <varname>doc</varname> or <varname>out</varname> by default.
+        </para></listitem></varlistentry>
+      <varlistentry><term><varname>
+        $outputDocdev</varname></term><listitem><para>
+        is for <emphasis>developer</emphasis> documentation.  Currently we count gtk-doc and man3 pages in there.  It goes to <varname>docdev</varname> or is removed (!) by default.  This is because e.g. gtk-doc tends to be rather large and completely unused by nixpkgs users.
+        </para></listitem></varlistentry>
+      <varlistentry><term><varname>
+        $outputMan</varname></term><listitem><para>
+        is for man pages (except for section 3). They go to <varname>man</varname> or <varname>doc</varname> or <varname>$outputBin</varname> by default.
+        </para></listitem></varlistentry>
+      <varlistentry><term><varname>
+        $outputInfo</varname></term><listitem><para>
+        is for info pages. They go to <varname>info</varname> or <varname>doc</varname> or <varname>$outputMan</varname> by default.
+        </para></listitem></varlistentry>
+    </variablelist>
+  </section>
+
+  <section><title>Common caveats</title>
+    <itemizedlist>
+      <listitem><para>Some configure scripts don't like some of the parameters passed by default by the framework, e.g. <literal>--docdir=/foo/bar</literal>.  You can disable this by setting <literal>setOutputFlags = false;</literal>.</para></listitem>
+      <listitem><para>The outputs of a single derivation can retain references to each other, but note that circular references are not allowed.  (And each strongly-connected component would act as a single output anyway.)</para></listitem>
+      <listitem><para>Most of split packages contain their core functionality in libraries.  These libraries tend to refer to various kind of data that typically gets into <varname>out</varname>, e.g. locale strings, so there is often no advantage in separating the libraries into <varname>lib</varname>, as keeping them in <varname>out</varname> is easier.</para></listitem>
+      <listitem><para>Some packages have hidden assumptions on install paths, which complicates splitting.</para></listitem>
+    </itemizedlist>
+  </section>
+
+</section><!--Writing a split derivation-->
+
+</chapter>
+

doc/stdenv.xml

@@ -956,7 +956,7 @@ following:
     phase.</para></listitem>
   </varlistentry>
 
-  <varlistentry>
+  <varlistentry xml:id="stdenv-separateDebugInfo">
     <term><varname>separateDebugInfo</varname></term>
     <listitem><para>If set to <literal>true</literal>, the standard
     environment will enable debug information in C/C++ builds. After

lib/customisation.nix

@@ -129,7 +129,7 @@ rec {
         };
 
       outputsList = map outputToAttrListElement outputs;
-  in commonAttrs.${drv.outputName};
+  in commonAttrs // { outputUnspecified = true; };
 
 
   /* Strip a derivation of all non-essential attributes, returning

lib/maintainers.nix

@@ -81,6 +81,7 @@
   copumpkin = "Dan Peebles <pumpkingod@gmail.com>";
   coroa = "Jonas Hörsch <jonas@chaoflow.net>";
   couchemar = "Andrey Pavlov <couchemar@yandex.ru>";
+  CrystalGamma = "Jona Stubbe <nixos@crystalgamma.de>";
   cstrahan = "Charles Strahan <charles.c.strahan@gmail.com>";
   cwoac = "Oliver Matthews <oliver@codersoffortune.net>";
   DamienCassou = "Damien Cassou <damien@cassou.me>";
@@ -117,6 +118,7 @@
   ertes = "Ertugrul Söylemez <ertesx@gmx.de>";
   exi = "Reno Reckling <nixos@reckling.org>";
   exlevan = "Alexey Levan <exlevan@gmail.com>";
+  expipiplus1 = "Joe Hermaszewski <nix@monoid.al>";
   fadenb = "Tristan Helmich <tristan.helmich+nixos@gmail.com>";
   falsifian = "James Cook <james.cook@utoronto.ca>";
   flosse = "Markus Kohlhase <mail@markus-kohlhase.de>";
@@ -186,6 +188,7 @@
   ktosiek = "Tomasz Kontusz <tomasz.kontusz@gmail.com>";
   lassulus = "Lassulus <lassulus@gmail.com>";
   layus = "Guillaume Maudoux <layus.on@gmail.com>";
+  ldesgoui = "Lucas Desgouilles <ldesgoui@gmail.com>";
   lebastr = "Alexander Lebedev <lebastr@gmail.com>";
   leenaars = "Michiel Leenaars <ml.software@leenaa.rs>";
   leonardoce = "Leonardo Cecchi <leonardo.cecchi@gmail.com>";

lib/strings.nix

@@ -98,7 +98,9 @@ rec {
        makeLibraryPath [ pkgs.openssl pkgs.zlib ]
        => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r/lib:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/lib"
   */
-  makeLibraryPath = makeSearchPath "lib";
+  makeLibraryPath = pkgs: makeSearchPath "lib"
+    # try to guess the right output of each pkg
+    (map (pkg: pkg.lib or (pkg.out or pkg)) pkgs);
 
   /* Construct a binary search path (such as $PATH) containing the
      binaries for a set of packages.
@@ -258,7 +260,7 @@ rec {
   /* Cut a string with a separator and produces a list of strings which
      were separated by this separator.
 
-     NOTE: this function is not performant and should be avoided
+     NOTE: this function is not performant and should never be used.
 
      Example:
        splitString "." "foo.bar.baz"

maintainers/scripts/find-tarballs.nix

@@ -14,12 +14,12 @@ let
     operator = const [ ];
   });
 
-  urls = map (drv: { url = head drv.urls; hash = drv.outputHash; type = drv.outputHashAlgo; }) fetchurlDependencies;
+  urls = map (drv: { url = head (drv.urls or [ drv.url ]); hash = drv.outputHash; type = drv.outputHashAlgo; }) fetchurlDependencies;
 
   fetchurlDependencies =
     filter
       (drv: drv.outputHash or "" != "" && drv.outputHashMode or "flat" == "flat"
-          && drv.postFetch or "" == "" && drv ? urls)
+          && drv.postFetch or "" == "" && (drv ? url || drv ? urls))
       dependencies;
 
   dependencies = map (x: x.value) (genericClosure {

nixos/doc/manual/default.nix

@@ -44,7 +44,7 @@ let
       echo "for hints about the offending path)."
       exit 1
     fi
-    ${libxslt}/bin/xsltproc \
+    ${libxslt.bin}/bin/xsltproc \
       --stringparam revision '${revision}' \
       -o $out ${./options-to-docbook.xsl} $optionsXML
   '';