lib.options: NixOS / nixpkgs option handling

Nixpkgs/NixOS option handling.

`lib.options.isOption`

Type: isOption :: a -> bool

Returns true when the given argument is an option

Example

# `lib.options.isOption` usage example

isOption 1             // => false
isOption (mkOption {}) // => true

Located at lib/options.nix:56 in <nixpkgs>.

`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.

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

Example

`lib.options.mkOption` usage example

mkOption { }  // => { _type = "option"; }
mkOption { default = "foo"; } // => { _type = "option"; default = "foo"; }

Located at lib/options.nix:66 in <nixpkgs>.

`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

Example

`lib.options.mkEnableOption` usage example

mkEnableOption "foo"
=> { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }

Located at lib/options.nix:98 in <nixpkgs>.

`lib.options.mkPackageOption`

Type: mkPackageOption :: pkgs -> (string|[string]) -> { nullable? :: bool, default? :: string|[string], example? :: null|string|[string], extraDescription? :: string, pkgsText? :: string } -> option

Creates an Option attribute set for an option that specifies the package a module should use for some purpose.

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 (usually pkgs in a module; alternatively to nixpkgs itself, another package set) as the first argument.

If you pass another package set you should set the pkgsText option. This option is used to display the expression for the package set. It is "pkgs" by default. If your expression is complex you should parenthesize it, as the pkgsText argument is usually immediately followed by an attribute lookup (.).

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.

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.

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). You can also set default to just a string in which case it is interpreted as an attribute name (a singleton attribute path, if you will).

If you wish to explicitly provide no default, pass null as default.

If you want users to be able to set no package, pass nullable = true. In this mode a default = null will not be interpreted as no default and is interpreted literally.

pkgs

: Package set (an instantiation of nixpkgs such as pkgs in modules or another package set)

name

: Name for the package, shown in option description

structured function argument

: nullable

: Whether the package can be null, for example to disable installing a package altogether (defaults to false)

default

: The attribute path where the default package is located (may be omitted, in which case it is copied from name)

example

: A string or an attribute path to use as an example (may be omitted)

extraDescription

: Additional text to include in the option description (may be omitted)

pkgsText

: Representation of the package set passed as pkgs (defaults to "pkgs")

Example

`lib.options.mkPackageOption` usage example

mkPackageOption pkgs "hello" { }
=> { ...; default = pkgs.hello; defaultText = literalExpression "pkgs.hello"; description = "The hello package to use."; type = package; }


mkPackageOption pkgs "GHC" {
  default = [ "ghc" ];
  example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
}
=> { ...; default = pkgs.ghc; defaultText = literalExpression "pkgs.ghc"; description = "The GHC package to use."; example = literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])"; type = package; }


mkPackageOption pkgs [ "python3Packages" "pytorch" ] {
  extraDescription = "This is an example and doesn't actually do anything.";
}
=> { ...; default = pkgs.python3Packages.pytorch; defaultText = literalExpression "pkgs.python3Packages.pytorch"; description = "The pytorch package to use. This is an example and doesn't actually do anything."; type = package; }


mkPackageOption pkgs "nushell" {
  nullable = true;
}
=> { ...; default = pkgs.nushell; defaultText = literalExpression "pkgs.nushell"; description = "The nushell package to use."; type = nullOr package; }


mkPackageOption pkgs "coreutils" {
  default = null;
}
=> { ...; description = "The coreutils package to use."; type = package; }


mkPackageOption pkgs "dbus" {
  nullable = true;
  default = null;
}
=> { ...; default = null; description = "The dbus package to use."; type = nullOr package; }


mkPackageOption pkgs.javaPackages "OpenJFX" {
  default = "openjfx20";
  pkgsText = "pkgs.javaPackages";
}
=> { ...; default = pkgs.javaPackages.openjfx20; defaultText = literalExpression "pkgs.javaPackages.openjfx20"; description = "The OpenJFX package to use."; type = package; }

Located at lib/options.nix:185 in <nixpkgs>.

`lib.options.mkPackageOptionMD`

Deprecated alias of mkPackageOption, to be removed in 25.05. Previously used to create options with markdown documentation, which is no longer required.

Located at lib/options.nix:226 in <nixpkgs>.

