mkPackageOptionMD
lib.mkPackageOptionMD
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.
Inputs
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
Type
mkPackageOption :: pkgs -> (string|[string]) -> { nullable? :: bool, default? :: string|[string], example? :: null|string|[string], extraDescription? :: string, pkgsText? :: string } -> option
Examples
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; }