blob: fbdcfd7ecb794118827209c337fbb2ae4d8a5663 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
# Name-based package directories
The structure of this directory maps almost directly to top-level package attributes.
This is the recommended way to add new top-level packages to Nixpkgs [when possible](#limitations).
## Example
The top-level package `pkgs.some-package` may be declared by setting up this file structure:
```
pkgs
└── by-name
├── so
┊ ├── some-package
┊ └── package.nix
```
Where `some-package` is the package name and `so` is the lowercased 2-letter prefix of the package name.
The `package.nix` may look like this:
```nix
# A function taking an attribute set as an argument
{
# Get access to top-level attributes for use as dependencies
lib,
stdenv,
libbar,
# Make this derivation configurable using `.override { enableBar = true }`
enableBar ? false,
}:
# The return value must be a derivation
stdenv.mkDerivation {
# ...
buildInputs =
lib.optional enableBar libbar;
}
```
You can also split up the package definition into more files in the same directory if necessary.
Once defined, the package can be built from the Nixpkgs root directory using:
```
nix-build -A some-package
```
See the [general package conventions](../README.md#conventions) for more information on package definitions.
### Changing implicit attribute defaults
The above expression is called using these arguments by default:
```nix
{
lib = pkgs.lib;
stdenv = pkgs.stdenv;
libbar = pkgs.libbar;
}
```
But the package might need `pkgs.libbar_2` instead.
While the function could be changed to take `libbar_2` directly as an argument,
this would change the `.override` interface, breaking code like `.override { libbar = ...; }`.
So instead it is preferable to use the same generic parameter name `libbar`
and override its value in [`pkgs/top-level/all-packages.nix`](../top-level/all-packages.nix):
```nix
libfoo = callPackage ../by-name/so/some-package/package.nix {
libbar = libbar_2;
};
```
## Limitations
There's some limitations as to which packages can be defined using this structure:
- Only packages defined using `pkgs.callPackage`.
This excludes packages defined using `pkgs.python3Packages.callPackage ...`.
Instead use the [category hierarchy](../README.md#category-hierarchy) for such attributes.
- Only top-level packages.
This excludes packages for other package sets like `pkgs.pythonPackages.*`.
Refer to the definition and documentation of the respective package set to figure out how such packages can be declared.
## Validation
CI performs [certain checks](../test/nixpkgs-check-by-name/README.md#validity-checks) on the `pkgs/by-name` structure.
This is done using the [`nixpkgs-check-by-name` tool](../test/nixpkgs-check-by-name).
The version of this tool used is the one that corresponds to the NixOS channel of the PR base branch.
See [here](../../.github/workflows/check-by-name.yml) for details.
The tool can be run locally using
```bash
nix-build -A tests.nixpkgs-check-by-name
result/bin/nixpkgs-check-by-name .
```
|