tjh.dev
1# This file defines the structure of the `config` nixpkgs option.
2
3# This file is tested in `pkgs/test/config.nix`.
4# Run tests with:
5#
6# nix-build -A tests.config
7#
8
9{ config, lib, ... }:
10
11let
12 inherit (lib)
13 literalExpression
14 mapAttrsToList
15 mkOption
16 optionals
17 types
18 ;
19
20 mkMassRebuild =
21 args:
22 mkOption (
23 builtins.removeAttrs args [ "feature" ]
24 // {
25 type = args.type or (types.uniq types.bool);
26 default = args.default or false;
27 description = (
28 (args.description or ''
29 Whether to ${args.feature} while building nixpkgs packages.
30 ''
31 )
32 + ''
33 Changing the default may cause a mass rebuild.
34 ''
35 );
36 }
37 );
38
39 options = {
40
41 # Internal stuff
42
43 # Hide built-in module system options from docs.
44 _module.args = mkOption {
45 internal = true;
46 };
47
48 warnings = mkOption {
49 type = types.listOf types.str;
50 default = [ ];
51 internal = true;
52 };
53
54 # Config options
55
56 warnUndeclaredOptions = mkOption {
57 description = "Whether to warn when `config` contains an unrecognized attribute.";
58 type = types.bool;
59 default = false;
60 };
61
62 fetchedSourceNameDefault = mkOption {
63 type = types.uniq (
64 types.enum [
65 "source"
66 "versioned"
67 "full"
68 ]
69 );
70 default = "source";
71 description = ''
72 This controls the default derivation `name` attribute set by the
73 `fetch*` (`fetchzip`, `fetchFromGitHub`, etc) functions.
74
75 Possible values and the resulting `.name`:
76
77 - `"source"` -> `"source"`
78 - `"versioned"` -> `"''${repo}-''${rev}-source"`
79 - `"full"` -> `"''${repo}-''${rev}-''${fetcherName}-source"`
80
81 The default `"source"` is the best choice for minimal rebuilds, it
82 will ignore any non-hash changes (like branches being renamed, source
83 URLs changing, etc) at the cost of `/nix/store` being easily
84 cache-poisoned (see [NixOS/nix#969](https://github.com/NixOS/nix/issues/969)).
85
86 Setting this to `"versioned"` greatly helps with discoverability of
87 sources in `/nix/store` and makes cache-poisoning of `/nix/store` much
88 harder, at the cost of a single mass-rebuild for all `src`
89 derivations, and an occasional rebuild when a source changes some of
90 its non-hash attributes.
91
92 Setting this to `"full"` is similar to setting it to `"versioned"`,
93 but the use of `fetcherName` in the derivation name will force a
94 rebuild when `src` switches between `fetch*` functions, thus forcing
95 `nix` to check new derivation's `outputHash`, which is useful for
96 debugging.
97
98 Also, `"full"` is useful for easy collection and tracking of
99 statistics of where the packages you use are hosted.
100
101 If you are a developer, you should probably set this to at
102 least`"versioned"`.
103
104 Changing the default will cause a mass rebuild.
105 '';
106 };
107
108 doCheckByDefault = mkMassRebuild {
109 feature = "run `checkPhase` by default";
110 };
111
112 strictDepsByDefault = mkMassRebuild {
113 feature = "set `strictDeps` to true by default";
114 };
115
116 structuredAttrsByDefault = mkMassRebuild {
117 feature = "set `__structuredAttrs` to true by default";
118 };
119
120 enableParallelBuildingByDefault = mkMassRebuild {
121 feature = "set `enableParallelBuilding` to true by default";
122 };
123
124 configurePlatformsByDefault = mkMassRebuild {
125 feature = "set `configurePlatforms` to `[\"build\" \"host\"]` by default";
126 };
127
128 contentAddressedByDefault = mkMassRebuild {
129 feature = "set `__contentAddressed` to true by default";
130 };
131
132 allowAliases = mkOption {
133 type = types.bool;
134 default = true;
135 description = ''
136 Whether to expose old attribute names for compatibility.
137
138 The recommended setting is to enable this, as it
139 improves backward compatibility, easing updates.
140
141 The only reason to disable aliases is for continuous
142 integration purposes. For instance, Nixpkgs should
143 not depend on aliases in its internal code. Projects
144 that aren't Nixpkgs should be cautious of instantly
145 removing all usages of aliases, as migrating too soon
146 can break compatibility with the stable Nixpkgs releases.
147 '';
148 };
149
150 allowUnfree = mkOption {
151 type = types.bool;
152 default = false;
153 # getEnv part is in check-meta.nix
154 defaultText = literalExpression ''false || builtins.getEnv "NIXPKGS_ALLOW_UNFREE" == "1"'';
155 description = ''
156 Whether to allow unfree packages.
157
158 See [Installing unfree packages](https://nixos.org/manual/nixpkgs/stable/#sec-allow-unfree) in the NixOS manual.
159 '';
160 };
161
162 allowBroken = mkOption {
163 type = types.bool;
164 default = false;
165 # getEnv part is in check-meta.nix
166 defaultText = literalExpression ''false || builtins.getEnv "NIXPKGS_ALLOW_BROKEN" == "1"'';
167 description = ''
168 Whether to allow broken packages.
169
170 See [Installing broken packages](https://nixos.org/manual/nixpkgs/stable/#sec-allow-broken) in the NixOS manual.
171 '';
172 };
173
174 allowUnsupportedSystem = mkOption {
175 type = types.bool;
176 default = false;
177 # getEnv part is in check-meta.nix
178 defaultText = literalExpression ''false || builtins.getEnv "NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM" == "1"'';
179 description = ''
180 Whether to allow unsupported packages.
181
182 See [Installing packages on unsupported systems](https://nixos.org/manual/nixpkgs/stable/#sec-allow-unsupported-system) in the NixOS manual.
183 '';
184 };
185
186 allowVariants = mkOption {
187 type = types.bool;
188 default = true;
189 description = ''
190 Whether to expose the nixpkgs variants.
191
192 Variants are instances of the current nixpkgs instance with different stdenvs or other applied options.
193 This allows for using different toolchains, libcs, or global build changes across nixpkgs.
194 Disabling can ensure nixpkgs is only building for the platform which you specified.
195 '';
196 };
197
198 cudaSupport = mkMassRebuild {
199 feature = "build packages with CUDA support by default";
200 };
201
202 replaceBootstrapFiles = mkMassRebuild {
203 type = types.functionTo (types.attrsOf types.package);
204 default = lib.id;
205 defaultText = literalExpression "lib.id";
206 description = ''
207 Use the bootstrap files returned instead of the default bootstrap
208 files.
209 The default bootstrap files are passed as an argument.
210 '';
211 example = literalExpression ''
212 prevFiles:
213 let
214 replacements = {
215 "sha256-YQlr088HPoVWBU2jpPhpIMyOyoEDZYDw1y60SGGbUM0=" = import <nix/fetchurl.nix> {
216 url = "(custom glibc linux x86_64 bootstrap-tools.tar.xz)";
217 hash = "(...)";
218 };
219 "sha256-QrTEnQTBM1Y/qV9odq8irZkQSD9uOMbs2Q5NgCvKCNQ=" = import <nix/fetchurl.nix> {
220 url = "(custom glibc linux x86_64 busybox)";
221 hash = "(...)";
222 executable = true;
223 };
224 };
225 in
226 builtins.mapAttrs (name: prev: replacements.''${prev.outputHash} or prev) prevFiles
227 '';
228 };
229
230 rocmSupport = mkMassRebuild {
231 feature = "build packages with ROCm support by default";
232 };
233
234 showDerivationWarnings = mkOption {
235 type = types.listOf (types.enum [ "maintainerless" ]);
236 default = [ ];
237 description = ''
238 Which warnings to display for potentially dangerous
239 or deprecated values passed into `stdenv.mkDerivation`.
240
241 A list of warnings can be found in
242 [/pkgs/stdenv/generic/check-meta.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/generic/check-meta.nix).
243
244 This is not a stable interface; warnings may be added, changed
245 or removed without prior notice.
246 '';
247 };
248
249 checkMeta = mkOption {
250 type = types.bool;
251 default = false;
252 description = ''
253 Whether to check that the `meta` attribute of derivations are correct during evaluation time.
254 '';
255 };
256
257 rewriteURL = mkOption {
258 type = types.functionTo (types.nullOr types.str);
259 description = ''
260 A hook to rewrite/filter URLs before they are fetched.
261
262 The function is passed the URL as a string, and is expected to return a new URL, or null if the given URL should not be attempted.
263
264 This function is applied _prior_ to resolving mirror:// URLs.
265
266 The intended use is to allow URL rewriting to insert company-internal mirrors, or work around company firewalls and similar network restrictions.
267 '';
268 default = lib.id;
269 defaultText = literalExpression "(url: url)";
270 example = literalExpression ''
271 {
272 # Use Nix like it's 2024! ;-)
273 rewriteURL = url: "https://web.archive.org/web/2024/''${url}";
274 }
275 '';
276 };
277
278 microsoftVisualStudioLicenseAccepted = mkOption {
279 type = types.bool;
280 default = false;
281 # getEnv part is in check-meta.nix
282 defaultText = literalExpression ''false || builtins.getEnv "NIXPKGS_ALLOW_UNFREE" == "1"'';
283 description = ''
284 If the Microsoft Visual Studio license has been accepted.
285
286 Please read https://www.visualstudio.com/license-terms/mt644918/ and enable this config if you accept.
287 '';
288 };
289 };
290
291in
292{
293
294 freeformType =
295 let
296 t = types.lazyAttrsOf types.raw;
297 in
298 t
299 // {
300 merge =
301 loc: defs:
302 let
303 r = t.merge loc defs;
304 in
305 r // { _undeclared = r; };
306 };
307
308 inherit options;
309
310 config = {
311 warnings = optionals config.warnUndeclaredOptions (
312 mapAttrsToList (k: v: "undeclared Nixpkgs option set: config.${k}") config._undeclared or { }
313 );
314 };
315
316}