commit c906064af1b36ad2e1478c917da300ac12e115ae · pyrox.dev/nixpkgs

+44

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

···

       123
       123
        
           ];

     

       124
       124
        
       }

     

       125
       125
        
       ```

     

       126
       126
       +
       

     

       127
       127
       +
       ## Free-floating definitions {#sec-option-definitions-definitions}

     

       128
       128
       +
       

     

       129
       129
       +
       :::{.note}

     

       130
       130
       +
       The module system internally transforms module syntax into definitions. This always happens internally.

     

       131
       131
       +
       :::

     

       132
       132
       +
       

     

       133
       133
       +
       It is possible to create first class definitions which are not transformed _again_ into definitions by the module system.

     

       134
       134
       +
       

     

       135
       135
       +
       Usually the file location of a definition is implicit and equal to the file it came from.

     

       136
       136
       +
       However, when manipulating definitions, it may be useful for them to be completely self-contained (or "free-floating").

     

       137
       137
       +
       

     

       138
       138
       +
       A free-floating definition is created with `mkDefinition { file = ...; value = ...; }`.

     

       139
       139
       +
       

     

       140
       140
       +
       Preserving the file location creates better error messages, for example when copying definitions from one option to another.

     

       141
       141
       +
       

     

       142
       142
       +
       Other properties like `mkOverride` `mkMerge` `mkAfter` can be used in the `value` attribute but not the other way around.

     

       143
       143
       +
       

     

       144
       144
       +
       The following shows an example configuration that yields an error with the custom position information:

     

       145
       145
       +
       

     

       146
       146
       +
       ```nix

     

       147
       147
       +
       {

     

       148
       148
       +
         _file = "file.nix";

     

       149
       149
       +
         options.foo = mkOption {

     

       150
       150
       +
           default = 13;

     

       151
       151
       +
         };

     

       152
       152
       +
         config.foo = lib.mkDefinition {

     

       153
       153
       +
           file = "custom place";

     

       154
       154
       +
           # mkOptionDefault creates a conflict with the option foo's `default = 1` on purpose

     

       155
       155
       +
           # So we see the error message below contains the conflicting values and different positions

     

       156
       156
       +
           value = lib.mkOptionDefault 42;

     

       157
       157
       +
         };

     

       158
       158
       +
       }

     

       159
       159
       +
       ```

     

       160
       160
       +
       

     

       161
       161
       +
       evaluating the module yields the following error:

     

       162
       162
       +
       

     

       163
       163
       +
       ```

     

       164
       164
       +
       error: Cannot merge definitions of `foo'. Definition values:

     

       165
       165
       +
       - In `file.nix': 13

     

       166
       166
       +
       - In `custom place': 42

     

       167
       167
       +
       ```

     

       168
       168
       +
       

     

       169
       169
       +
       To set the file location for all definitions in a module, you may add the `_file` module syntax attribute, which has a similar effect to using `mkDefinition` on all definitions in the module, without the hassle.

nixos/doc/manual/redirects.json

···

       1664
       1664
        
         "sec-option-definitions-merging": [

     

       1665
       1665
        
           "index.html#sec-option-definitions-merging"

     

       1666
       1666
        
         ],

     

       1667
       1667
       +
         "sec-option-definitions-definitions": [

     

       1668
       1668
       +
           "index.html#sec-option-definitions-definitions"

     

       1669
       1669
       +
         ],

     

       1667
       1670
        
         "sec-assertions": [

     

       1668
       1671
        
           "index.html#sec-assertions"

     

       1669
       1672
        
         ],