about summary refs log tree commit diff
path: root/doc
diff options
context:
space:
mode:
authorAdam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com>2023-04-24 05:09:01 +0000
committerGitHub <noreply@github.com>2023-04-24 05:09:01 +0000
commit8669061b613747787d8bf25e30f87ccb9f619ed8 (patch)
treeb5273b2bb19bffc503e64e2bcc34928091e7204e /doc
parent6598663bd94976847203fdd9dc4d19230137024b (diff)
parent75bbbbd39b15341bb54197db321ea37fc6e25b4b (diff)
Merge pull request #225272 from amjoseph-nixpkgs/pr/docs/broken-vs-badPlatforms
doc/stdenv/meta.chapter.md: explain difference between broken and badPlatforms
Diffstat (limited to 'doc')
-rw-r--r--doc/stdenv/meta.chapter.md21
1 files changed, 20 insertions, 1 deletions
diff --git a/doc/stdenv/meta.chapter.md b/doc/stdenv/meta.chapter.md
index 0b4777efdb8c9..30bfb392c93dd 100644
--- a/doc/stdenv/meta.chapter.md
+++ b/doc/stdenv/meta.chapter.md
@@ -182,7 +182,26 @@ meta.hydraPlatforms = [];
 
 ### `broken` {#var-meta-broken}
 
-If set to `true`, the package is marked as "broken", meaning that it won’t 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 won’t show up in [search.nixos.org](https://search.nixos.org/packages), and cannot be built or installed unless the environment variable [`NIXPKGS_ALLOW_BROKEN`](#opt-allowBroken) 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, for example:
+
+- Does not cross compile
+
+  ```nix
+   meta.broken = !(stdenv.buildPlatform.canExecute stdenv.hostPlatform)
+  ```
+
+- Broken if all of a certain set of its dependencies are broken
+
+  ```nix
+  meta.broken = lib.all (map (p: p.meta.broken) [ glibc musl ])
+  ```
+
+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}