2009-02-09 16:51:03 +00:00
# Nixpkgs/NixOS option handling.
2017-07-29 00:05:35 +00:00
{ lib }:
2009-02-09 16:51:03 +00:00
2020-10-20 11:47:24 +00:00
let
inherit ( lib )
2020-10-22 11:45:25 +00:00
all
collect
concatLists
concatMap
elemAt
filter
foldl'
head
2021-08-10 17:54:32 +00:00
tail
2020-10-22 11:45:25 +00:00
isAttrs
isBool
isDerivation
isFunction
isInt
isList
isString
length
mapAttrs
optional
optionals
take
;
inherit ( lib . attrsets )
2022-01-19 16:09:38 +00:00
attrByPath
2020-10-22 11:45:25 +00:00
optionalAttrs
;
inherit ( lib . strings )
concatMapStrings
concatStringsSep
;
inherit ( lib . types )
mkOptionType
2020-10-20 11:47:24 +00:00
;
in
2009-02-09 16:51:03 +00:00
rec {
2018-10-28 20:31:35 +00:00
/* 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
* /
2013-10-23 16:20:39 +00:00
isOption = lib . isType " o p t i o n " ;
2017-10-30 17:12:49 +00:00
2018-10-28 20:31:35 +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 . 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-03 15:19:19 +00:00
mkOption { default = " f o o " ; } // = > { _type = " o p t i o n " ; default = " f o o " ; }
2018-10-28 20:31:35 +00:00
* /
2013-10-30 14:33:20 +00:00
mkOption =
2018-10-28 20:31:35 +00:00
{
# 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 ,
2019-08-26 00:01:49 +00:00
# Related packages used in the manual (see `genRelatedPackages` in ../nixos/lib/make-options-doc/default.nix).
2018-10-28 20:31:35 +00:00
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-10-28 16:04:49 +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.
2018-10-28 20:31:35 +00:00
visible ? null ,
# Whether the option can be set only once
readOnly ? null ,
2019-03-07 19:28:09 +00:00
# Deprecated, used by types.optionSet.
options ? null
2013-10-30 14:33:20 +00:00
} @ attrs :
attrs // { _type = " o p t i o n " ; } ;
2009-05-27 20:25:17 +00:00
2018-10-28 20:31:35 +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 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 {
2013-07-18 19:13:42 +00:00
default = false ;
example = true ;
2013-10-17 12:29:51 +00:00
description = " W h e t h e r t o e n a b l e ${ name } . " ;
2013-07-18 19:13:42 +00:00
type = lib . types . bool ;
} ;
2022-01-21 09:41:34 +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 .
2022-01-19 16:09:38 +00:00
2022-01-21 09:41:34 +00:00
Type : mkPackageOption : : pkgs -> string -> { default : : [ string ] , example : : null | string | [ string ] } -> option
The package is specified as a list of strings representing its attribute path in nixpkgs .
Because of this , you need to pass nixpkgs itself as the first argument .
The second argument is the name of the option , used in the description " T h e < n a m e > p a c k a g e t o u s e . " .
You can also pass an example value , either a literal string or a package's attribute path .
You can omit the default path if the name of the option is also attribute path in nixpkgs .
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 " ] ;
example = " p k g s . h a s k e l l . p a c k a g e . g h c 9 2 1 . 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 ] ) " ;
}
= > { _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 = { . . . } ; }
2022-01-19 16:09:38 +00:00
* /
2022-01-21 09:41:34 +00:00
mkPackageOption =
# Package set (a specific version of nixpkgs)
pkgs :
# Name for the package, shown in option description
name :
{ default ? [ name ] , example ? null }:
let default' = if ! isList default then [ default ] else default ;
in mkOption {
type = lib . types . package ;
description = " T h e ${ name } p a c k a g e t o u s e . " ;
default = attrByPath default'
( throw " ${ concatStringsSep " . " default' } c a n n o t b e f o u n d i n p k g s " ) pkgs ;
defaultText = literalExpression ( " p k g s . " + concatStringsSep " . " default' ) ;
$ { 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 ) ;
} ;
2022-01-19 16:09:38 +00:00
2018-10-28 20:31:35 +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 . * /
2014-12-21 13:50:46 +00:00
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 ) ;
2013-10-30 13:21:41 +00:00
mergeDefaultOption = loc : defs :
let list = getValues defs ; in
2012-08-13 18:19:31 +00:00
if length list == 1 then head list
2013-11-12 12:48:19 +00:00
else if all isFunction list then x : mergeDefaultOption loc ( map ( f : f x ) list )
2009-05-19 14:54:41 +00:00
else if all isList list then concatLists list
2015-07-23 15:19:21 +00:00
else if all isAttrs list then foldl' lib . mergeAttrs { } list
else if all isBool list then foldl' lib . or false list
2013-11-12 12:48:19 +00:00
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-16 18:05:53 +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 } " ;
2009-02-09 16:51:03 +00:00
2013-10-30 13:21:41 +00:00
mergeOneOption = 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 . "
else if length defs != 1 then
2020-09-16 18:05:53 +00:00
throw " T h e u n i q u 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 . D e f i n i t i o n v a l u e s : ${ showDefs defs } "
2013-10-30 13:21:41 +00:00
else ( head defs ) . value ;
2015-06-15 16:04:27 +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-15 18:30:48 +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-22 11:41:28 +00:00
else if length defs == 1 then ( head defs ) . value
2020-09-16 18:05:53 +00:00
else ( foldl' ( first : def :
if def . value != first . value then
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 ] } "
2015-06-15 16:04:27 +00:00
else
2021-08-10 17:54:32 +00:00
first ) ( head defs ) ( tail defs ) ) . value ;
2015-06-15 16:04:27 +00:00
2018-10-28 20:31:35 +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 .
Type : getValues : : [ { value : : a } ] -> [ a ]
Example :
getValues [ { value = 1 ; } { value = 2 ; } ] // = > [ 1 2 ]
getValues [ ] // = > [ ]
* /
2013-10-30 13:21:41 +00:00
getValues = map ( x : x . value ) ;
2017-10-30 17:12:49 +00:00
2018-10-28 20:31:35 +00:00
/* 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
Type : getFiles : : [ { file : : a } ] -> [ a ]
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 [ ] // = > [ ]
* /
2013-10-30 13:21:41 +00:00
getFiles = map ( x : x . file ) ;
2009-02-09 16:51:03 +00:00
2009-06-11 16:03:38 +00:00
# Generate documentation template from the list of option declaration like
# the set generated with filterOptionSets.
2013-10-28 13:25:58 +00:00
optionAttrSetToDocList = optionAttrSetToDocList' [ ] ;
optionAttrSetToDocList' = prefix : options :
2015-07-23 14:32:52 +00:00
concatMap ( opt :
2013-10-28 13:25:58 +00:00
let
docOption = rec {
2018-02-11 22:04:09 +00:00
loc = opt . loc ;
2013-10-28 13:25:58 +00:00
name = showOption opt . loc ;
2021-11-18 23:26:27 +00:00
description = opt . description or null ;
2013-10-28 13:25:58 +00:00
declarations = filter ( x : x != unknownModule ) opt . declarations ;
internal = opt . internal or false ;
2021-10-28 16:04:49 +00:00
visible =
if ( opt ? visible && opt . visible == " s h a l l o w " )
then true
else opt . visible or true ;
2015-07-30 11:36:57 +00:00
readOnly = opt . readOnly or false ;
2016-09-07 01:03:32 +00:00
type = opt . type . description or null ;
2013-10-28 13:25:58 +00:00
}
2016-04-20 21:57:33 +00:00
// optionalAttrs ( opt ? example ) { example = scrubOptionValue opt . example ; }
// optionalAttrs ( opt ? default ) { default = scrubOptionValue opt . default ; }
// optionalAttrs ( opt ? defaultText ) { default = opt . defaultText ; }
// optionalAttrs ( opt ? relatedPackages && opt . relatedPackages != null ) { inherit ( opt ) relatedPackages ; } ;
2013-10-28 13:25:58 +00:00
subOptions =
let ss = opt . type . getSubOptions opt . loc ;
in if ss != { } then optionAttrSetToDocList' opt . loc ss else [ ] ;
2021-10-28 16:04:49 +00:00
subOptionsVisible = docOption . visible && opt . visible or null != " s h a l l o w " ;
2013-10-28 13:25:58 +00:00
in
2021-10-28 16:04:49 +00:00
[ docOption ] ++ optionals subOptionsVisible subOptions ) ( collect isOption options ) ;
2009-06-11 16:03:38 +00:00
2009-02-09 16:51:03 +00:00
2010-05-12 11:07:49 +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
2018-10-28 20:31:35 +00:00
` 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 .
* /
2013-10-17 12:29:51 +00:00
scrubOptionValue = x :
2013-10-30 15:19:07 +00:00
if isDerivation x then
{ type = " d e r i v a t i o n " ; drvPath = x . name ; outPath = x . name ; name = x . name ; }
2010-05-12 11:07:49 +00:00
else if isList x then map scrubOptionValue x
2010-06-01 14:24:16 +00:00
else if isAttrs x then mapAttrs ( n : v : scrubOptionValue v ) ( removeAttrs x [ " _ a r g s " ] )
2010-05-12 11:07:49 +00:00
else x ;
2011-09-05 10:14:24 +00:00
2021-10-03 15:19:19 +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 .
2018-10-28 20:31:35 +00:00
* /
2021-10-03 15:19:19 +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 . "
else { _type = " l i t e r a l D o c B o o k " ; inherit text ; } ;
2011-09-05 10:14:24 +00:00
2018-10-28 20:31:35 +00:00
# Helper functions.
2011-09-05 10:14:24 +00:00
2018-10-28 20:31:35 +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 i n t o a
safe , human readable version .
2018-03-05 14:54:21 +00:00
2018-10-28 20:31:35 +00:00
Example :
( showOption [ " f o o " " b a r " " b a z " ] ) == " f o o . b a r . b a z "
2020-04-14 18:34:47 +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 "
2020-04-14 02:49:17 +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 "
Unlike attributes , options can also start with numbers :
( 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 "
2018-10-28 20:31:35 +00:00
* /
2020-04-14 18:29:37 +00:00
showOption = parts : let
escapeOptionPart = part :
let
escaped = lib . strings . escapeNixString part ;
in if escaped == " \" ${ part } \" "
then part
else escaped ;
in ( concatStringsSep " . " ) ( map escapeOptionPart parts ) ;
2013-10-28 18:48:30 +00:00
showFiles = files : concatStringsSep " a n d " ( map ( f : " ` ${ f } ' " ) files ) ;
2020-09-16 18:05:07 +00:00
showDefs = defs : concatMapStrings ( def :
let
# Pretty print the value for display, if successful
2021-08-25 22:28:49 +00:00
prettyEval = builtins . tryEval
( lib . generators . toPretty { }
( lib . generators . withRecursion { depthLimit = 10 ; throwOnDepthLimit = false ; } def . value ) ) ;
2020-09-16 18:05:07 +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 ;
2013-10-28 13:25:58 +00:00
unknownModule = " < u n k n o w n - f i l e > " ;
2013-10-27 23:56:22 +00:00
2009-05-24 10:57:41 +00:00
}