Nix Multiple Outputs: `glibc` Exception, File Type Grouping, and Caveats

The `glibc` package is a deliberate single exception to the “binaries first” convention. The `glibc` has `libs` as its first output allowing the libraries provided by `glibc` to be referenced directly (e.g. `${glibc}/lib/ld-linux-x86-64.so.2`). The executables provided by `glibc` can be accessed via its `bin` attribute (e.g. `${lib.getBin stdenv.cc.libc}/bin/ldd`). The reason for why `glibc` deviates from the convention is because referencing a library provided by `glibc` is a very common operation among Nix packages. For instance, third-party executables packaged by Nix are typically patched and relinked with the relevant version of `glibc` libraries from Nix packages (please see the documentation on [patchelf](https://github.com/NixOS/patchelf) for more details). ### File type groups {#multiple-output-file-type-groups} 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 `outputFoo` variable specifying the output name where they should go. If that variable isn’t defined by the derivation writer, it is guessed – a default output name is defined, falling back to other possibilities if the output isn’t defined. #### `$outputDev` {#outputdev} is for development-only files. These include C(++) headers (`include/`), pkg-config (`lib/pkgconfig/`), cmake (`lib/cmake/`) and aclocal files (`share/aclocal/`). They go to `dev` or `out` by default. #### `$outputBin` {#outputbin} is meant for user-facing binaries, typically residing in `bin/`. They go to `bin` or `out` by default. #### `$outputLib` {#outputlib} is meant for libraries, typically residing in `lib/` and `libexec/`. They go to `lib` or `out` by default. #### `$outputDoc` {#outputdoc} is for user documentation, typically residing in `share/doc/`. It goes to `doc` or `out` by default. #### `$outputDevdoc` {#outputdevdoc} is for _developer_ documentation. Currently we count gtk-doc and devhelp books, typically residing in `share/gtk-doc/` and `share/devhelp/`, in there. It goes to `devdoc` or is removed (!) by default. This is because e.g. gtk-doc tends to be rather large and completely unused by nixpkgs users. #### `$outputMan` {#outputman} is for man pages (except for section 3), typically residing in `share/man/man[0-9]/`. They go to `man` or `$outputBin` by default. #### `$outputDevman` {#outputdevman} is for section 3 man pages, typically residing in `share/man/man[0-9]/`. They go to `devman` or `$outputMan` by default. #### `$outputInfo` {#outputinfo} is for info pages, typically residing in `share/info/`. They go to `info` or `$outputBin` by default. ### Common caveats {#sec-multiple-outputs-caveats} - Some configure scripts don’t like some of the parameters passed by default by the framework, e.g. `--docdir=/foo/bar`. You can disable this by setting `setOutputFlags = false;`. - 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.) - Most of split packages contain their core functionality in libraries. These libraries tend to refer to various kind of data that typically gets into `out`, e.g. locale strings, so there is often no advantage in separating the libraries into `lib`, as keeping them in `out` is easier. - Some packages have hidden assumptions on install paths, which complicates splitting.

This text details the `glibc` package's deliberate exception to the "binaries first" convention in Nix, where its `libs` output is primary due to the frequent need to reference its libraries for patching other executables. It then describes how Nix handles "File type groups" through `outputFoo` variables, which direct specific file types (like development files, binaries, libraries, various types of documentation, and man/info pages) to designated outputs (e.g., `dev`, `bin`, `lib`, `doc`). If not explicitly set, default output names are guessed, with `devdoc` notably being removed by default if its output isn't defined. Finally, it outlines common caveats, including configure script conflicts (resolvable by `setOutputFlags = false`), restrictions on circular references between outputs, and challenges in splitting packages when core libraries rely on the main `out` output or packages have hidden install path assumptions.