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"