Nixpkgs Setup Hooks: File Management, Environment Configuration, and Bintools Wrapper

This setup hook adds configure flags that tell packages to install files into any one of the proper outputs listed in `outputs`. This behavior can be turned off by setting `setOutputFlags` to false in the derivation environment. See [](#chap-multiple-output) for more information. ### `move-sbin.sh` {#move-sbin.sh} This setup hook moves any binaries installed in the `sbin/` subdirectory into `bin/`. In addition, a link is provided from `sbin/` to `bin/` for compatibility. ### `move-lib64.sh` {#move-lib64.sh} This setup hook moves any libraries installed in the `lib64/` subdirectory into `lib/`. In addition, a link is provided from `lib64/` to `lib/` for compatibility. ### `move-systemd-user-units.sh` {#move-systemd-user-units.sh} 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. This hook only runs when compiling for Linux. ### `no-broken-symlinks.sh` {#no-broken-symlinks.sh} This setup hook checks for, reports, and (by default) fails builds when "broken" symlinks are found. A symlink is considered "broken" if it's dangling (the target doesn't exist) or reflexive (it refers to itself). This hook can be disabled by setting `dontCheckForBrokenSymlinks`. ::: {.note} The hook only considers symlinks with targets inside the Nix store or $TMPDIR directory (typically /nix/store and /build in the builder environment, the later being where build is executed). ::: ::: {.note} The check for reflexivity is direct and does not account for transitivity, so this hook will not prevent cycles in symlinks. ::: ### `set-source-date-epoch-to-latest.sh` {#set-source-date-epoch-to-latest.sh} This sets `SOURCE_DATE_EPOCH` to the modification time of the most recent file. ### `add-bin-to-path.sh` {#add-bin-to-path.sh} This setup hook checks if the `bin/` directory exists in the `$out` output path and, if so, adds it to the `PATH` environment variable. This ensures that executables located in `$out/bin` are accessible. This hook is particularly useful during testing, as it allows packages to locate their executables without requiring manual modifications to the `PATH`. **Note**: This hook is specifically designed for the `$out/bin` directory only and does not handle and support other paths like `$sourceRoot/bin`. It may not work as intended in cases with multiple outputs or when binaries are located in directories like `sbin/`. These caveats should be considered when using this hook, as they might introduce unexpected behavior in some specific cases. ### `writable-tmpdir-as-home.sh` {#writable-tmpdir-as-home.sh} This setup hook ensures that the directory specified by the `HOME` environment variable is writable. If it is not, the hook assigns `HOME` to a writable directory (in `.home` in `$NIX_BUILD_TOP`). This adjustment is necessary for certain packages that require write access to a home directory. By setting `HOME` to a writable directory, this setup hook prevents failures in packages that attempt to write to the home directory. ### Bintools Wrapper and hook {#bintools-wrapper} The Bintools Wrapper wraps the binary utilities for a bunch of miscellaneous purposes. These are GNU Binutils when targeting Linux, and a mix of cctools and GNU binutils for Darwin. \[The “Bintools” name is supposed to be a compromise between “Binutils” and “cctools” not denoting any specific implementation.\] Specifically, the underlying bintools package, and a C standard library (glibc or Darwin’s libSystem, just for the dynamic loader) are all fed in, and dependency finding, hardening (see below), and purity checks for each are handled by the Bintools Wrapper. Packages typically depend on CC Wrapper, which in turn (at run time) depends on the Bintools Wrapper. The Bintools Wrapper was only just recently split off from CC Wrapper, so the division of labor is still being worked out. For example, it shouldn’t care about the C standard library, but just take a derivation with the dynamic loader (which happens to be the glibc on linux). Dependency finding however is a task both wrappers will continue to need to share, and probably the most important to understand. It is currently accomplished by collecting directories of host-platform dependencies (i.e. `buildInputs` and `nativeBuildInputs`) in environment variables. The Bintools Wrapper’s setup hook causes any `lib` and `lib64` subdirectories to be added to `NIX_LDFLAGS`. Since the CC Wrapper and the Bintools Wrapper use the same strategy, most of the Bintools Wrapper code is sparsely commented and refers to the CC Wrapper. But the CC Wrapper’s code, by contrast, has quite lengthy comments. The Bintools Wrapper merely cites those, rather than repeating them, to avoid falling out of sync.

This chunk outlines several Nixpkgs setup hooks and introduces the Bintools Wrapper. The hooks include `multiple-outputs.sh` for configuring package outputs, `move-sbin.sh`, `move-lib64.sh`, and `move-systemd-user-units.sh` for standardizing file locations (e.g., `sbin` to `bin`, `lib64` to `lib`, systemd user units from `lib` to `share`), often providing compatibility symlinks. `no-broken-symlinks.sh` checks for and can fail builds due to dangling or reflexive symlinks, while `set-source-date-epoch-to-latest.sh` adjusts `SOURCE_DATE_EPOCH`. `add-bin-to-path.sh` ensures `$out/bin` is in the `PATH` for executables (with specific caveats), and `writable-tmpdir-as-home.sh` makes sure the `HOME` directory is writable. Finally, the Bintools Wrapper is described as a utility that wraps binary tools (like GNU Binutils or cctools) to handle dependency finding, hardening, and purity checks, often working with the CC Wrapper and adding `lib`/`lib64` paths to `NIX_LDFLAGS`.