2020-04-24 23:36:52 +00:00
# Nixpkgs/NixOS option handling.
{ lib }:
2020-10-27 00:29:36 +00:00
let
inherit ( lib )
all
collect
concatLists
concatMap
2022-06-26 10:26:21 +00:00
concatMapStringsSep
2020-10-27 00:29:36 +00:00
filter
foldl'
head
2021-08-12 14:41:47 +00:00
tail
2020-10-27 00:29:36 +00:00
isAttrs
isBool
isDerivation
isFunction
isInt
isList
isString
length
mapAttrs
optional
optionals
take
;
inherit ( lib . attrsets )
2022-01-25 03:21:06 +00:00
attrByPath
2020-10-27 00:29:36 +00:00
optionalAttrs
;
inherit ( lib . strings )
concatMapStrings
concatStringsSep
;
inherit ( lib . types )
mkOptionType
;
2023-03-04 12:14:45 +00:00
inherit ( lib . lists )
last
;
2023-02-16 17:41:37 +00:00
prioritySuggestion = ''
Use ` lib . mkForce value ` or ` lib . mkDefault value ` to change the priority on any of these definitions .
'' ;
2020-10-27 00:29:36 +00:00
in
2020-04-24 23:36:52 +00:00
rec {
/* R e t u r n s t r u e w h e n t h e g i v e n a r g u m e n t i s a n o p t i o n
Type : isOption : : a -> bool
Example :
isOption 1 // = > false
isOption ( mkOption { } ) // = > true
* /
isOption = lib . isType " o p t i o n " ;
/* C r e a t e s a n O p t i o n a t t r i b u t e s e t . m k O p t i o n a c c e p t s a n a t t r i b u t e s e t w i t h t h e f o l l o w i n g k e y s :
All keys default to ` null ` when not given .
Example :
mkOption { } // = > { _type = " o p t i o n " ; }
2021-10-06 13:57:05 +00:00
mkOption { default = " f o o " ; } // = > { _type = " o p t i o n " ; default = " f o o " ; }
2020-04-24 23:36:52 +00:00
* /
mkOption =
{
# Default value used when no definition is given in the configuration.
default ? null ,
# Textual representation of the default, for the manual.
defaultText ? null ,
# Example value used in the manual.
example ? null ,
# String describing the option.
description ? null ,
# Related packages used in the manual (see `genRelatedPackages` in ../nixos/lib/make-options-doc/default.nix).
relatedPackages ? null ,
# Option type, providing type-checking and value merging.
type ? null ,
# Function that converts the option value to something else.
apply ? null ,
# Whether the option is for NixOS developers only.
internal ? null ,
2021-12-06 16:07:01 +00:00
# Whether the option shows up in the manual. Default: true. Use false to hide the option and any sub-options from submodules. Use "shallow" to hide only sub-options.
2020-04-24 23:36:52 +00:00
visible ? null ,
# Whether the option can be set only once
readOnly ? null ,
} @ attrs :
attrs // { _type = " o p t i o n " ; } ;
/* C r e a t e s a n O p t i o n a t t r i b u t e s e t f o r a b o o l e a n v a l u e o p t i o n i . e a n
option to be toggled on or off :
Example :
mkEnableOption " f o o "
= > { _type = " o p t i o n " ; default = false ; description = " W h e t h e r t o e n a b l e f o o . " ; example = true ; type = { . . . } ; }
* /
mkEnableOption =
# Name for the created option
name : mkOption {
default = false ;
example = true ;
2022-09-09 14:08:57 +00:00
description =
if name ? _type && name . _type == " m d D o c "
then lib . mdDoc " W h e t h e r t o e n a b l e ${ name . text } . "
else " W h e t h e r t o e n a b l e ${ name } . " ;
2020-04-24 23:36:52 +00:00
type = lib . types . bool ;
} ;
2022-01-25 03:21:06 +00:00
/* C r e a t e s a n O p t i o n a t t r i b u t e s e t f o r a n o p t i o n t h a t s p e c i f i e s t h e
package a module should use for some purpose .
2023-03-04 12:14:45 +00:00
The package is specified in the third argument under ` default ` as a list of strings
representing its attribute path in nixpkgs ( or another package set ) .
Because of this , you need to pass nixpkgs itself ( or a subset ) as the first argument .
2022-01-25 03:21:06 +00:00
2023-03-04 12:14:45 +00:00
The second argument may be either a string or a list of strings .
It provides the display name of the package in the description of the generated option
( using only the last element if the passed value is a list )
and serves as the fallback value for the ` default ` argument .
2022-01-25 03:21:06 +00:00
2023-03-04 12:14:45 +00:00
To include extra information in the description , pass ` extraDescription ` to
append arbitrary text to the generated description .
You can also pass an ` example ` value , either a literal string or an attribute path .
2022-01-25 03:21:06 +00:00
2023-03-04 12:14:45 +00:00
The default argument can be omitted if the provided name is
an attribute of pkgs ( if name is a string ) or a
valid attribute path in pkgs ( if name is a list ) .
2022-01-25 03:21:06 +00:00
2023-03-04 12:14:45 +00:00
If you wish to explicitly provide no default , pass ` null ` as ` default ` .
2022-12-28 21:21:41 +00:00
2023-03-08 16:32:21 +00:00
Type : mkPackageOption : : pkgs -> ( string | [ string ] ) -> { default ? : : [ string ] , example ? : : null | string | [ string ] , extraDescription ? : : string } -> option
2022-01-25 03:21:06 +00:00
Example :
mkPackageOption pkgs " h e l l o " { }
= > { _type = " o p t i o n " ; default = « derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv » ; defaultText = { . . . } ; description = " T h e h e l l o p a c k a g e t o u s e . " ; type = { . . . } ; }
Example :
mkPackageOption pkgs " G H C " {
default = [ " g h c " ] ;
2022-11-21 17:40:18 +00:00
example = " p k g s . h a s k e l l . p a c k a g e s . g h c 9 2 . g h c . w i t h P a c k a g e s ( h k g s : [ h k g s . p r i m e s ] ) " ;
2022-01-25 03:21:06 +00:00
}
= > { _type = " o p t i o n " ; default = « derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv » ; defaultText = { . . . } ; description = " T h e G H C p a c k a g e t o u s e . " ; example = { . . . } ; type = { . . . } ; }
2023-03-04 12:14:45 +00:00
Example :
mkPackageOption pkgs [ " p y t h o n 3 9 P a c k a g e s " " p y t o r c h " ] {
extraDescription = " T h i s i s a n e x a m p l e a n d d o e s n ' t a c t u a l l y d o a n y t h i n g . " ;
}
= > { _type = " o p t i o n " ; default = « derivation /nix/store/gvqgsnc4fif9whvwd9ppa568yxbkmvk8-python3.9-pytorch-1.10.2.drv » ; defaultText = { . . . } ; description = " T h e p y t o r c h p a c k a g e t o u s e . T h i s i s a n e x a m p l e a n d d o e s n ' t a c t u a l l y d o a n y t h i n g . " ; type = { . . . } ; }
2022-01-25 03:21:06 +00:00
* /
mkPackageOption =
2023-03-04 12:14:45 +00:00
# Package set (a specific version of nixpkgs or a subset)
2022-01-25 03:21:06 +00:00
pkgs :
# Name for the package, shown in option description
name :
2023-03-04 12:14:45 +00:00
{
2023-03-08 16:32:21 +00:00
# The attribute path where the default package is located (may be omitted)
2023-03-04 12:14:45 +00:00
default ? name ,
2023-03-08 16:32:21 +00:00
# A string or an attribute path to use as an example (may be omitted)
2023-03-04 12:14:45 +00:00
example ? null ,
2023-03-08 16:32:21 +00:00
# Additional text to include in the option description (may be omitted)
2023-03-04 12:14:45 +00:00
extraDescription ? " " ,
} :
let
name' = if isList name then last name else name ;
default' = if isList default then default else [ default ] ;
defaultPath = concatStringsSep " . " default' ;
defaultValue = attrByPath default'
( throw " ${ defaultPath } c a n n o t b e f o u n d i n p k g s " ) pkgs ;
2022-01-25 03:21:06 +00:00
in mkOption {
2023-03-04 12:14:45 +00:00
defaultText = literalExpression ( " p k g s . " + defaultPath ) ;
2022-01-25 03:21:06 +00:00
type = lib . types . package ;
2023-03-04 12:14:45 +00:00
description = " T h e ${ name' } p a c k a g e t o u s e . "
+ ( if extraDescription == " " then " " else " " ) + extraDescription ;
$ { if default != null then " d e f a u l t " else null } = defaultValue ;
2022-01-25 03:21:06 +00:00
$ { if example != null then " e x a m p l e " else null } = literalExpression
( if isList example then " p k g s . " + concatStringsSep " . " example else example ) ;
} ;
2023-01-11 07:51:40 +00:00
/* L i k e m k P a c k a g e O p t i o n , b u t e m i t a n m d D o c d e s c r i p t i o n i n s t e a d o f D o c B o o k . */
2023-03-04 12:14:45 +00:00
mkPackageOptionMD = pkgs : name : extra :
let option = mkPackageOption pkgs name extra ;
2023-01-11 07:51:40 +00:00
in option // { description = lib . mdDoc option . description ; } ;
2020-04-24 23:36:52 +00:00
/* T h i s o p t i o n a c c e p t s a n y t h i n g , b u t i t d o e s n o t p r o d u c e a n y r e s u l t .
This is useful for sharing a module across different module sets
without having to implement similar features as long as the
values of the options are not accessed . * /
mkSinkUndeclaredOptions = attrs : mkOption ( {
internal = true ;
visible = false ;
default = false ;
description = " S i n k f o r o p t i o n d e f i n i t i o n s . " ;
type = mkOptionType {
name = " s i n k " ;
check = x : true ;
merge = loc : defs : false ;
} ;
apply = x : throw " O p t i o n v a l u e i s n o t r e a d a b l e b e c a u s e t h e o p t i o n i s n o t d e c l a r e d . " ;
} // attrs ) ;
mergeDefaultOption = loc : defs :
let list = getValues defs ; in
if length list == 1 then head list
else if all isFunction list then x : mergeDefaultOption loc ( map ( f : f x ) list )
else if all isList list then concatLists list
else if all isAttrs list then foldl' lib . mergeAttrs { } list
else if all isBool list then foldl' lib . or false list
else if all isString list then lib . concatStrings list
else if all isInt list && all ( x : x == head list ) list then head list
2020-09-25 04:45:31 +00:00
else throw " C a n n o t m e r g e d e f i n i t i o n s o f ` ${ showOption loc } ' . D e f i n i t i o n v a l u e s : ${ showDefs defs } " ;
2020-04-24 23:36:52 +00:00
2022-01-26 04:04:25 +00:00
mergeOneOption = mergeUniqueOption { message = " " ; } ;
mergeUniqueOption = { message }: loc : defs :
if length defs == 1
then ( head defs ) . value
else assert length defs > 1 ;
2023-02-16 17:41:37 +00:00
throw " T h e o p t i o n ` ${ showOption loc } ' i s d e f i n e d m u l t i p l e t i m e s w h i l e i t ' s e x p e c t e d t o b e u n i q u e . \n ${ message } \n D e f i n i t i o n v a l u e s : ${ showDefs defs } \n ${ prioritySuggestion } " ;
2020-04-24 23:36:52 +00:00
/* " M e r g e " o p t i o n d e f i n i t i o n s b y c h e c k i n g t h a t t h e y a l l h a v e t h e s a m e v a l u e . */
mergeEqualOption = loc : defs :
if defs == [ ] then abort " T h i s c a s e s h o u l d n e v e r h a p p e n . "
2020-09-25 04:45:31 +00:00
# Return early if we only have one element
# This also makes it work for functions, because the foldl' below would try
# to compare the first element with itself, which is false for functions
2020-10-27 00:29:36 +00:00
else if length defs == 1 then ( head defs ) . value
2020-09-25 04:45:31 +00:00
else ( foldl' ( first : def :
if def . value != first . value then
2023-02-16 17:41:37 +00:00
throw " T h e o p t i o n ` ${ showOption loc } ' h a s c o n f l i c t i n g d e f i n i t i o n v a l u e s : ${ showDefs [ first def ] } \n ${ prioritySuggestion } "
2020-04-24 23:36:52 +00:00
else
2021-08-12 14:41:47 +00:00
first ) ( head defs ) ( tail defs ) ) . value ;
2020-04-24 23:36:52 +00:00
/* E x t r a c t s v a l u e s o f a l l " v a l u e " k e y s o f t h e g i v e n l i s t .
2023-02-02 18:25:31 +00:00
Type : getValues : : [ { value : : a ; } ] -> [ a ]
2020-04-24 23:36:52 +00:00
Example :
getValues [ { value = 1 ; } { value = 2 ; } ] // = > [ 1 2 ]
getValues [ ] // = > [ ]
* /
getValues = map ( x : x . value ) ;
/* E x t r a c t s v a l u e s o f a l l " f i l e " k e y s o f t h e g i v e n l i s t
2023-02-02 18:25:31 +00:00
Type : getFiles : : [ { file : : a ; } ] -> [ a ]
2020-04-24 23:36:52 +00:00
Example :
getFiles [ { file = " f i l e 1 " ; } { file = " f i l e 2 " ; } ] // = > [ " f i l e 1 " " f i l e 2 " ]
getFiles [ ] // = > [ ]
* /
getFiles = map ( x : x . file ) ;
# Generate documentation template from the list of option declaration like
# the set generated with filterOptionSets.
optionAttrSetToDocList = optionAttrSetToDocList' [ ] ;
2022-12-17 10:02:37 +00:00
optionAttrSetToDocList' = _ : options :
2020-04-24 23:36:52 +00:00
concatMap ( opt :
let
2022-12-28 21:21:41 +00:00
name = showOption opt . loc ;
2020-04-24 23:36:52 +00:00
docOption = rec {
loc = opt . loc ;
2022-12-28 21:21:41 +00:00
inherit name ;
2022-01-07 04:07:37 +00:00
description = opt . description or null ;
2020-04-24 23:36:52 +00:00
declarations = filter ( x : x != unknownModule ) opt . declarations ;
internal = opt . internal or false ;
2021-12-06 16:07:01 +00:00
visible =
if ( opt ? visible && opt . visible == " s h a l l o w " )
then true
else opt . visible or true ;
2020-04-24 23:36:52 +00:00
readOnly = opt . readOnly or false ;
2022-03-30 09:31:56 +00:00
type = opt . type . description or " u n s p e c i f i e d " ;
2020-04-24 23:36:52 +00:00
}
2022-12-28 21:21:41 +00:00
// optionalAttrs ( opt ? example ) {
example =
builtins . addErrorContext " w h i l e e v a l u a t i n g t h e e x a m p l e o f o p t i o n ` ${ name } ` " (
renderOptionValue opt . example
) ;
}
// optionalAttrs ( opt ? default ) {
default =
builtins . addErrorContext " w h i l e e v a l u a t i n g t h e d e f a u l t v a l u e o f o p t i o n ` ${ name } ` " (
renderOptionValue ( opt . defaultText or opt . default )
) ;
}
2020-04-24 23:36:52 +00:00
// optionalAttrs ( opt ? relatedPackages && opt . relatedPackages != null ) { inherit ( opt ) relatedPackages ; } ;
subOptions =
let ss = opt . type . getSubOptions opt . loc ;
in if ss != { } then optionAttrSetToDocList' opt . loc ss else [ ] ;
2021-12-06 16:07:01 +00:00
subOptionsVisible = docOption . visible && opt . visible or null != " s h a l l o w " ;
2020-04-24 23:36:52 +00:00
in
2022-07-14 12:49:19 +00:00
# To find infinite recursion in NixOS option docs:
# builtins.trace opt.loc
2021-12-06 16:07:01 +00:00
[ docOption ] ++ optionals subOptionsVisible subOptions ) ( collect isOption options ) ;
2020-04-24 23:36:52 +00:00
/* T h i s f u n c t i o n r e c u r s i v e l y r e m o v e s a l l d e r i v a t i o n a t t r i b u t e s f r o m
` x ` except for the ` name ` attribute .
This is to make the generation of ` options . xml ` much more
efficient : the XML representation of derivations is very large
( on the order of megabytes ) and is not actually used by the
manual generator .
2022-12-17 10:02:37 +00:00
This function was made obsolete by renderOptionValue and is kept for
compatibility with out-of-tree code .
2020-04-24 23:36:52 +00:00
* /
scrubOptionValue = x :
if isDerivation x then
{ type = " d e r i v a t i o n " ; drvPath = x . name ; outPath = x . name ; name = x . name ; }
else if isList x then map scrubOptionValue x
else if isAttrs x then mapAttrs ( n : v : scrubOptionValue v ) ( removeAttrs x [ " _ a r g s " ] )
else x ;
2022-12-17 10:02:37 +00:00
/* E n s u r e s t h a t t h e g i v e n o p t i o n v a l u e ( d e f a u l t o r e x a m p l e ) i s a ` _ t y p e ` d s t r i n g
by rendering Nix values to ` literalExpression ` s .
* /
renderOptionValue = v :
if v ? _type && v ? text then v
else literalExpression ( lib . generators . toPretty {
multiline = true ;
allowPrettyValues = true ;
} v ) ;
2021-10-06 13:57:05 +00:00
/* F o r u s e i n t h e ` d e f a u l t T e x t ` a n d ` e x a m p l e ` o p t i o n a t t r i b u t e s . C a u s e s t h e
given string to be rendered verbatim in the documentation as Nix code . This
is necessary for complex values , e . g . functions , or values that depend on
other values or packages .
2020-04-24 23:36:52 +00:00
* /
2021-10-06 13:57:05 +00:00
literalExpression = text :
if ! isString text then throw " l i t e r a l E x p r e s s i o n e x p e c t s a s t r i n g . "
else { _type = " l i t e r a l E x p r e s s i o n " ; inherit text ; } ;
literalExample = lib . warn " l i t e r a l E x a m p l e i s d e p r e c a t e d , u s e l i t e r a l E x p r e s s i o n i n s t e a d , o r u s e l i t e r a l D o c B o o k f o r a n o n - N i x d e s c r i p t i o n . " literalExpression ;
/* F o r u s e i n t h e ` d e f a u l t T e x t ` a n d ` e x a m p l e ` o p t i o n a t t r i b u t e s . C a u s e s t h e
given DocBook text to be inserted verbatim in the documentation , for when
a ` literalExpression ` would be too hard to read .
* /
literalDocBook = text :
if ! isString text then throw " l i t e r a l D o c B o o k e x p e c t s a s t r i n g . "
2022-09-11 15:47:08 +00:00
else
lib . warnIf ( lib . isInOldestRelease 2211 )
" l i t e r a l D o c B o o k i s d e p r e c a t e d , u s e l i t e r a l M D i n s t e a d "
{ _type = " l i t e r a l D o c B o o k " ; inherit text ; } ;
2020-04-24 23:36:52 +00:00
2022-06-26 10:26:21 +00:00
/* T r a n s i t i o n m a r k e r f o r d o c u m e n t a t i o n t h a t ' s a l r e a d y m i g r a t e d t o m a r k d o w n
syntax .
* /
mdDoc = text :
if ! isString text then throw " m d D o c e x p e c t s a s t r i n g . "
else { _type = " m d D o c " ; inherit text ; } ;
/* F o r u s e i n t h e ` d e f a u l t T e x t ` a n d ` e x a m p l e ` o p t i o n a t t r i b u t e s . C a u s e s t h e
given MD text to be inserted verbatim in the documentation , for when
a ` literalExpression ` would be too hard to read .
* /
literalMD = text :
if ! isString text then throw " l i t e r a l M D e x p e c t s a s t r i n g . "
else { _type = " l i t e r a l M D " ; inherit text ; } ;
2020-04-24 23:36:52 +00:00
# Helper functions.
2023-02-22 10:55:15 +00:00
/* C o n v e r t a n o p t i o n , d e s c r i b e d a s a l i s t o f t h e o p t i o n p a r t s t o a
human-readable version .
2020-04-24 23:36:52 +00:00
Example :
( showOption [ " f o o " " b a r " " b a z " ] ) == " f o o . b a r . b a z "
2023-02-22 10:55:15 +00:00
( showOption [ " f o o " " b a r . b a z " " t u x " ] ) == " f o o . \" b a r . b a z \" . t u x "
( showOption [ " w i n d o w M a n a g e r " " 2 b w m " " e n a b l e " ] ) == " w i n d o w M a n a g e r . \" 2 b w m \" . e n a b l e "
2020-04-24 23:36:52 +00:00
Placeholders will not be quoted as they are not actual values :
( showOption [ " f o o " " * " " b a r " ] ) == " f o o . * . b a r "
( showOption [ " f o o " " < n a m e > " " b a r " ] ) == " f o o . < n a m e > . b a r "
* /
showOption = parts : let
escapeOptionPart = part :
let
2022-10-21 18:38:19 +00:00
# We assume that these are "special values" and not real configuration data.
# If it is real configuration data, it is rendered incorrectly.
specialIdentifiers = [
" < n a m e > " # attrsOf (submodule {})
" * " # listOf (submodule {})
" < f u n c t i o n b o d y > " # functionTo
] ;
in if builtins . elem part specialIdentifiers
2020-04-24 23:36:52 +00:00
then part
2022-10-21 18:38:19 +00:00
else lib . strings . escapeNixIdentifier part ;
2020-04-24 23:36:52 +00:00
in ( concatStringsSep " . " ) ( map escapeOptionPart parts ) ;
showFiles = files : concatStringsSep " a n d " ( map ( f : " ` ${ f } ' " ) files ) ;
2020-09-25 04:45:31 +00:00
showDefs = defs : concatMapStrings ( def :
let
# Pretty print the value for display, if successful
2021-10-01 09:20:50 +00:00
prettyEval = builtins . tryEval
( lib . generators . toPretty { }
( lib . generators . withRecursion { depthLimit = 10 ; throwOnDepthLimit = false ; } def . value ) ) ;
2020-09-25 04:45:31 +00:00
# Split it into its lines
lines = filter ( v : ! isList v ) ( builtins . split " \n " prettyEval . value ) ;
# Only display the first 5 lines, and indent them for better visibility
value = concatStringsSep " \n " ( take 5 lines ++ optional ( length lines > 5 ) " . . . " ) ;
result =
# Don't print any value if evaluating the value strictly fails
if ! prettyEval . success then " "
# Put it on a new line if it consists of multiple
else if length lines > 1 then " : \n " + value
else " : " + value ;
in " \n - I n ` ${ def . file } ' ${ result } "
) defs ;
2022-06-26 10:26:21 +00:00
showOptionWithDefLocs = opt : ''
$ { showOption opt . loc } , with values defined in :
$ { concatMapStringsSep " \n " ( defFile : " - ${ defFile } " ) opt . files }
'' ;
2020-04-24 23:36:52 +00:00
unknownModule = " < u n k n o w n - f i l e > " ;
}