dev/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

* Package naming / versioning guidelines.

Browse Source 
svn path=/nixpkgs/trunk/; revision=18433
This commit is contained in:
Eelco Dolstra 2009-11-18 15:05:09 +00:00
parent 15da008651
commit eb9ff07031
2 changed files with 111 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
doc/coding-conventions.xml
View File

@ -207,6 +207,79 @@ args.stdenv.mkDerivation (args // {
</section>
<section><title>Package naming</title>
<para>In Nixpkgs, there are generally three different names associated with a package:
<itemizedlist>
<listitem><para>The <varname>name</varname> attribute of the
derivation (excluding the version part). This is what most users
see, in particular when using
<command>nix-env</command>.</para></listitem>
<listitem><para>The variable name used for the instantiated package
in <filename>all-packages.nix</filename>, 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 <command>nix-env
-iA</command>.</para></listitem>
<listitem><para>The filename for (the directory containing) the Nix
expression.</para></listitem>
</itemizedlist>
Most of the time, these are the same. For instance, the package
<literal>e2fsprogs</literal> has a <varname>name</varname> attribute
<literal>"e2fsprogs-<replaceable>version</replaceable>"</literal>, is
bound to the variable name <varname>e2fsprogs</varname> in
<filename>all-packages.nix</filename>, and the Nix expression is in
<filename>pkgs/os-specific/linux/e2fsprogs/default.nix</filename>.
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
<literal>module-init-tools</literal> package is bound to the
<literal>module_init_tools</literal> variable in
<filename>all-packages.nix</filename>.</para>
<para>There are a few naming guidelines:
<itemizedlist>
<listitem><para>Generally, try to stick to the upstream package
name.</para></listitem>
<listitem><para>Don’t use uppercase letters in the
<literal>name</literal> attribute — e.g.,
<literal>"mplayer-1.0rc2"</literal> instead of
<literal>"MPlayer-1.0rc2"</literal>.</para></listitem>
<listitem><para>The version part of the <literal>name</literal>
attribute <emphasis>must</emphasis> start with a digit (following a
dash) — e.g., <literal>"hello-0.3-pre-r3910"</literal> instead of
<literal>"hello-svn-r3910"</literal>, as the latter would be seen as
a package named <literal>hello-svn</literal> by
<command>nix-env</command>.</para></listitem>
<listitem><para>Dashes in the package name should be changed to
underscores in variable names, rather than to camel case — e.g.,
<varname>module_init_tools</varname> instead of
<varname>moduleInitTools</varname>.</para></listitem>
<listitem><para>If there are multiple versions of a package, this
should be reflected in the variable names in
<filename>all-packages.nix</filename>,
e.g. <varname>hello_0_3</varname> and <varname>hello_0_4</varname>.
If there is an obvious “default” version, make an attribute like
<literal>hello = hello_0_4;</literal>.</para></listitem>
</itemizedlist>
</para>
</section>
<section xml:id="sec-organisation"><title>File naming and organisation</title>
<para>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
<filename>allPackages.nix</filename> or
<filename>AllPackages.nix</filename>.</para>
<section><title>Hierachy</title>
<para>Each package should be stored in its own directory somewhere in
the <filename>pkgs/</filename> tree, i.e. in
<filename>pkgs/<replaceable>category</replaceable>/<replaceable>subcategory</replaceable>/<replaceable>...</replaceable>/<replaceable>pkgname</replaceable></filename>.
@ -492,4 +567,39 @@ splitting up an existing category.</para>
</section>
<section><title>Versioning</title>
<para>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.</para>
<para>If there is only one version of a package, its Nix expression
should be named <filename>e2fsprogs/default.nix</filename>. If there
are multiple versions, this should be reflected in the filename,
e.g. <filename>e2fsprogs/1.41.8.nix</filename> and
<filename>e2fsprogs/1.41.9.nix</filename>. 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 <filename>firefox/2.0.nix</filename> and
<filename>firefox/3.5.nix</filename>, respectively (which, at a given
point, might contain versions <literal>2.0.0.20</literal> and
<literal>3.5.4</literal>). If a version requires many auxiliary
files, you can use a subdirectory for each version,
e.g. <filename>firefox/2.0/default.nix</filename> and
<filename>firefox/3.5/default.nix</filename>.</para>
<para>All versions of a package <emphasis>must</emphasis> be included
in <filename>all-packages.nix</filename> to make sure that they
evaluate correctly.</para>
</section>
</section>
</chapter>

2
pkgs/top-level/all-packages.nix
View File

@ -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;
};