diff options
Diffstat (limited to 'pkgs/README.md')
| -rw-r--r-- | pkgs/README.md | 48 |
1 files changed, 28 insertions, 20 deletions
diff --git a/pkgs/README.md b/pkgs/README.md index f6cb7b25f129e..a478ac120f17c 100644 --- a/pkgs/README.md +++ b/pkgs/README.md @@ -7,7 +7,7 @@ See the [CONTRIBUTING.md](../CONTRIBUTING.md) document for more general informat - [`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>` - - [`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` - [`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 @@ -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) - [`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 +- [`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] ## Quick Start to Adding a Package @@ -49,22 +50,25 @@ Now that this is out of the way. To add a package to 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 - $ 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 - $ emacs pkgs/development/libraries/libfoo/default.nix - $ git add pkgs/development/libraries/libfoo/default.nix + $ emacs pkgs/by-name/so/some-package/package.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/by-name/he/hello/package.nix`](./by-name/he/hello/package.nix). Trivial package, which specifies some `meta` attributes which is good practice. - GNU cpio: [`pkgs/tools/archivers/cpio/default.nix`](tools/archivers/cpio/default.nix). Also a simple package. The generic builder in `stdenv` does everything for you. It has no dependencies beyond `stdenv`. @@ -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/). -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: ```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 @@ -121,9 +117,19 @@ Now that this is out of the way. To add a package to Nixpkgs: ## 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. + +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`. -When in doubt, consider refactoring the `pkgs/` tree, e.g. creating new categories or splitting up an existing category. +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_:** @@ -299,6 +305,8 @@ A (typically large) program with a distinct user interface, primarily used inter - `misc` +</details> + # Conventions ## Package naming |