staging-next 2026-04-07 (#507470)

/pkgs/development/compilers/flutter @RossComputerGuy

# GNU Tar & Zip

/pkgs/tools/archivers/gnutar        @RossComputerGuy

/pkgs/by-name/gn/gnutar        @RossComputerGuy

/pkgs/by-name/zi/zip           @RossComputerGuy

# SELinux

This chapter describes several special build helpers.

```{=include=} sections

special/buildenv.section.md

special/fakenss.section.md

special/fhs-environments.section.md

special/makesetuphook.section.md

# buildEnv {#sec-buildEnv}

`buildEnv` constructs a derivation containing directories and symbolic links, which resembles the profile layout where a list of derivations or store paths are installed.

Unlike [`symlinkJoin`](#trivial-builder-symlinkJoin), `buildEnv` takes special care of the outputs to link and checks for content collisions across the paths by default.

A common use case for `buildEnv` is constructing environment wrappers, such as an interpreter with modules or a program with extensions.

For example, [`python.withPackage`](#attributes-on-interpreters-packages) is based on `buildEnv`.

## Arguments {#sec-buildEnv-arguments}

`buildEnv` takes [fixed-point arguments (`buildEnv (finalAttrs: { })`)](#chap-build-helpers-finalAttrs) as well as a plain attribute set.

Unless otherwise noted, arguments can be overridden directly using [`<pkg>.overrideAttrs`](#sec-pkg-overrideAttrs).

`buildEnv` enforces [structured attributes (`{ __structuredAttrs = true; }`)](https://nix.dev/manual/nix/2.18/language/advanced-attributes.html#adv-attr-structuredAttrs).

- `name` or `pname` and `version` (required):

    The name of the environment.

- `paths` (required):

    The derivations or store paths to symlink ("install").

    The elements can be any path-like object that string-interpolates to a store path.

    The priority of each path is taken from `<path>.meta.priority` and falls back to `lib.meta.defaultPriority` if not set.

    The argument `paths` is passed as attribute `passthru.paths` to prevent unexpected context pollution.

    `passthru.paths` can be overridden with `<pkg>.overrideAttrs`.

-   `extraOutputsToInstall` (default to `[ ]`):

    Package outputs to include in addition to what `meta.outputsToInstall` specifies.

-   `includeClosures` (default to `false`):

    Whether to include closures of all input paths.

    The list of the closure paths are constructed with `writeClosure`.

    They are installed with lower priority and with build-time exceptions silenced.

-   `extraPrefix` (default to `""`):

    Root the result in directory `"$out${extraPrefix}"`, e.g. `"/share"`.

-   `ignoreCollisions` (default: `false`):

    Don't fail the build upon content collisions.

-   `checkCollisionContents` (default: `true`):

    If there is a collision, check whether the contents and permissions match; and only if not, throw a collision error.

-   `ignoreSingleFileOutputs` (default: `false`):

    Don't fail the build upon single-file outputs.

-   `manifest` (default: `""`):

    The manifest file (if any). A symlink `$out/manifest` will be created to it.

-   `pathsToLink` (default: `[ "/" ]`):

    The paths (relative to each element of `paths`) that we want to symlink (e.g., `["/bin"]`).

    Any file outside the directories in this list won't be symlinked into the produced environment.

-   `postBuild` (default: `""`):

    Shell commands to run after building the symlink tree.

-   `passthru` and `meta` (default: `{ }`):

    `stdenv.mkDerivation`-supported attributes not passing down to `builtins.derivation`.

-   `derivationArgs` (default: `{ }`):

    Additional `stdenv.mkDerivation` arguments, such as `nativeBuildInputs`/`buildInputs` for `postBuild` dependencies and setup hooks.

    `derivationArgs` is not passed down to `stdenv.mkDerivation`.

    Override its attributes directly via `<pkg>.overrideAttrs` and reference directly via `finalAttrs`.

## Build-time exceptions {#sec-buildEnv-exceptions}

There are situations where the specified `paths` might not produce sensible profile layout.

By default, the builder fails early upon detecting these exceptions.

`buildEnv` provides arguments to fine-tune or ignore certain exceptions.

### Path collisions {#ssec-buildEnv-collisions}

Path collisions occur when files provided by two more output paths with the same priority overlap with each other, making the result profile layout potentially affected by the order of elements of `paths`.

This is undesirable in several use cases, such as when `paths` are determined by merging Nix modules.

If the argument `checkCollisionContents` is `true`, the builder checks whether the overlapping paths share the same content and mode, and fails only if not.

The argument `ignoreCollisions` silence the collision checks and allow the files to be overwritten based on the order of chosen output paths.

In addition to silencing this exception with `ignoreCollisions`, one can also adjust the priority of colliding packages and store paths.

Store paths can specify priority in the form

```nix

{

  outPath = <path>;

  meta.priority = <priority>;

}

```

And [`lib.meta.setPrio`](#function-library-lib.meta.setPrio)-related Nixpkgs Library functions also apply to a string-like attribute set (`{ outPath = <path>; }`).

### Single-file outputs {#ssec-buildEnv-singleFileOutputs}

When an output path provides a single file instead of a directory, it inherently cannot merge into the result layout.

All discoverable packages should configure their `meta.outputsToInstall` correctly, so that single-file outputs won't be installed into a profile.

Set `ignoreSingleFileOutputs` to `true` to drop all single-file output paths silently.

This option is useful when the specified paths contain the output paths of package tests.

#### `npmDeps` {#npm-config-hook-deps}

Derivation that contains the NPM package dependencies.

Derivation that contains the npm package dependencies.

Usually built with `fetchNpmDeps`.

This attribute is required or the hook will abort the build.

Tcl dependencies go in `buildInputs`/`nativeBuildInputs`/... like other packages.

For more complex package definitions, such as packages with mixed languages, use `tcl.tclPackageHook`.

Where possible, make sure to enable stubs for maximum compatibility, usually with the `--enable-stubs` configure flag.

Where possible, make sure to enable stubs for maximum compatibility.

If you are using `mkTclDerivation`, `--enable-stubs` will be automatically added to `configureFlags`.

Here is a simple package example to be called with `tclPackages.callPackage`.

  configureFlags = [

    "--with-ssl-dir=${openssl.dev}"

    "--enable-stubs"

  ];

  meta = {

All Tcl applications reside elsewhere.

In case a package is used as both a library and an application (for example `expect`), it should be defined in `tcl-packages.nix`, with an alias elsewhere.

### Using tclRequiresCheck {#using-tclrequirescheck}

Although unit tests are highly preferred to validate correctness of a package, not

all packages have test suites that can be run easily, and some have none at all.

To help ensure the package still works, [`tclRequiresCheck`](#using-tclrequirescheck) can attempt to `package require`

the listed modules.

```nix

{

  tclRequiresCheck = [

    "json"

    "doctools"

  ];

}

```

roughly translates to:

```nix

{

  preDist = ''

    TCLLIBPATH="$out/lib $TCLLIBPATH"

    tclsh <<<'exit [catch {package require json; package require doctools}]'

  '';

}

```

However, this is done in its own phase, and not dependent on whether [`doCheck = true;`](#var-stdenv-doCheck).

This can also be useful in verifying that the package doesn't assume commonly

present packages (e.g. `tcllib`).