commit 9769e9023340c673d9c15f91efa89f0787b9a564 · pyrox.dev/nixpkgs

+48 -15

lib/options.nix

···

       36
        
         inherit (lib.types)

     

       37
        
           mkOptionType

     

       38
        
           ;

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       39
        
         prioritySuggestion = ''

     

       40
        
          Use `lib.mkForce value` or `lib.mkDefault value` to change the priority on any of these definitions.

     

       41
        
         '';

     
···

       107
        
         /* Creates an Option attribute set for an option that specifies the

     

       108
        
            package a module should use for some purpose.

     

       109
        
       

     

       110
       -
            The package is specified as a list of strings representing its attribute path in nixpkgs.

     

       0
        
       
     

       0
        
       
     

       111
        
       

     

       112
       -
            Because of this, you need to pass nixpkgs itself as the first argument.

     

       0
        
       
     

       0
        
       
     

       113
        
       

     

       114
       -
            The second argument is the name of the option, used in the description "The <name> package to use.".

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       115
        
       

     

       116
       -
            You can also pass an example value, either a literal string or a package's attribute path.

     

       0
        
       
     

       0
        
       
     

       117
        
       

     

       118
       -
            You can omit the default path if the name of the option is also attribute path in nixpkgs.

     

       0
        
       
     

       0
        
       
     

       119
        
       

     

       120
       -
            Type: mkPackageOption :: pkgs -> string -> { default :: [string]; example :: null | string | [string]; } -> option

     

       121
        
       

     

       122
        
            Example:

     

       123
        
              mkPackageOption pkgs "hello" { }

     
···

       129
        
                example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";

     

       130
        
              }

     

       131
        
              => { _type = "option"; default = «derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv»; defaultText = { ... }; description = "The GHC package to use."; example = { ... }; type = { ... }; }

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       132
        
         */

     

       133
        
         mkPackageOption =

     

       134
       -
           # Package set (a specific version of nixpkgs)

     

       135
        
           pkgs:

     

       136
        
             # Name for the package, shown in option description

     

       137
        
             name:

     

       138
       -
             { default ? [ name ], example ? null }:

     

       139
       -
             let default' = if !isList default then [ default ] else default;

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       140
        
             in mkOption {

     

       0
        
       
     

       141
        
               type = lib.types.package;

     

       142
       -
               description = "The ${name} package to use.";

     

       143
       -
               default = attrByPath default'

     

       144
       -
                 (throw "${concatStringsSep "." default'} cannot be found in pkgs") pkgs;

     

       145
       -
               defaultText = literalExpression ("pkgs." + concatStringsSep "." default');

     

       146
        
               ${if example != null then "example" else null} = literalExpression

     

       147
        
                 (if isList example then "pkgs." + concatStringsSep "." example else example);

     

       148
        
             };

     

       149
        
       

     

       150
        
         /* Like mkPackageOption, but emit an mdDoc description instead of DocBook. */

     

       151
       -
         mkPackageOptionMD = args: name: extra:

     

       152
       -
           let option = mkPackageOption args name extra;

     

       153
        
           in option // { description = lib.mdDoc option.description; };

     

       154
        
       

     

       155
        
         /* This option accepts anything, but it does not produce any result.

···

       36
        
         inherit (lib.types)

     

       37
        
           mkOptionType

     

       38
        
           ;

     

       39
       +
         inherit (lib.lists)

     

       40
       +
           last

     

       41
       +
           ;

     

       42
        
         prioritySuggestion = ''

     

       43
        
          Use `lib.mkForce value` or `lib.mkDefault value` to change the priority on any of these definitions.

     

       44
        
         '';

     
···

       110
        
         /* Creates an Option attribute set for an option that specifies the

     

       111
        
            package a module should use for some purpose.

     

       112
        
       

     

       113
       +
            Type: mkPackageOption :: pkgs -> (string|[string]) ->

     

       114
       +
             { default? :: [string], example? :: null|string|[string], extraDescription? :: string } ->

     

       115
       +
             option

     

       116
        
       

     

       117
       +
            The package is specified in the third argument under `default` as a list of strings

     

       118
       +
            representing its attribute path in nixpkgs (or another package set).

     

       119
       +
            Because of this, you need to pass nixpkgs itself (or a subset) as the first argument.

     

       120
        
       

     

       121
       +
            The second argument may be either a string or a list of strings.

     

       122
       +
            It provides the display name of the package in the description of the generated option

     

       123
       +
            (using only the last element if the passed value is a list)

     

       124
       +
            and serves as the fallback value for the `default` argument.

     

       125
        
       

     

       126
       +
            To include extra information in the description, pass `extraDescription` to

     

       127
       +
            append arbitrary text to the generated description.

     

       128
       +
            You can also pass an `example` value, either a literal string or an attribute path.

     

       129
        
       

     

       130
       +
            The default argument can be omitted if the provided name is

     

       131
       +
            an attribute of pkgs (if name is a string) or a

     

       132
       +
            valid attribute path in pkgs (if name is a list).

     

       133
        
       

     

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

     

       135
        
       

     

       136
        
            Example:

     

       137
        
              mkPackageOption pkgs "hello" { }

     
···

       143
        
                example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";

     

       144
        
              }

     

       145
        
              => { _type = "option"; default = «derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv»; defaultText = { ... }; description = "The GHC package to use."; example = { ... }; type = { ... }; }

     

       146
       +
       

     

       147
       +
            Example:

     

       148
       +
              mkPackageOption pkgs [ "python39Packages" "pytorch" ] {

     

       149
       +
                extraDescription = "This is an example and doesn't actually do anything.";

     

       150
       +
              }

     

       151
       +
              => { _type = "option"; default = «derivation /nix/store/gvqgsnc4fif9whvwd9ppa568yxbkmvk8-python3.9-pytorch-1.10.2.drv»; defaultText = { ... }; description = "The pytorch package to use. This is an example and doesn't actually do anything."; type = { ... }; }

     

       152
       +
       

     

       153
        
         */

     

       154
        
         mkPackageOption =

     

       155
       +
           # Package set (a specific version of nixpkgs or a subset)

     

       156
        
           pkgs:

     

       157
        
             # Name for the package, shown in option description

     

       158
        
             name:

     

       159
       +
             {

     

       160
       +
               # The attribute path where the default package is located

     

       161
       +
               default ? name,

     

       162
       +
               # A string or an attribute path to use as an example

     

       163
       +
               example ? null,

     

       164
       +
               # Additional text to include in the option description

     

       165
       +
               extraDescription ? "",

     

       166
       +
             }:

     

       167
       +
             let

     

       168
       +
               name' = if isList name then last name else name;

     

       169
       +
               default' = if isList default then default else [ default ];

     

       170
       +
               defaultPath = concatStringsSep "." default';

     

       171
       +
               defaultValue = attrByPath default'

     

       172
       +
                 (throw "${defaultPath} cannot be found in pkgs") pkgs;

     

       173
        
             in mkOption {

     

       174
       +
               defaultText = literalExpression ("pkgs." + defaultPath);

     

       175
        
               type = lib.types.package;

     

       176
       +
               description = "The ${name'} package to use."

     

       177
       +
                 + (if extraDescription == "" then "" else " ") + extraDescription;

     

       178
       +
               ${if default != null then "default" else null} = defaultValue;

     

       0
        
       
     

       179
        
               ${if example != null then "example" else null} = literalExpression

     

       180
        
                 (if isList example then "pkgs." + concatStringsSep "." example else example);

     

       181
        
             };

     

       182
        
       

     

       183
        
         /* Like mkPackageOption, but emit an mdDoc description instead of DocBook. */

     

       184
       +
         mkPackageOptionMD = pkgs: name: extra:

     

       185
       +
           let option = mkPackageOption pkgs name extra;

     

       186
        
           in option // { description = lib.mdDoc option.description; };

     

       187
        
       

     

       188
        
         /* This option accepts anything, but it does not produce any result.

+31 -3

nixos/doc/manual/development/option-declarations.section.md

···

       101
        
       

     

       102
        
       **Note**: You shouldn’t necessarily make package options for all of your modules. You can always overwrite a specific package throughout nixpkgs by using [nixpkgs overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays).

     

       103
        
       

     

       104
       -
       The default 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.

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       105
        
       

     

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

     

       0
        
       
     

       0
        
       
     

       107
        
       

     

       108
       -
       You can omit the default path if the name of the option is also attribute path in nixpkgs.

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       109
        
       

     

       110
        
       During the transition to CommonMark documentation `mkPackageOption` creates an option with a DocBook description attribute, once the transition is completed it will create a CommonMark description instead. `mkPackageOptionMD` always creates an option with a CommonMark description attribute and will be removed some time after the transition is completed.

     

       111
        
       

     
···

       138
        
         defaultText = lib.literalExpression "pkgs.ghc";

     

       139
        
         example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";

     

       140
        
         description = lib.mdDoc "The GHC package to use.";

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       141
        
       }

     

       142
        
       ```

     

       143
        
       :::

···

       101
        
       

     

       102
        
       **Note**: You shouldn’t necessarily make package options for all of your modules. You can always overwrite a specific package throughout nixpkgs by using [nixpkgs overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays).

     

       103
        
       

     

       104
       +
       The package is specified in the third argument under `default` as a list of strings

     

       105
       +
       representing its attribute path in nixpkgs (or another package set).

     

       106
       +
       Because of this, you need to pass nixpkgs itself (or a subset) as the first argument.

     

       107
       +
       

     

       108
       +
       The second argument may be either a string or a list of strings.

     

       109
       +
       It provides the display name of the package in the description of the generated option

     

       110
       +
       (using only the last element if the passed value is a list)

     

       111
       +
       and serves as the fallback value for the `default` argument.

     

       112
        
       

     

       113
       +
       To include extra information in the description, pass `extraDescription` to

     

       114
       +
       append arbitrary text to the generated description.

     

       115
       +
       You can also pass an `example` value, either a literal string or an attribute path.

     

       116
        
       

     

       117
       +
       The default argument can be omitted if the provided name is

     

       118
       +
       an attribute of pkgs (if name is a string) or a

     

       119
       +
       valid attribute path in pkgs (if name is a list).

     

       120
       +
       

     

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

     

       122
        
       

     

       123
        
       During the transition to CommonMark documentation `mkPackageOption` creates an option with a DocBook description attribute, once the transition is completed it will create a CommonMark description instead. `mkPackageOptionMD` always creates an option with a CommonMark description attribute and will be removed some time after the transition is completed.

     

       124
        
       

     
···

       151
        
         defaultText = lib.literalExpression "pkgs.ghc";

     

       152
        
         example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";

     

       153
        
         description = lib.mdDoc "The GHC package to use.";

     

       154
       +
       }

     

       155
       +
       ```

     

       156
       +
       :::

     

       157
       +
       

     

       158
       +
       ::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example}

     

       159
       +
       ```nix

     

       160
       +
       mkPackageOption pkgs [ "python39Packages" "pytorch" ] {

     

       161
       +
         extraDescription = "This is an example and doesn't actually do anything.";

     

       162
       +
       }

     

       163
       +
       # is like

     

       164
       +
       lib.mkOption {

     

       165
       +
         type = lib.types.package;

     

       166
       +
         default = pkgs.python39Packages.pytorch;

     

       167
       +
         defaultText = lib.literalExpression "pkgs.python39Packages.pytorch";

     

       168
       +
         description = "The pytorch package to use. This is an example and doesn't actually do anything.";

     

       169
        
       }

     

       170
        
       ```

     

       171
        
       :::