tjh.dev
1/*
2 Library of low-level helper functions for nix expressions.
3
4 Please implement (mostly) exhaustive unit tests
5 for new functions in `./tests.nix`.
6*/
7let
8
9 # A copy of `lib.makeExtensible'` in order to document `extend`.
10 # It has been leading to some trouble, so we have to document it specially.
11 makeExtensible' =
12 rattrs:
13 let
14 self = rattrs self // {
15 /**
16 Patch the Nixpkgs library
17
18 A function that applies patches onto the nixpkgs library.
19 Usage is discouraged for most scenarios.
20
21 :::{.note}
22 The name `extends` is a bit misleading, as it doesn't actually extend the library, but rather patches it.
23 It is merely a consequence of being implemented by `makeExtensible`.
24 :::
25
26 # Inputs
27
28 - An "extension function" `f` that returns attributes that will be updated in the returned Nixpkgs library.
29
30 # Output
31
32 A patched Nixpkgs library.
33
34 :::{.warning}
35 This functionality is intended as an escape hatch for when the provided version of the Nixpkgs library has a flaw.
36
37 If you were to use it to add new functionality, you will run into compatibility and interoperability issues.
38 :::
39 */
40 extend = f: lib.makeExtensible (lib.extends f rattrs);
41 };
42 in
43 self;
44
45 lib = makeExtensible' (
46 self:
47 let
48 callLibs = file: import file { lib = self; };
49 in
50 {
51
52 # often used, or depending on very little
53 trivial = callLibs ./trivial.nix;
54 fixedPoints = callLibs ./fixed-points.nix;
55
56 # datatypes
57 attrsets = callLibs ./attrsets.nix;
58 lists = callLibs ./lists.nix;
59 strings = callLibs ./strings.nix;
60 stringsWithDeps = callLibs ./strings-with-deps.nix;
61
62 # packaging
63 customisation = callLibs ./customisation.nix;
64 derivations = callLibs ./derivations.nix;
65 maintainers = import ../maintainers/maintainer-list.nix;
66 teams = callLibs ../maintainers/team-list.nix;
67 meta = callLibs ./meta.nix;
68 versions = callLibs ./versions.nix;
69
70 # module system
71 modules = callLibs ./modules.nix;
72 options = callLibs ./options.nix;
73 types = callLibs ./types.nix;
74
75 # constants
76 licenses = callLibs ./licenses.nix;
77 sourceTypes = callLibs ./source-types.nix;
78 systems = callLibs ./systems;
79
80 # serialization
81 cli = callLibs ./cli.nix;
82 gvariant = callLibs ./gvariant.nix;
83 generators = callLibs ./generators.nix;
84
85 # misc
86 asserts = callLibs ./asserts.nix;
87 debug = callLibs ./debug.nix;
88 misc = callLibs ./deprecated/misc.nix;
89
90 # domain-specific
91 fetchers = callLibs ./fetchers.nix;
92
93 # Eval-time filesystem handling
94 path = callLibs ./path;
95 filesystem = callLibs ./filesystem.nix;
96 fileset = callLibs ./fileset;
97 sources = callLibs ./sources.nix;
98
99 # back-compat aliases
100 platforms = self.systems.doubles;
101
102 # linux kernel configuration
103 kernel = callLibs ./kernel.nix;
104
105 # network
106 network = callLibs ./network;
107
108 # TODO: For consistency, all builtins should also be available from a sub-library;
109 # these are the only ones that are currently not
110 inherit (builtins)
111 addErrorContext
112 isPath
113 trace
114 typeOf
115 unsafeGetAttrPos
116 ;
117 inherit (self.trivial)
118 id
119 const
120 pipe
121 concat
122 or
123 and
124 xor
125 bitAnd
126 bitOr
127 bitXor
128 bitNot
129 boolToString
130 boolToYesNo
131 mergeAttrs
132 flip
133 defaultTo
134 mapNullable
135 inNixShell
136 isFloat
137 min
138 max
139 importJSON
140 importTOML
141 warn
142 warnIf
143 warnIfNot
144 throwIf
145 throwIfNot
146 checkListOfEnum
147 info
148 showWarnings
149 nixpkgsVersion
150 version
151 isInOldestRelease
152 oldestSupportedReleaseIsAtLeast
153 mod
154 compare
155 splitByAndCompare
156 seq
157 deepSeq
158 lessThan
159 add
160 sub
161 functionArgs
162 setFunctionArgs
163 isFunction
164 toFunction
165 mirrorFunctionArgs
166 fromHexString
167 toHexString
168 toBaseDigits
169 inPureEvalMode
170 isBool
171 isInt
172 pathExists
173 genericClosure
174 readFile
175 ;
176 inherit (self.fixedPoints)
177 fix
178 fix'
179 converge
180 extends
181 composeExtensions
182 composeManyExtensions
183 makeExtensible
184 makeExtensibleWithCustomName
185 toExtension
186 ;
187 inherit (self.attrsets)
188 attrByPath
189 hasAttrByPath
190 setAttrByPath
191 getAttrFromPath
192 attrVals
193 attrNames
194 attrValues
195 getAttrs
196 catAttrs
197 filterAttrs
198 filterAttrsRecursive
199 foldlAttrs
200 foldAttrs
201 collect
202 nameValuePair
203 mapAttrs
204 mapAttrs'
205 mapAttrsToList
206 attrsToList
207 concatMapAttrs
208 mapAttrsRecursive
209 mapAttrsRecursiveCond
210 mapAttrsToListRecursive
211 mapAttrsToListRecursiveCond
212 genAttrs
213 genAttrs'
214 isDerivation
215 toDerivation
216 optionalAttrs
217 zipAttrsWithNames
218 zipAttrsWith
219 zipAttrs
220 recursiveUpdateUntil
221 recursiveUpdate
222 matchAttrs
223 mergeAttrsList
224 overrideExisting
225 showAttrPath
226 getOutput
227 getFirstOutput
228 getBin
229 getLib
230 getStatic
231 getDev
232 getInclude
233 getMan
234 chooseDevOutputs
235 zipWithNames
236 zip
237 recurseIntoAttrs
238 dontRecurseIntoAttrs
239 cartesianProduct
240 cartesianProductOfSets
241 mapCartesianProduct
242 updateManyAttrsByPath
243 listToAttrs
244 hasAttr
245 getAttr
246 isAttrs
247 intersectAttrs
248 removeAttrs
249 ;
250 inherit (self.lists)
251 singleton
252 forEach
253 map
254 foldr
255 fold
256 foldl
257 foldl'
258 imap0
259 imap1
260 filter
261 ifilter0
262 concatMap
263 flatten
264 remove
265 findSingle
266 findFirst
267 any
268 all
269 count
270 optional
271 optionals
272 toList
273 range
274 replicate
275 partition
276 zipListsWith
277 zipLists
278 reverseList
279 listDfs
280 toposort
281 sort
282 sortOn
283 naturalSort
284 compareLists
285 take
286 takeEnd
287 drop
288 dropEnd
289 sublist
290 last
291 init
292 crossLists
293 unique
294 uniqueStrings
295 allUnique
296 intersectLists
297 subtractLists
298 mutuallyExclusive
299 groupBy
300 groupBy'
301 concatLists
302 genList
303 length
304 head
305 tail
306 elem
307 elemAt
308 isList
309 ;
310 inherit (self.strings)
311 concatStrings
312 concatMapStrings
313 concatImapStrings
314 stringLength
315 substring
316 isString
317 replaceString
318 replaceStrings
319 intersperse
320 concatStringsSep
321 concatMapStringsSep
322 concatMapAttrsStringSep
323 concatImapStringsSep
324 concatLines
325 makeSearchPath
326 makeSearchPathOutput
327 makeLibraryPath
328 makeIncludePath
329 makeBinPath
330 optionalString
331 hasInfix
332 hasPrefix
333 hasSuffix
334 join
335 stringToCharacters
336 stringAsChars
337 escape
338 escapeShellArg
339 escapeShellArgs
340 isStorePath
341 isStringLike
342 isValidPosixName
343 toShellVar
344 toShellVars
345 trim
346 trimWith
347 escapeRegex
348 escapeURL
349 escapeXML
350 replaceChars
351 lowerChars
352 upperChars
353 toLower
354 toUpper
355 toCamelCase
356 toSentenceCase
357 addContextFrom
358 splitString
359 splitStringBy
360 removePrefix
361 removeSuffix
362 versionOlder
363 versionAtLeast
364 getName
365 getVersion
366 match
367 split
368 cmakeOptionType
369 cmakeBool
370 cmakeFeature
371 mesonOption
372 mesonBool
373 mesonEnable
374 nameFromURL
375 enableFeature
376 enableFeatureAs
377 withFeature
378 withFeatureAs
379 fixedWidthString
380 fixedWidthNumber
381 toInt
382 toIntBase10
383 readPathsFromFile
384 fileContents
385 ;
386 inherit (self.stringsWithDeps)
387 textClosureList
388 textClosureMap
389 noDepEntry
390 fullDepEntry
391 packEntry
392 stringAfter
393 ;
394 inherit (self.customisation)
395 overrideDerivation
396 makeOverridable
397 callPackageWith
398 callPackagesWith
399 extendDerivation
400 hydraJob
401 makeScope
402 makeScopeWithSplicing
403 makeScopeWithSplicing'
404 extendMkDerivation
405 ;
406 inherit (self.derivations) lazyDerivation optionalDrvAttr warnOnInstantiate;
407 inherit (self.generators) mkLuaInline;
408 inherit (self.meta)
409 addMetaAttrs
410 dontDistribute
411 setName
412 updateName
413 appendToName
414 mapDerivationAttrset
415 setPrio
416 lowPrio
417 lowPrioSet
418 hiPrio
419 hiPrioSet
420 licensesSpdx
421 getLicenseFromSpdxId
422 getLicenseFromSpdxIdOr
423 getExe
424 getExe'
425 ;
426 inherit (self.filesystem)
427 pathType
428 pathIsDirectory
429 pathIsRegularFile
430 packagesFromDirectoryRecursive
431 ;
432 inherit (self.sources)
433 cleanSourceFilter
434 cleanSource
435 sourceByRegex
436 sourceFilesBySuffices
437 commitIdFromGitRepo
438 cleanSourceWith
439 pathHasContext
440 canCleanSource
441 pathIsGitRepo
442 revOrTag
443 repoRevToName
444 ;
445 inherit (self.modules)
446 evalModules
447 setDefaultModuleLocation
448 unifyModuleSyntax
449 applyModuleArgsIfFunction
450 mergeModules
451 mergeModules'
452 mergeOptionDecls
453 mergeDefinitions
454 pushDownProperties
455 dischargeProperties
456 filterOverrides
457 sortProperties
458 fixupOptionType
459 mkIf
460 mkAssert
461 mkDefinition
462 mkMerge
463 mkOverride
464 mkOptionDefault
465 mkDefault
466 mkImageMediaOverride
467 mkForce
468 mkVMOverride
469 mkFixStrictness
470 mkOrder
471 mkBefore
472 mkAfter
473 mkAliasDefinitions
474 mkAliasAndWrapDefinitions
475 fixMergeModules
476 mkRemovedOptionModule
477 mkRenamedOptionModule
478 mkRenamedOptionModuleWith
479 mkMergedOptionModule
480 mkChangedOptionModule
481 mkAliasOptionModule
482 mkDerivedConfig
483 doRename
484 mkAliasOptionModuleMD
485 ;
486 evalOptionValue = lib.warn "External use of `lib.evalOptionValue` is deprecated. If your use case isn't covered by non-deprecated functions, we'd like to know more and perhaps support your use case well, instead of providing access to these low level functions. In this case please open an issue in https://github.com/nixos/nixpkgs/issues/." self.modules.evalOptionValue;
487 inherit (self.options)
488 isOption
489 mkEnableOption
490 mkSinkUndeclaredOptions
491 mergeDefaultOption
492 mergeOneOption
493 mergeEqualOption
494 mergeUniqueOption
495 getValues
496 getFiles
497 optionAttrSetToDocList
498 optionAttrSetToDocList'
499 scrubOptionValue
500 literalExpression
501 literalExample
502 showOption
503 showOptionWithDefLocs
504 showFiles
505 unknownModule
506 mkOption
507 mkPackageOption
508 literalMD
509 ;
510 inherit (self.types)
511 isType
512 setType
513 defaultTypeMerge
514 defaultFunctor
515 isOptionType
516 mkOptionType
517 ;
518 inherit (self.asserts)
519 assertMsg
520 assertOneOf
521 ;
522 inherit (self.debug)
523 traceIf
524 traceVal
525 traceValFn
526 traceSeq
527 traceSeqN
528 traceValSeq
529 traceValSeqFn
530 traceValSeqN
531 traceValSeqNFn
532 traceFnSeqN
533 runTests
534 testAllTrue
535 ;
536 inherit (self.misc)
537 maybeEnv
538 defaultMergeArg
539 defaultMerge
540 foldArgs
541 maybeAttrNullable
542 maybeAttr
543 ifEnable
544 checkFlag
545 getValue
546 checkReqs
547 uniqList
548 uniqListExt
549 condConcat
550 lazyGenericClosure
551 innerModifySumArgs
552 modifySumArgs
553 innerClosePropagation
554 closePropagation
555 mapAttrsFlatten
556 nvs
557 setAttr
558 setAttrMerge
559 mergeAttrsWithFunc
560 mergeAttrsConcatenateValues
561 mergeAttrsNoOverride
562 mergeAttrByFunc
563 mergeAttrsByFuncDefaults
564 mergeAttrsByFuncDefaultsClean
565 mergeAttrBy
566 fakeHash
567 fakeSha256
568 fakeSha512
569 nixType
570 imap
571 ;
572 inherit (self.versions)
573 splitVersion
574 ;
575 inherit (self.network.ipv6)
576 mkEUI64Suffix
577 ;
578 }
579 );
580in
581lib