`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

Located at lib/options.nix:233 in <nixpkgs>.

`lib.options.mergeOneOption`

Require a single definition.

WARNING: Does not perform nested checks, as this does not run the merge function!

Located at lib/options.nix:262 in <nixpkgs>.

`lib.options.mergeUniqueOption`

Require a single definition.

NOTE: When the type is not checked completely by check, pass a merge function for further checking (of sub-attributes, etc).

structured function argument

: message

: Function argument

merge

: WARNING: the default merge function assumes that the definition is a valid (option) value. You MUST pass a merge function if the return value needs to be - type checked beyond what .check does (which should be very litte; only on the value head; not attribute values, etc) - if you want attribute values to be checked, or list items - if you want coercedTo-like behavior to work

loc

: Function argument

defs

: Function argument

Located at lib/options.nix:269 in <nixpkgs>.

`lib.options.mergeEqualOption`

"Merge" option definitions by checking that they all have the same value.

loc

: Function argument

defs

: Function argument

Located at lib/options.nix:284 in <nixpkgs>.

`lib.options.getValues`

Type: getValues :: [ { value :: a; } ] -> [a]

Extracts values of all "value" keys of the given list.

Example

# `lib.options.getValues` usage example

getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
getValues [ ]                               // => [ ]

Located at lib/options.nix:304 in <nixpkgs>.

`lib.options.getFiles`

Type: getFiles :: [ { file :: a; } ] -> [a]

Extracts values of all "file" keys of the given list

Example

# `lib.options.getFiles` usage example

getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
getFiles [ ]                                         // => [ ]

Located at lib/options.nix:314 in <nixpkgs>.

`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.

This function was made obsolete by renderOptionValue and is kept for compatibility with out-of-tree code.

x

: Function argument

Located at lib/options.nix:372 in <nixpkgs>.

`lib.options.renderOptionValue`

Ensures that the given option value (default or example) is a _typed string by rendering Nix values to literalExpressions.

v

: Function argument

Located at lib/options.nix:383 in <nixpkgs>.

`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

Located at lib/options.nix:396 in <nixpkgs>.

`lib.options.mdDoc`

Transition marker for documentation that's already migrated to markdown syntax. Has been a no-op for some while and been removed from nixpkgs. Kept here to alert downstream users who may not be aware of the migration's completion that it should be removed from modules.

Located at lib/options.nix:407 in <nixpkgs>.

`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

Located at lib/options.nix:413 in <nixpkgs>.

`lib.options.showOption`

Convert an option, described as a list of the option parts to a human-readable version.

parts

: Function argument

Example

`lib.options.showOption` usage example

(showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
  (showOption ["foo" "bar.baz" "tux"]) == "foo.\"bar.baz\".tux"
  (showOption ["windowManager" "2bwm" "enable"]) == "windowManager.\"2bwm\".enable"

Placeholders will not be quoted as they are not actual values:
  (showOption ["foo" "*" "bar"]) == "foo.*.bar"
  (showOption ["foo" "<name>" "bar"]) == "foo.<name>.bar"

Located at lib/options.nix:431 in <nixpkgs>.

lib.options: NixOS / nixpkgs option handling

lib.options.isOption

lib.options.mkOption

lib.options.mkOption usage example

lib.options.mkEnableOption

lib.options.mkEnableOption usage example

lib.options.mkPackageOption

lib.options.mkPackageOption usage example

lib.options.mkPackageOptionMD

lib.options.mkSinkUndeclaredOptions

lib.options.mergeOneOption

lib.options.mergeUniqueOption

lib.options.mergeEqualOption

lib.options.getValues

lib.options.getFiles

lib.options.scrubOptionValue

lib.options.renderOptionValue

lib.options.literalExpression

lib.options.mdDoc

lib.options.literalMD

lib.options.showOption

lib.options.showOption usage example

`lib.options.isOption`

`lib.options.mkOption`

`lib.options.mkOption` usage example

`lib.options.mkEnableOption`

`lib.options.mkEnableOption` usage example

`lib.options.mkPackageOption`

`lib.options.mkPackageOption` usage example

`lib.options.mkPackageOptionMD`

`lib.options.mkSinkUndeclaredOptions`

`lib.options.mergeOneOption`

`lib.options.mergeUniqueOption`

`lib.options.mergeEqualOption`

`lib.options.getValues`

`lib.options.getFiles`

`lib.options.scrubOptionValue`

`lib.options.renderOptionValue`

`lib.options.literalExpression`

`lib.options.mdDoc`

`lib.options.literalMD`

`lib.options.showOption`

`lib.options.showOption` usage example