diff options
| -rw-r--r-- | doc/guix.texi | 82 |
1 files changed, 81 insertions, 1 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index dfffdbf783..ca2871bc53 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1631,7 +1631,10 @@ needed is to review and apply the patch. @menu -* Software Freedom:: What may go into the distribution. +* Software Freedom:: What may go into the distribution. +* Package Naming:: What's in a name? +* Version Numbers:: When the name is not enough. +* Python Modules:: Taming the snake. @end menu @node Software Freedom @@ -1654,6 +1657,83 @@ reject non-free firmware, recommendations of non-free software, and discuss ways to deal with trademarks and patents. +@node Package Naming +@subsection Package Naming + +A package has actually two names associated to it: +First, there is the name of the @emph{Scheme variable}, the one following +@code{define-public}. By this name, the package can be made known in the +Scheme code, for instance as input to another package. +Second, there is the string in the @code{name} field of a package definition. +This name is used by the package manager. + +Both are usually the same and correspond to the lowercase conversion of the +project name chosen by upstream. For instance, the GNUnet project is packaged +as @code{gnunet}. We do not add @code{lib} prefixes for library packages, +unless these are already part of the official project name. +But see @ref{Python Modules} for special rules concerning modules for +the Python language. + + +@node Version Numbers +@subsection Version Numbers + +We usually package only the latest version of a given free software +project. But sometimes, for instance for incompatible library versions, +two (or more) versions of the same package are needed. These require different +Scheme variable names. We use the name as defined in @ref {Package Naming} +for the most recent version; previous versions use the same name, suffixed +by @code{-} and the smallest prefix of the version number that may +distinguish the two versions. + +The name inside the package definition is the same for all versions of a +package and does not contain any version number. + +For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows: +@example +(define-public gtk+ + (package + (name "gtk+") + (version "3.9.12") + ...)) +(define-public gtk+-2 + (package + (name "gtk+") + (version "2.24.20") + ...)) +@end example +If we also wanted GTK+ 3.8.2, this would be packaged as +@example +(define-public gtk+-3.8 + (package + (name "gtk+") + (version "3.8.2") + ...)) +@end example + + +@node Python Modules +@subsection Python Modules + +We currently package Python 2 and Python 3, under the Scheme variable names +@code{python-2} and @code{python} as explained in @ref{Version Numbers}. +To avoid confusion and naming clashes with other programming languages, it +seems desirable that the name of a package for a Python module contains +the word @code{python}. +Some modules are compatible with only one version of Python, others with both. +If the package Foo compiles only with Python 3, we name it +@code{python-foo}; if it compiles only with Python 2, we name it +@code{python2-foo}. If it is compatible with both versions, we create two +packages with the corresponding names. + +If a project already contains the word @code{python}, we drop this; +for instance, the module python-dateutil is packaged under the names +@code{python-dateutil} and @code{python2-dateutil}. + + + + + @node Bootstrapping @section Bootstrapping |