doc/stdenv/meta.chapter.md: explain difference between broken and badPlatforms

There has been a longstanding ambiguity between `broken` and
`badPlatforms`, which seem to serve overlapping purposes.

This commit adds to the documentation two examples of constraints
which cannot be expressed by `platforms` and `badPlatforms`.

This commit also mentions `NIXPKGS_ALLOW_BROKEN=1` for overriding
`broken`.
This commit is contained in:
Adam Joseph 2023-04-08 00:33:11 -07:00
parent 0d3d2a2231
commit 19d48a9257

View File

@ -182,7 +182,9 @@ meta.hydraPlatforms = [];
### `broken` {#var-meta-broken}
If set to `true`, the package is marked as "broken", meaning that it wont show up in `nix-env -qa`, and cannot be built or installed. Such packages should be removed from Nixpkgs eventually unless they are fixed.
If set to `true`, the package is marked as "broken", meaning that it wont show up in `nix-env -qa`, and cannot be built or installed unless the environment variable `NIXPKGS_ALLOW_BROKEN` is set. Such unconditionally-broken packages should be removed from Nixpkgs eventually unless they are fixed.
The value of this attribute can depend on a package's arguments, including `stdenv`. This means that `broken` can be used to express constraints such as "does not cross compile" (`meta.broken = !(stdenv.buildPlatform.canExecute stdenv.hostPlatform)`) or "broken if all of a certain set of its dependencies are broken". This makes `broken` strictly more powerful than `meta.badPlatforms`. However `meta.availableOn` currently examines only `meta.platforms` and `meta.badPlatforms`, so `meta.broken` does not influence the default values for optional dependencies.
## Licenses {#sec-meta-license}