Commit 8032bb61 authored by Silvan Mosberger's avatar Silvan Mosberger
Browse files

pkgs/by-name: recommendations for multi-versioned packages 

Over the past weeks, we've seen one oversight with the new
enforcement of `pkgs/by-name` for new packages.

This documents the problem and the recommendation for resolving it.
parent c6caed47

pkgs/by-name/README.md

+80 −0
Original line number Diff line number Diff line
@@ -118,3 +118,83 @@ $ ./pkgs/test/nixpkgs-check-by-name/scripts/run-local.sh master 
```



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



## Recommendation for new packages with multiple versions



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

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

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



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

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

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



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



```nix

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

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

```



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

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

```nix

  inherit

    ({

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

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

    })

    foo_1

    foo_2

    ;

```



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

because it establishes a clear connection between related attributes.



### Further possible refactorings



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



```nix

  inherit (import ../tools/foo pkgs)

    foo_1 foo_2;

```



```nix

# pkgs/tools/foo/default.nix

pkgs: {

  foo_1 = callPackage ./1.nix { };

  foo_2 = callPackage ./2.nix { };

}

```



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

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



```nix

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

    foo_1 foo_2;

```



```nix

# pkgs/tools/foo/default.nix

{

  stdenv

}: {

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

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

}

```



### Exposing the package set



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



```nix

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

  # Or using callPackages

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



  inherit (foo-versions) foo_1 foo_2;

```