pkgs/README.md: Update to mention pkgs/by-name
This commit is contained in:
parent
f6467c3574
commit
87f7f1641c
|
@ -7,7 +7,7 @@ See the [CONTRIBUTING.md](../CONTRIBUTING.md) document for more general informat
|
||||||
|
|
||||||
- [`top-level`](./top-level): Entrypoints, package set aggregations
|
- [`top-level`](./top-level): Entrypoints, package set aggregations
|
||||||
- [`impure.nix`](./top-level/impure.nix), [`default.nix`](./top-level/default.nix), [`config.nix`](./top-level/config.nix): Definitions for the evaluation entry point of `import <nixpkgs>`
|
- [`impure.nix`](./top-level/impure.nix), [`default.nix`](./top-level/default.nix), [`config.nix`](./top-level/config.nix): Definitions for the evaluation entry point of `import <nixpkgs>`
|
||||||
- [`stage.nix`](./top-level/stage.nix), [`all-packages.nix`](./top-level/all-packages.nix), [`splice.nix`](./top-level/splice.nix): Definitions for the top-level attribute set made available through `import <nixpkgs> {…}`
|
- [`stage.nix`](./top-level/stage.nix), [`all-packages.nix`](./top-level/all-packages.nix), [`by-name-overlay.nix`](./top-level/by-name-overlay.nix), [`splice.nix`](./top-level/splice.nix): Definitions for the top-level attribute set made available through `import <nixpkgs> {…}`
|
||||||
- `*-packages.nix`, [`linux-kernels.nix`](./top-level/linux-kernels.nix), [`unixtools.nix`](./top-level/unixtools.nix): Aggregations of nested package sets defined in `development`
|
- `*-packages.nix`, [`linux-kernels.nix`](./top-level/linux-kernels.nix), [`unixtools.nix`](./top-level/unixtools.nix): Aggregations of nested package sets defined in `development`
|
||||||
- [`aliases.nix`](./top-level/aliases.nix), [`python-aliases.nix`](./top-level/python-aliases.nix): Aliases for package definitions that have been renamed or removed
|
- [`aliases.nix`](./top-level/aliases.nix), [`python-aliases.nix`](./top-level/python-aliases.nix): Aliases for package definitions that have been renamed or removed
|
||||||
- `release*.nix`, [`make-tarball.nix`](./top-level/make-tarball.nix), [`packages-config.nix`](./top-level/packages-config.nix), [`metrics.nix`](./top-level/metrics.nix), [`nixpkgs-basic-release-checks.nix`](./top-level/nixpkgs-basic-release-checks.nix): Entry-points and utilities used by Hydra for continuous integration
|
- `release*.nix`, [`make-tarball.nix`](./top-level/make-tarball.nix), [`packages-config.nix`](./top-level/packages-config.nix), [`metrics.nix`](./top-level/metrics.nix), [`nixpkgs-basic-release-checks.nix`](./top-level/nixpkgs-basic-release-checks.nix): Entry-points and utilities used by Hydra for continuous integration
|
||||||
|
@ -19,6 +19,7 @@ See the [CONTRIBUTING.md](../CONTRIBUTING.md) document for more general informat
|
||||||
- [`stdenv`](./stdenv): [Standard environment](https://nixos.org/manual/nixpkgs/stable/#part-stdenv)
|
- [`stdenv`](./stdenv): [Standard environment](https://nixos.org/manual/nixpkgs/stable/#part-stdenv)
|
||||||
- [`pkgs-lib`](./pkgs-lib): Definitions for utilities that need packages but are not needed for packages
|
- [`pkgs-lib`](./pkgs-lib): Definitions for utilities that need packages but are not needed for packages
|
||||||
- [`test`](./test): Tests not directly associated with any specific packages
|
- [`test`](./test): Tests not directly associated with any specific packages
|
||||||
|
- [`by-name`](./by-name): Top-level packages organised by name ([docs](./by-name/README.md))
|
||||||
- All other directories loosely categorise top-level packages definitions, see [category hierarchy][categories]
|
- All other directories loosely categorise top-level packages definitions, see [category hierarchy][categories]
|
||||||
|
|
||||||
## Quick Start to Adding a Package
|
## Quick Start to Adding a Package
|
||||||
|
@ -49,20 +50,23 @@ Now that this is out of the way. To add a package to Nixpkgs:
|
||||||
$ cd nixpkgs
|
$ cd nixpkgs
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See the [category hierarchy section][categories] for some hints on the tree organisation. Create a directory for your package, e.g.
|
2. Create a package directory `pkgs/by-name/so/some-package` where `some-package` is the package name and `so` is the lowercased 2-letter prefix of the package name:
|
||||||
|
|
||||||
```ShellSession
|
```ShellSession
|
||||||
$ mkdir pkgs/development/libraries/libfoo
|
$ mkdir -p pkgs/by-name/so/some-package
|
||||||
```
|
```
|
||||||
|
|
||||||
3. In the package directory, create a Nix expression — a piece of code that describes how to build the package. In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store. The expression should usually be called `default.nix`.
|
For more detailed information, see [here](./by-name/README.md).
|
||||||
|
|
||||||
|
3. Create a `package.nix` file in the package directory, containing a Nix expression — a piece of code that describes how to build the package. In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store.
|
||||||
|
|
||||||
```ShellSession
|
```ShellSession
|
||||||
$ emacs pkgs/development/libraries/libfoo/default.nix
|
$ emacs pkgs/by-name/so/some-package/package.nix
|
||||||
$ git add pkgs/development/libraries/libfoo/default.nix
|
$ git add pkgs/by-name/so/some-package/package.nix
|
||||||
```
|
```
|
||||||
|
|
||||||
You can have a look at the existing Nix expressions under `pkgs/` to see how it’s done. Here are some good ones:
|
You can have a look at the existing Nix expressions under `pkgs/` to see how it’s done, some of which are also using the [category hierarchy](#category-hierarchy).
|
||||||
|
Here are some good ones:
|
||||||
|
|
||||||
- GNU Hello: [`pkgs/applications/misc/hello/default.nix`](applications/misc/hello/default.nix). Trivial package, which specifies some `meta` attributes which is good practice.
|
- GNU Hello: [`pkgs/applications/misc/hello/default.nix`](applications/misc/hello/default.nix). Trivial package, which specifies some `meta` attributes which is good practice.
|
||||||
|
|
||||||
|
@ -94,21 +98,13 @@ Now that this is out of the way. To add a package to Nixpkgs:
|
||||||
|
|
||||||
The exact syntax and semantics of the Nix expression language, including the built-in function, are [described in the Nix manual](https://nixos.org/manual/nix/stable/language/).
|
The exact syntax and semantics of the Nix expression language, including the built-in function, are [described in the Nix manual](https://nixos.org/manual/nix/stable/language/).
|
||||||
|
|
||||||
4. Add a call to the function defined in the previous step to [`pkgs/top-level/all-packages.nix`](top-level/all-packages.nix) with some descriptive name for the variable, e.g. `libfoo`.
|
|
||||||
|
|
||||||
```ShellSession
|
|
||||||
$ emacs pkgs/top-level/all-packages.nix
|
|
||||||
```
|
|
||||||
|
|
||||||
The attributes in that file are sorted by category (like “Development / Libraries”) that more-or-less correspond to the directory structure of Nixpkgs, and then by attribute name.
|
|
||||||
|
|
||||||
5. To test whether the package builds, run the following command from the root of the nixpkgs source tree:
|
5. To test whether the package builds, run the following command from the root of the nixpkgs source tree:
|
||||||
|
|
||||||
```ShellSession
|
```ShellSession
|
||||||
$ nix-build -A libfoo
|
$ nix-build -A some-package
|
||||||
```
|
```
|
||||||
|
|
||||||
where `libfoo` should be the variable name defined in the previous step. You may want to add the flag `-K` to keep the temporary build directory in case something fails. If the build succeeds, a symlink `./result` to the package in the Nix store is created.
|
where `some-package` should be the package name. You may want to add the flag `-K` to keep the temporary build directory in case something fails. If the build succeeds, a symlink `./result` to the package in the Nix store is created.
|
||||||
|
|
||||||
6. If you want to install the package into your profile (optional), do
|
6. If you want to install the package into your profile (optional), do
|
||||||
|
|
||||||
|
@ -121,9 +117,19 @@ Now that this is out of the way. To add a package to Nixpkgs:
|
||||||
## Category Hierarchy
|
## Category Hierarchy
|
||||||
[categories]: #category-hierarchy
|
[categories]: #category-hierarchy
|
||||||
|
|
||||||
Each package should be stored in its own directory somewhere in the `pkgs/` tree, i.e. in `pkgs/category/subcategory/.../pkgname`. Below are some rules for picking the right category for a package. Many packages fall under several categories; what matters is the _primary_ purpose of a package. For example, the `libxml2` package builds both a library and some tools; but it’s a library foremost, so it goes under `pkgs/development/libraries`.
|
Most top-level packages are organised in a loosely-categorised directory hierarchy in this directory.
|
||||||
|
See the [overview](#overview) for which directories are part of this.
|
||||||
|
|
||||||
When in doubt, consider refactoring the `pkgs/` tree, e.g. creating new categories or splitting up an existing category.
|
This category hierarchy is partially deprecated and will be migrated away over time.
|
||||||
|
The new `pkgs/by-name` directory ([docs](./by-name/README.md)) should be preferred instead.
|
||||||
|
The category hierarchy may still be used for packages that should be imported using an alternate `callPackage`, such as `python3Packages.callPackage` or `libsForQt5.callPackage`.
|
||||||
|
|
||||||
|
If that is the case for a new package, here are some rules for picking the right category.
|
||||||
|
Many packages fall under several categories; what matters is the _primary_ purpose of a package.
|
||||||
|
For example, the `libxml2` package builds both a library and some tools; but it’s a library foremost, so it goes under `pkgs/development/libraries`.
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Categories</summary>
|
||||||
|
|
||||||
**If it’s used to support _software development_:**
|
**If it’s used to support _software development_:**
|
||||||
|
|
||||||
|
@ -299,6 +305,8 @@ A (typically large) program with a distinct user interface, primarily used inter
|
||||||
|
|
||||||
- `misc`
|
- `misc`
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
# Conventions
|
# Conventions
|
||||||
|
|
||||||
## Package naming
|
## Package naming
|
||||||
|
|
Loading…
Reference in a new issue