diff options
author | Alyssa Ross <hi@alyssa.is> | 2023-09-12 08:14:37 +0000 |
---|---|---|
committer | Alyssa Ross <hi@alyssa.is> | 2023-09-12 08:14:37 +0000 |
commit | 7d648ac22d941d0c7efdd987315ae0ddf9932ba0 (patch) | |
tree | 51a3e8126722c5a52a9a1e7e40b4eeaf4610db0b /nixpkgs/pkgs/README.md | |
parent | aa4353b499e6950b7333578f936455a628145c31 (diff) | |
parent | db9208ab987cdeeedf78ad9b4cf3c55f5ebd269b (diff) | |
download | nixlib-7d648ac22d941d0c7efdd987315ae0ddf9932ba0.tar nixlib-7d648ac22d941d0c7efdd987315ae0ddf9932ba0.tar.gz nixlib-7d648ac22d941d0c7efdd987315ae0ddf9932ba0.tar.bz2 nixlib-7d648ac22d941d0c7efdd987315ae0ddf9932ba0.tar.lz nixlib-7d648ac22d941d0c7efdd987315ae0ddf9932ba0.tar.xz nixlib-7d648ac22d941d0c7efdd987315ae0ddf9932ba0.tar.zst nixlib-7d648ac22d941d0c7efdd987315ae0ddf9932ba0.zip |
Merge branch 'nixos-unstable' of https://github.com/NixOS/nixpkgs
Diffstat (limited to 'nixpkgs/pkgs/README.md')
-rw-r--r-- | nixpkgs/pkgs/README.md | 55 |
1 files changed, 32 insertions, 23 deletions
diff --git a/nixpkgs/pkgs/README.md b/nixpkgs/pkgs/README.md index 2f486dc7a992..a478ac120f17 100644 --- a/nixpkgs/pkgs/README.md +++ b/nixpkgs/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 @@ -348,14 +356,15 @@ All versions of a package _must_ be included in `all-packages.nix` to make sure * Not start with the package name. * More generally, it should not refer to the package name. * Not end with a period (or any punctuation for that matter). - * Aim to inform while avoiding subjective language. -* `meta.license` must be set and fit the upstream license. + * Provide factual information. + * Avoid subjective language. +* `meta.license` must be set and match the upstream license. * If there is no upstream license, `meta.license` should default to `lib.licenses.unfree`. * If in doubt, try to contact the upstream developers for clarification. * `meta.mainProgram` must be set when appropriate. * `meta.maintainers` should be set. -See the nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes). +See the Nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes). ### Import From Derivation |