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 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; }

Noogle detected

• lib.mkPackageOption
• lib.options.mkPackageOption
• lib.options.mkPackageOptionMD

mkPackageOption =
    # Package set (an instantiation of nixpkgs such as pkgs in modules or another package set)
    pkgs:
      # Name for the package, shown in option description
      name:
      {
        # Whether the package can be null, for example to disable installing a package altogether (defaults to false)
        nullable ? false,
        # The attribute path where the default package is located (may be omitted, in which case it is copied from `name`)
        default ? name,
        # A string or an attribute path to use as an example (may be omitted)
        example ? null,
        # Additional text to include in the option description (may be omitted)
        extraDescription ? "",
        # Representation of the package set passed as pkgs (defaults to `"pkgs"`)
        pkgsText ? "pkgs"
      }:
      let
        name' = if isList name then last name else name;
        default' = if isList default then default else [ default ];
        defaultText = concatStringsSep "." default';
        defaultValue = attrByPath default'
          (throw "${defaultText} cannot be found in ${pkgsText}") pkgs;
        defaults = if default != null then {
          default = defaultValue;
          defaultText = literalExpression ("${pkgsText}." + defaultText);
        } else optionalAttrs nullable {
          default = null;
        };
      in mkOption (defaults // {
        description = "The ${name'} package to use."
          + (if extraDescription == "" then "" else " ") + extraDescription;
        type = with lib.types; (if nullable then nullOr else lib.id) package;
      } // optionalAttrs (example != null) {
        example = literalExpression
          (if isList example then "${pkgsText}." + concatStringsSep "." example else example);
      });