diff options
Diffstat (limited to 'doc/stdenv')
| -rw-r--r-- | doc/stdenv/multiple-output.xml | 74 | ||||
| -rw-r--r-- | doc/stdenv/stdenv.xml | 33 |
2 files changed, 77 insertions, 30 deletions
diff --git a/doc/stdenv/multiple-output.xml b/doc/stdenv/multiple-output.xml index 51e1cc2e024..20658918db7 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. </para> </note> + + <para> + A number of attributes can be used to work with a derivation with multiple outputs. The attribute <varname>outputs</varname> 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 <varname>meta.outputsToInstall</varname> is used to determine the default set of outputs to install when using the derivation name unqualified. + </para> + </section> <section xml:id="sec-multiple-outputs-installing"> <title>Installing a split package</title> <para> - When installing a package via <varname>systemPackages</varname> or <command>nix-env</command> you have several options: + When installing a package with multiple outputs, the package's <varname>meta.outputsToInstall</varname> attribute determines which outputs are actually installed. <varname>meta.outputsToInstall</varname> is a list whose <link xlink:href="https://github.com/NixOS/nixpkgs/blob/f1680774340d5443a1409c3421ced84ac1163ba9/pkgs/stdenv/generic/make-derivation.nix#L310-L320">default installs binaries and the associated man pages</link>. The following sections describe ways to install different outputs. </para> - <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> + <section xml:id="sec-multiple-outputs-installing-nixos"> + <title>Selecting outputs to install via NixOS</title> + + <para> + NixOS provides two ways to select the outputs to install for packages listed in <varname>environment.systemPackages</varname>: + </para> + + <itemizedlist> + <listitem> + <para> + The configuration option <varname>environment.extraOutputsToInstall</varname> is appended to each package's <varname>meta.outputsToInstall</varname> attribute to determine the outputs to install. It can for example be used to install <literal>info</literal> documentation or debug symbols for all packages. + </para> + </listitem> + <listitem> + <para> + The outputs can be listed as packages in <varname>environment.systemPackages</varname>. For example, the <literal>"out"</literal> and <literal>"info"</literal> outputs for the <varname>coreutils</varname> package can be installed by including <varname>coreutils</varname> and <varname>coreutils.info</varname> in <varname>environment.systemPackages</varname>. + </para> + </listitem> + </itemizedlist> + </section> + + <section xml:id="sec-multiple-outputs-installing-nix-env"> + <title>Selecting outputs to install via <command>nix-env</command></title> + + <para> + <command>nix-env</command> lacks an easy way to select the outputs to install. When installing a package, <command>nix-env</command> always installs the outputs listed in <varname>meta.outputsToInstall</varname>, even when the user explicitly selects an output. + </para> + + <warning> <para> - TODO: more about tweaking the attribute, etc. + <command>nix-env</command> silenty disregards the outputs selected by the user, and instead installs the outputs from <varname>meta.outputsToInstall</varname>. For example, </para> - </listitem> - <listitem> +<screen><prompt>$ </prompt>nix-env -iA nixpkgs.coreutils.info</screen> <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. + installs the <literal>"out"</literal> output (<varname>coreutils.meta.outputsToInstall</varname> is <literal>[ "out" ]</literal>) instead of the requested <literal>"info"</literal>. </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> + </warning> + + <para> + The only recourse to select an output with <command>nix-env</command> is to override the package's <varname>meta.outputsToInstall</varname>, using the functions described in <xref linkend="chap-overrides" />. For example, the following overlay adds the <literal>"info"</literal> output for the <varname>coreutils</varname> package: + </para> + +<programlisting>self: super: +{ + coreutils = super.coreutils.overrideAttrs (oldAttrs: { + meta = oldAttrs.meta // { outputsToInstall = oldAttrs.meta.outputsToInstall or [ "out" ] ++ [ "info" ]; }; + }); +} +</programlisting> + </section> </section> <section xml:id="sec-multiple-outputs-using-split-packages"> <title>Using a split package</title> diff --git a/doc/stdenv/stdenv.xml b/doc/stdenv/stdenv.xml index f97c2a145af..46ee97927ea 100644 --- a/doc/stdenv/stdenv.xml +++ b/doc/stdenv/stdenv.xml @@ -475,9 +475,12 @@ passthru.updateScript = writeScript "update-zoom-us" '' <programlisting> passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]; </programlisting> - </para> - <para> - The script will be usually run from the root of the Nixpkgs repository but you should not rely on that. Also note that the update scripts will be run in parallel by default; you should avoid running <command>git commit</command> or any other commands that cannot handle that. + The script will be run with <varname>UPDATE_NIX_ATTR_PATH</varname> environment variable set to the attribute path it is supposed to update. + <note> + <para> + The script will be usually run from the root of the Nixpkgs repository but you should not rely on that. Also note that the update scripts will be run in parallel by default; you should avoid running <command>git commit</command> or any other commands that cannot handle that. + </para> + </note> </para> <para> For information about how to run the updates, execute <command>nix-shell maintainers/scripts/update.nix</command>. @@ -1636,10 +1639,6 @@ substitute ./foo.in ./foo.out \ --subst-var someVar </programlisting> </para> - <para> - <function>substitute</function> is implemented using the <command - xlink:href="http://replace.richardlloyd.org.uk/">replace</command> command. Unlike with the <command>sed</command> command, you don’t have to worry about escaping special characters. It supports performing substitutions on binary files (such as executables), though there you’ll probably want to make sure that the replacement string is as long as the replaced string. - </para> </listitem> </varlistentry> <varlistentry xml:id='fun-substituteInPlace'> @@ -1836,6 +1835,19 @@ addEnvHooks "$hostOffset" myBashFunction </varlistentry> <varlistentry> <term> + <literal>move-systemd-user-units.sh</literal> + </term> + <listitem> + <para> + This setup hook moves any systemd user units installed in the lib + subdirectory into share. In addition, a link is provided from share to + lib for compatibility. This is needed for systemd to find user services + when installed into the user profile. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> <literal>set-source-date-epoch-to-latest.sh</literal> </term> <listitem> @@ -2058,7 +2070,7 @@ nativeBuildInputs = [ breakpointHook ]; The <literal>installManPage</literal> function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with <literal>.gz</literal> suffix). This function will place them into the correct directory. </para> <para> - The <literal>installShellCompletion</literal> function takes one or more paths to shell completion files. By default it will autodetect the shell type from the completion file extension, but you may also specify it by passing one of <literal>--bash</literal>, <literal>--fish</literal>, or <literal>--zsh</literal>. These flags apply to all paths listed after them (up until another shell flag is given). Each path may also have a custom installation name provided by providing a flag <literal>--name NAME</literal> before the path. If this flag is not provided, zsh completions will be renamed automatically such that <literal>foobar.zsh</literal> becomes <literal>_foobar</literal>. + The <literal>installShellCompletion</literal> function takes one or more paths to shell completion files. By default it will autodetect the shell type from the completion file extension, but you may also specify it by passing one of <literal>--bash</literal>, <literal>--fish</literal>, or <literal>--zsh</literal>. These flags apply to all paths listed after them (up until another shell flag is given). Each path may also have a custom installation name provided by providing a flag <literal>--name NAME</literal> before the path. If this flag is not provided, zsh completions will be renamed automatically such that <literal>foobar.zsh</literal> becomes <literal>_foobar</literal>. A root name may be provided for all paths using the flag <literal>--cmd NAME</literal>; this synthesizes the appropriate name depending on the shell (e.g. <literal>--cmd foo</literal> will synthesize the name <literal>foo.bash</literal> for bash and <literal>_foo</literal> for zsh). The path may also be a fifo or named fd (such as produced by <literal><(cmd)</literal>), in which case the shell and name must be provided. <programlisting> nativeBuildInputs = [ installShellFiles ]; postInstall = '' @@ -2069,6 +2081,11 @@ postInstall = '' installShellCompletion --zsh --name _foobar share/completions.zsh # implicit behavior installShellCompletion share/completions/foobar.{bash,fish,zsh} + # using named fd + installShellCompletion --cmd foobar \ + --bash <($out/bin/foobar --bash-completion) \ + --fish <($out/bin/foobar --fish-completion) \ + --zsh <($out/bin/foobar --zsh-completion) ''; </programlisting> </para> |