From eb9ff07031d8b1845d6d84579d1b19481977e319 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 18 Nov 2009 15:05:09 +0000 Subject: [PATCH] * Package naming / versioning guidelines. svn path=/nixpkgs/trunk/; revision=18433 --- doc/coding-conventions.xml | 110 ++++++++++++++++++++++++++++++++ pkgs/top-level/all-packages.nix | 2 +- 2 files changed, 111 insertions(+), 1 deletion(-) diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index 282fad66280..e55f86ae3d3 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -207,6 +207,79 @@ args.stdenv.mkDerivation (args // { +
Package naming + +In Nixpkgs, there are generally three different names associated with a package: + + + + The name attribute of the + derivation (excluding the version part). This is what most users + see, in particular when using + nix-env. + + The variable name used for the instantiated package + in all-packages.nix, and when passing it as a + dependency to other functions. This is what Nix expression authors + see. It can also be used when installing using nix-env + -iA. + + The filename for (the directory containing) the Nix + expression. + + + +Most of the time, these are the same. For instance, the package +e2fsprogs has a name attribute +"e2fsprogs-version", is +bound to the variable name e2fsprogs in +all-packages.nix, and the Nix expression is in +pkgs/os-specific/linux/e2fsprogs/default.nix. +However, identifiers in the Nix language don’t allow certain +characters (e.g. dashes), so sometimes a different variable name +should be used. For instance, the +module-init-tools package is bound to the +module_init_tools variable in +all-packages.nix. + +There are a few naming guidelines: + + + + Generally, try to stick to the upstream package + name. + + Don’t use uppercase letters in the + name attribute — e.g., + "mplayer-1.0rc2" instead of + "MPlayer-1.0rc2". + + The version part of the name + attribute must start with a digit (following a + dash) — e.g., "hello-0.3-pre-r3910" instead of + "hello-svn-r3910", as the latter would be seen as + a package named hello-svn by + nix-env. + + Dashes in the package name should be changed to + underscores in variable names, rather than to camel case — e.g., + module_init_tools instead of + moduleInitTools. + + If there are multiple versions of a package, this + should be reflected in the variable names in + all-packages.nix, + e.g. hello_0_3 and hello_0_4. + If there is an obvious “default” version, make an attribute like + hello = hello_0_4;. + + + + + +
+ +
File naming and organisation Names of files and directories should be in lowercase, with @@ -215,6 +288,8 @@ dashes between words — not in camel case. For instance, it should be allPackages.nix or AllPackages.nix. +
Hierachy + Each package should be stored in its own directory somewhere in the pkgs/ tree, i.e. in pkgs/category/subcategory/.../pkgname. @@ -492,4 +567,39 @@ splitting up an existing category.
+
Versioning + +Because every version of a package in Nixpkgs creates a +potential maintenance burden, old versions of a package should not be +kept unless there is a good reason to do so. For instance, Nixpkgs +contains several versions of GCC because other packages don’t build +with the latest version of GCC. Other examples are having both the +latest stable and latest pre-release version of a package, or to keep +several major releases of an application that differ significantly in +functionality. + +If there is only one version of a package, its Nix expression +should be named e2fsprogs/default.nix. If there +are multiple versions, this should be reflected in the filename, +e.g. e2fsprogs/1.41.8.nix and +e2fsprogs/1.41.9.nix. The version in the +filename should leave out unnecessary detail. For instance, if we +keep the latest Firefox 2.0.x and 3.5.x versions in Nixpkgs, they +should be named firefox/2.0.nix and +firefox/3.5.nix, respectively (which, at a given +point, might contain versions 2.0.0.20 and +3.5.4). If a version requires many auxiliary +files, you can use a subdirectory for each version, +e.g. firefox/2.0/default.nix and +firefox/3.5/default.nix. + +All versions of a package must be included +in all-packages.nix to make sure that they +evaluate correctly. + +
+ +
+ + diff --git a/pkgs/top-level/all-packages.nix b/pkgs/top-level/all-packages.nix index 2ceb0253fb2..cc089e0e1f5 100644 --- a/pkgs/top-level/all-packages.nix +++ b/pkgs/top-level/all-packages.nix @@ -5232,7 +5232,7 @@ let libuuid = if stdenv.system != "i686-darwin" then utillinuxng else null; - e2fsprogs = import ../os-specific/linux/e2fsprogs/default.nix { + e2fsprogs = import ../os-specific/linux/e2fsprogs { inherit fetchurl stdenv pkgconfig libuuid; };