File Type Groups and Common Caveats in Nixpkgs Split Derivations

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.

Glibc deviates from the 'binaries first' convention by placing libraries in its first output for easier referencing. The Nixpkgs support code categorizes outputs based on file types using `outputFoo` variables, such as `$outputDev` for development files, `$outputBin` for user binaries, `$outputLib` for libraries, `$outputDoc` for user documentation, `$outputDevdoc` for developer documentation (often removed), `$outputMan` for man pages, `$outputDevman` for section 3 man pages, and `$outputInfo` for info pages, with default locations and fallbacks defined. Common caveats include disabling default parameters in configure scripts with `setOutputFlags = false;`, avoiding circular references between outputs, the potential lack of advantage in separating libraries due to data dependencies, and hidden assumptions on install paths.