NixOS / nixpkgs option handling
lib.options.isOption
isOption :: a -> bool
Returns true when the given argument is an option
lib.options.isOption usage example
isOption 1 // => false
isOption (mkOption {}) // => true
lib.options.mkOption
Creates an Option attribute set. mkOption accepts an attribute set with the following keys:
All keys default to null
when not given.
pattern - structured function argument
-
default
-
Default value used when no definition is given in the configuration.
-
defaultText
-
Textual representation of the default, for the manual.
-
example
-
Example value used in the manual.
-
description
-
String describing the option.
-
relatedPackages
-
Related packages used in the manual (see
genRelatedPackages
in ../nixos/lib/make-options-doc/default.nix). -
type
-
Option type, providing type-checking and value merging.
-
apply
-
Function that converts the option value to something else.
-
internal
-
Whether the option is for NixOS developers only.
-
visible
-
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.
-
readOnly
-
Whether the option can be set only once
lib.options.mkOption usage example
mkOption { } // => { _type = "option"; }
mkOption { default = "foo"; } // => { _type = "option"; default = "foo"; }
lib.options.mkEnableOption
Creates an Option attribute set for a boolean value option i.e an option to be toggled on or off:
-
name
-
Name for the created option
lib.options.mkEnableOption usage example
mkEnableOption "foo"
=> { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }
lib.options.mkPackageOption
mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> optionThe 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 "The <name> package to use.".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.
Creates an Option attribute set for an option that specifies the package a module should use for some purpose.
-
pkgs
-
Package set (a specific version of nixpkgs)
-
name
-
Name for the package, shown in option description
pattern - structured function argument
-
default
-
Function argument
-
example
-
Function argument
lib.options.mkPackageOption usage example
mkPackageOption pkgs "hello" { }
=> { _type = "option"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = "The hello package to use."; type = { ... }; }
mkPackageOption pkgs "GHC" {
default = [ "ghc" ];
example = "pkgs.haskell.packages.ghc924.ghc.withPackages (hkgs: [ hkgs.primes ])";
}
=> { _type = "option"; default = «derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv»; defaultText = { ... }; description = "The GHC package to use."; example = { ... }; type = { ... }; }
lib.options.mkSinkUndeclaredOptions
This option accepts anything, but it does not produce any result.
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.
-
attrs
-
Function argument
lib.options.mergeEqualOption
"Merge" option definitions by checking that they all have the same value.
-
loc
-
Function argument
-
defs
-
Function argument
lib.options.getValues
getValues :: [ { value :: a } ] -> [a]
Extracts values of all "value" keys of the given list.
lib.options.getValues usage example
getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
getValues [ ] // => [ ]
lib.options.getFiles
getFiles :: [ { file :: a } ] -> [a]
Extracts values of all "file" keys of the given list
lib.options.getFiles usage example
getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
getFiles [ ] // => [ ]
lib.options.scrubOptionValue
This function recursively removes all derivation attributes from
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.
-
x
-
Function argument
lib.options.literalExpression
For use in the defaultText
and example
option attributes. Causes the
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.
-
text
-
Function argument
lib.options.literalDocBook
For use in the defaultText
and example
option attributes. Causes the
given DocBook text to be inserted verbatim in the documentation, for when
a literalExpression
would be too hard to read.
-
text
-
Function argument
lib.options.mdDoc
Transition marker for documentation that's already migrated to markdown syntax.
-
text
-
Function argument
lib.options.literalMD
For use in the defaultText
and example
option attributes. Causes the
given MD text to be inserted verbatim in the documentation, for when
a literalExpression
would be too hard to read.
-
text
-
Function argument
lib.options.showOption
Convert an option, described as a list of the option parts in to a safe, human readable version.
-
parts
-
Function argument
lib.options.showOption usage example
(showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
(showOption ["foo" "bar.baz" "tux"]) == "foo.bar.baz.tux"
Placeholders will not be quoted as they are not actual values:
(showOption ["foo" "*" "bar"]) == "foo.*.bar"
(showOption ["foo" "<name>" "bar"]) == "foo.<name>.bar"
Unlike attributes, options can also start with numbers:
(showOption ["windowManager" "2bwm" "enable"]) == "windowManager.2bwm.enable"