commit 0e619d7837d53ca5085c61152998a1d30c4eaaa0 · pyrox.dev/nixpkgs

+80
pkgs/by-name/README.md
···

       118
       118
        
       ```

     

       119
       119
        
       

     

       120
       120
        
       See [here](../../.github/workflows/check-by-name.yml) for more info.

     

       121
       121
       +
       

     

       122
       122
       +
       ## Recommendation for new packages with multiple versions

     

       123
       123
       +
       

     

       124
       124
       +
       These checks of the `pkgs/by-name` structure can cause problems in combination:

     

       125
       125
       +
       1. New top-level packages using `callPackage` must be defined via `pkgs/by-name`.

     

       126
       126
       +
       2. Packages in `pkgs/by-name` cannot refer to files outside their own directory.

     

       127
       127
       +
       

     

       128
       128
       +
       This means that outside `pkgs/by-name`, multiple already-present top-level packages can refer to some common file.

     

       129
       129
       +
       If you open a PR to another instance of such a package, CI will fail check 1,

     

       130
       130
       +
       but if you try to move the package to `pkgs/by-name`, it will fail check 2.

     

       131
       131
       +
       

     

       132
       132
       +
       This is often the case for packages with multiple versions, such as

     

       133
       133
       +
       

     

       134
       134
       +
       ```nix

     

       135
       135
       +
         foo_1 = callPackage ../tools/foo/1.nix { };

     

       136
       136
       +
         foo_2 = callPackage ../tools/foo/2.nix { };

     

       137
       137
       +
       ```

     

       138
       138
       +
       

     

       139
       139
       +
       The best way to resolve this is to not use `callPackage` directly, such that check 1 doesn't trigger.

     

       140
       140
       +
       This can be done by using `inherit` on a local package set:

     

       141
       141
       +
       ```nix

     

       142
       142
       +
         inherit

     

       143
       143
       +
           ({

     

       144
       144
       +
             foo_1 = callPackage ../tools/foo/1.nix { };

     

       145
       145
       +
             foo_2 = callPackage ../tools/foo/2.nix { };

     

       146
       146
       +
           })

     

       147
       147
       +
           foo_1

     

       148
       148
       +
           foo_2

     

       149
       149
       +
           ;

     

       150
       150
       +
       ```

     

       151
       151
       +
       

     

       152
       152
       +
       While this may seem pointless, this can in fact help with future package set refactorings,

     

       153
       153
       +
       because it establishes a clear connection between related attributes.

     

       154
       154
       +
       

     

       155
       155
       +
       ### Further possible refactorings

     

       156
       156
       +
       

     

       157
       157
       +
       This is not required, but the above solution also allows refactoring the definitions into a separate file:

     

       158
       158
       +
       

     

       159
       159
       +
       ```nix

     

       160
       160
       +
         inherit (import ../tools/foo pkgs)

     

       161
       161
       +
           foo_1 foo_2;

     

       162
       162
       +
       ```

     

       163
       163
       +
       

     

       164
       164
       +
       ```nix

     

       165
       165
       +
       # pkgs/tools/foo/default.nix

     

       166
       166
       +
       pkgs: {

     

       167
       167
       +
         foo_1 = callPackage ./1.nix { };

     

       168
       168
       +
         foo_2 = callPackage ./2.nix { };

     

       169
       169
       +
       }

     

       170
       170
       +
       ```

     

       171
       171
       +
       

     

       172
       172
       +
       Alternatively using [`callPackages`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.customisation.callPackagesWith)

     

       173
       173
       +
       if `callPackage` isn't used underneath and you want the same `.override` arguments for all attributes:

     

       174
       174
       +
       

     

       175
       175
       +
       ```nix

     

       176
       176
       +
         inherit (callPackages ../tools/foo { })

     

       177
       177
       +
           foo_1 foo_2;

     

       178
       178
       +
       ```

     

       179
       179
       +
       

     

       180
       180
       +
       ```nix

     

       181
       181
       +
       # pkgs/tools/foo/default.nix

     

       182
       182
       +
       {

     

       183
       183
       +
         stdenv

     

       184
       184
       +
       }: {

     

       185
       185
       +
         foo_1 = stdenv.mkDerivation { /* ... */ };

     

       186
       186
       +
         foo_2 = stdenv.mkDerivation { /* ... */ };

     

       187
       187
       +
       }

     

       188
       188
       +
       ```

     

       189
       189
       +
       

     

       190
       190
       +
       ### Exposing the package set

     

       191
       191
       +
       

     

       192
       192
       +
       This is not required, but the above solution also allows exposing the package set as an attribute:

     

       193
       193
       +
       

     

       194
       194
       +
       ```nix

     

       195
       195
       +
         foo-versions = import ../tools/foo pkgs;

     

       196
       196
       +
         # Or using callPackages

     

       197
       197
       +
         # foo-versions = callPackages ../tools/foo { };

     

       198
       198
       +
       

     

       199
       199
       +
         inherit (foo-versions) foo_1 foo_2;

     

       200
       200
       +
       ```