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