diff --git a/doc/stdenv/multiple-output.xml b/doc/stdenv/multiple-output.xml
index 83275bb2fbd1..1c22bcb99e76 100644
--- a/doc/stdenv/multiple-output.xml
+++ b/doc/stdenv/multiple-output.xml
@@ -22,39 +22,69 @@
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.
+
+
+ A number of attributes can be used to work with a derivation with multiple outputs. The attribute outputs is a list of strings, which are the names of the outputs. For each of these names, an identically named attribute is created, corresponding to that output. The attribute meta.outputsToInstall is used to determine the default set of outputs to install when using the derivation name unqualified.
+
+
Installing a split package
- When installing a package via systemPackages or nix-env you have several options:
+ When installing a package with multiple outputs, the package's meta.outputsToInstall attribute determines which outputs are actually installed. meta.outputsToInstall is a list whose default installs binaries and the associated man pages. The following sections describe ways to install different outputs.
-
-
-
- You can install particular outputs explicitly, as each is available in the Nix language as an attribute of the package. The outputs attribute contains a list of output names.
-
-
-
-
- You can let it use the default outputs. These are handled by meta.outputsToInstall attribute that contains a list of output names.
-
-
- TODO: more about tweaking the attribute, etc.
-
-
-
-
- NixOS provides configuration option environment.extraOutputsToInstall that allows adding extra outputs of environment.systemPackages atop the default ones. It's mainly meant for documentation and debug symbols, and it's also modified by specific options.
-
-
+
+ Selecting outputs to install via NixOS
+
+
+ NixOS provides two ways to select the outputs to install for packages listed in environment.systemPackages:
+
+
+
+
- At this moment there is no similar configurability for packages installed by nix-env. You can still use approach from to override meta.outputsToInstall attributes, but that's a rather inconvenient way.
+ The configuration option environment.extraOutputsToInstall is appended to each package's meta.outputsToInstall attribute to determine the outputs to install. It can for example be used to install info documentation or debug symbols for all packages.
-
-
-
+
+
+
+ The outputs can be listed as packages in environment.systemPackages. For example, the "out" and "info" outputs for the coreutils package can be installed by including coreutils and coreutils.info in environment.systemPackages.
+
+
+
+
+
+
+ Selecting outputs to install via <command>nix-env</command>
+
+
+ nix-env lacks an easy way to select the outputs to install. When installing a package, nix-env always installs the outputs listed in meta.outputsToInstall, even when the user explicitly selects an output.
+
+
+
+
+ nix-env silenty disregards the outputs selected by the user, and instead installs the outputs from meta.outputsToInstall. For example,
+
+$ nix-env -iA nixpkgs.coreutils.info
+
+ installs the "out" output (coreutils.meta.outputsToInstall is [ "out" ]) instead of the requested "info".
+
+
+
+
+ The only recourse to select an output with nix-env is to override the package's meta.outputsToInstall, using the functions described in . For example, the following overlay adds the "info" output for the coreutils package:
+
+
+self: super:
+{
+ coreutils = super.coreutils.overrideAttrs (oldAttrs: {
+ meta = oldAttrs.meta // { outputsToInstall = oldAttrs.meta.outputsToInstall or [ "out" ] ++ [ "info" ]; };
+ });
+}
+
+ Using a split package
diff --git a/pkgs/stdenv/generic/make-derivation.nix b/pkgs/stdenv/generic/make-derivation.nix
index a11b280b047e..7fb63acc31da 100644
--- a/pkgs/stdenv/generic/make-derivation.nix
+++ b/pkgs/stdenv/generic/make-derivation.nix
@@ -287,8 +287,12 @@ in rec {
name = attrs.name or "${attrs.pname}-${attrs.version}";
# If the packager hasn't specified `outputsToInstall`, choose a default,
- # which is the name of `p.bin or p.out or p`;
- # if he has specified it, it will be overridden below in `// meta`.
+ # which is the name of `p.bin or p.out or p` along with `p.man` when
+ # present.
+ #
+ # If the packager has specified it, it will be overridden below in
+ # `// meta`.
+ #
# Note: This default probably shouldn't be globally configurable.
# Services and users should specify outputs explicitly,
# unless they are comfortable with this default.