[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
10/11: doc: Move "Packaging Guidelines" under "Contributing".
From: |
guix-commits |
Subject: |
10/11: doc: Move "Packaging Guidelines" under "Contributing". |
Date: |
Tue, 22 Jan 2019 17:05:12 -0500 (EST) |
civodul pushed a commit to branch master
in repository guix.
commit afe7408e1942d20782deece3ebfbb7621fd8aefe
Author: Ludovic Courtès <address@hidden>
Date: Mon Jan 21 11:31:54 2019 +0100
doc: Move "Packaging Guidelines" under "Contributing".
* doc/guix.texi (Packaging Guidelines): Move to...
* doc/contributing.texi (Packaging Guidelines): ... here. Turn into a
section. Adjust references to "Contributing".
---
doc/contributing.texi | 450 ++++++++++++++++++++++++++++++++++++++++++++++++
doc/guix.texi | 462 --------------------------------------------------
2 files changed, 450 insertions(+), 462 deletions(-)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index f248862..ecc20da 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -23,6 +23,7 @@ choice.
* Building from Git:: The latest and greatest.
* Running Guix Before It Is Installed:: Hacker tricks.
* The Perfect Setup:: The right tools.
+* Packaging Guidelines:: Growing the distribution.
* Coding Style:: Hygiene of the contributor.
* Submitting Patches:: Share your work.
@end menu
@@ -223,6 +224,455 @@ trigger string @code{origin...}, which can be expanded
further. The
@code{...}, which also can be expanded further.
address@hidden Packaging Guidelines
address@hidden Packaging Guidelines
+
address@hidden packages, creating
+The GNU distribution is nascent and may well lack some of your favorite
+packages. This section describes how you can help make the distribution
+grow.
+
+Free software packages are usually distributed in the form of
address@hidden code tarballs}---typically @file{tar.gz} files that contain
+all the source files. Adding a package to the distribution means
+essentially two things: adding a @dfn{recipe} that describes how to
+build the package, including a list of other packages required to build
+it, and adding @dfn{package metadata} along with that recipe, such as a
+description and licensing information.
+
+In Guix all this information is embodied in @dfn{package definitions}.
+Package definitions provide a high-level view of the package. They are
+written using the syntax of the Scheme programming language; in fact,
+for each package we define a variable bound to the package definition,
+and export that variable from a module (@pxref{Package Modules}).
+However, in-depth Scheme knowledge is @emph{not} a prerequisite for
+creating packages. For more information on package definitions,
address@hidden Packages}.
+
+Once a package definition is in place, stored in a file in the Guix
+source tree, it can be tested using the @command{guix build} command
+(@pxref{Invoking guix build}). For example, assuming the new package is
+called @code{gnew}, you may run this command from the Guix build tree
+(@pxref{Running Guix Before It Is Installed}):
+
address@hidden
+./pre-inst-env guix build gnew --keep-failed
address@hidden example
+
+Using @code{--keep-failed} makes it easier to debug build failures since
+it provides access to the failed build tree. Another useful
+command-line option when debugging is @code{--log-file}, to access the
+build log.
+
+If the package is unknown to the @command{guix} command, it may be that
+the source file contains a syntax error, or lacks a @code{define-public}
+clause to export the package variable. To figure it out, you may load
+the module from Guile to get more information about the actual error:
+
address@hidden
+./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
address@hidden example
+
+Once your package builds correctly, please send us a patch
+(@pxref{Submitting Patches}). Well, if you need help, we will be happy to
+help you too. Once the patch is committed in the Guix repository, the
+new package automatically gets built on the supported platforms by
address@hidden://hydra.gnu.org/jobset/gnu/master, our continuous integration
+system}.
+
address@hidden substituter
+Users can obtain the new package definition simply by running
address@hidden pull} (@pxref{Invoking guix pull}). When
address@hidden@value{SUBSTITUTE-SERVER}} is done building the package,
installing the
+package automatically downloads binaries from there
+(@pxref{Substitutes}). The only place where human intervention is
+needed is to review and apply the patch.
+
+
address@hidden
+* Software Freedom:: What may go into the distribution.
+* Package Naming:: What's in a name?
+* Version Numbers:: When the name is not enough.
+* Synopses and Descriptions:: Helping users find the right package.
+* Python Modules:: A touch of British comedy.
+* Perl Modules:: Little pearls.
+* Java Packages:: Coffee break.
+* Fonts:: Fond of fonts.
address@hidden menu
+
address@hidden Software Freedom
address@hidden Software Freedom
+
address@hidden Adapted from http://www.gnu.org/philosophy/philosophy.html.
address@hidden free software
+The GNU operating system has been developed so that users can have
+freedom in their computing. GNU is @dfn{free software}, meaning that
+users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
+essential freedoms}: to run the program, to study and change the program
+in source code form, to redistribute exact copies, and to distribute
+modified versions. Packages found in the GNU distribution provide only
+software that conveys these four freedoms.
+
+In addition, the GNU distribution follow the
address@hidden://www.gnu.org/distros/free-system-distribution-guidelines.html,free
+software distribution guidelines}. Among other things, these guidelines
+reject non-free firmware, recommendations of non-free software, and
+discuss ways to deal with trademarks and patents.
+
+Some otherwise free upstream package sources contain a small and optional
+subset that violates the above guidelines, for instance because this subset
+is itself non-free code. When that happens, the offending items are removed
+with appropriate patches or code snippets in the @code{origin} form of the
+package (@pxref{Defining Packages}). This way, @code{guix
+build --source} returns the ``freed'' source rather than the unmodified
+upstream source.
+
+
address@hidden Package Naming
address@hidden Package Naming
+
address@hidden package name
+A package has actually two names associated with it:
+First, there is the name of the @emph{Scheme variable}, the one following
address@hidden 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 package management commands such as
address@hidden package} and @command{guix build}.
+
+Both are usually the same and correspond to the lowercase conversion of
+the project name chosen upstream, with underscores replaced with
+hyphens. For instance, GNUnet is available as @code{gnunet}, and
+SDL_net as @code{sdl-net}.
+
+We do not add @code{lib} prefixes for library packages, unless these are
+already part of the official project name. But @pxref{Python
+Modules} and @ref{Perl Modules} for special rules concerning modules for
+the Python and Perl languages.
+
+Font package names are handled differently, @pxref{Fonts}.
+
+
address@hidden Version Numbers
address@hidden Version Numbers
+
address@hidden package version
+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:
+
address@hidden
+(define-public gtk+
+ (package
+ (name "gtk+")
+ (version "3.9.12")
+ ...))
+(define-public gtk+-2
+ (package
+ (name "gtk+")
+ (version "2.24.20")
+ ...))
address@hidden example
+If we also wanted GTK+ 3.8.2, this would be packaged as
address@hidden
+(define-public gtk+-3.8
+ (package
+ (name "gtk+")
+ (version "3.8.2")
+ ...))
address@hidden example
+
address@hidden See
<https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
address@hidden for a discussion of what follows.
address@hidden version number, for VCS snapshots
+Occasionally, we package snapshots of upstream's version control system
+(VCS) instead of formal releases. This should remain exceptional,
+because it is up to upstream developers to clarify what the stable
+release is. Yet, it is sometimes necessary. So, what should we put in
+the @code{version} field?
+
+Clearly, we need to make the commit identifier of the VCS snapshot
+visible in the version string, but we also need to make sure that the
+version string is monotonically increasing so that @command{guix package
+--upgrade} can determine which version is newer. Since commit
+identifiers, notably with Git, are not monotonically increasing, we add
+a revision number that we increase each time we upgrade to a newer
+snapshot. The resulting version string looks like this:
+
address@hidden
+2.0.11-3.cabba9e
+ ^ ^ ^
+ | | `-- upstream commit ID
+ | |
+ | `--- Guix package revision
+ |
+latest upstream version
address@hidden example
+
+It is a good idea to strip commit identifiers in the @code{version}
+field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
+aesthetics have a role to play here) as well as problems related to OS
+limits such as the maximum shebang length (127 bytes for the Linux
+kernel.) It is best to use the full commit identifiers in
address@hidden, though, to avoid ambiguities. A typical package
+definition may look like this:
+
address@hidden
+(define my-package
+ (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
+ (revision "1")) ;Guix package revision
+ (package
+ (version (git-version "0.9" revision commit))
+ (source (origin
+ (method git-fetch)
+ (uri (git-reference
+ (url "git://example.org/my-package.git")
+ (commit commit)))
+ (sha256 (base32 "address@hidden"))
+ (file-name (git-file-name name version))))
+ ;; @dots{}
+ )))
address@hidden example
+
address@hidden Synopses and Descriptions
address@hidden Synopses and Descriptions
+
address@hidden package description
address@hidden package synopsis
+As we have seen before, each package in address@hidden includes a
+synopsis and a description (@pxref{Defining Packages}). Synopses and
+descriptions are important: They are what @command{guix package
+--search} searches, and a crucial piece of information to help users
+determine whether a given package suits their needs. Consequently,
+packagers should pay attention to what goes into them.
+
+Synopses must start with a capital letter and must not end with a
+period. They must not start with ``a'' or ``the'', which usually does
+not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
+tool that frobs files''. The synopsis should say what the package
+is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
+used for---e.g., the synopsis for address@hidden is ``Print lines
+matching a pattern''.
+
+Keep in mind that the synopsis must be meaningful for a very wide
+audience. For example, ``Manipulate alignments in the SAM format''
+might make sense for a seasoned bioinformatics researcher, but might be
+fairly unhelpful or even misleading to a non-specialized audience. It
+is a good idea to come up with a synopsis that gives an idea of the
+application domain of the package. In this example, this might give
+something like ``Manipulate nucleotide sequence alignments'', which
+hopefully gives the user a better idea of whether this is what they are
+looking for.
+
+Descriptions should take between five and ten lines. Use full
+sentences, and avoid using acronyms without first introducing them.
+Please avoid marketing phrases such as ``world-leading'',
+``industrial-strength'', and ``next-generation'', and avoid superlatives
+like ``the most advanced''---they are not helpful to users looking for a
+package and may even sound suspicious. Instead, try to be factual,
+mentioning use cases and features.
+
address@hidden Texinfo markup, in package descriptions
+Descriptions can include Texinfo markup, which is useful to introduce
+ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
+hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
+should be careful when using some characters for example @samp{@@} and
+curly braces which are the basic special characters in Texinfo
+(@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
+such as @command{guix package --show} take care of rendering it
+appropriately.
+
+Synopses and descriptions are translated by volunteers
address@hidden://translationproject.org/domain/guix-packages.html, at the
+Translation Project} so that as many users as possible can read them in
+their native language. User interfaces search them and display them in
+the language specified by the current locale.
+
+To allow @command{xgettext} to extract them as translatable strings,
+synopses and descriptions @emph{must be literal strings}. This means
+that you cannot use @code{string-append} or @code{format} to construct
+these strings:
+
address@hidden
+(package
+ ;; @dots{}
+ (synopsis "This is translatable")
+ (description (string-append "This is " "*not*" " translatable.")))
address@hidden lisp
+
+Translation is a lot of work so, as a packager, please pay even more
+attention to your synopses and descriptions as every change may entail
+additional work for translators. In order to help them, it is possible
+to make recommendations or instructions visible to them by inserting
+special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
+Gettext}):
+
address@hidden
+;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
+(description "ARandR is designed to provide a simple visual front end
+for the X11 resize-and-rotate (RandR) extension. @dots{}")
address@hidden example
+
+
address@hidden Python Modules
address@hidden Python Modules
+
address@hidden python
+We currently package Python 2 and Python 3, under the Scheme variable names
address@hidden 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
address@hidden; if it compiles only with Python 2, we name it
address@hidden 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
address@hidden and @code{python2-dateutil}. If the project name
+starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
+described above.
+
address@hidden Specifying Dependencies
address@hidden inputs, for Python packages
+
+Dependency information for Python packages is usually available in the
+package source tree, with varying degrees of accuracy: in the
address@hidden file, in @file{requirements.txt}, or in @file{tox.ini}.
+
+Your mission, when writing a recipe for a Python package, is to map
+these dependencies to the appropriate type of ``input'' (@pxref{package
+Reference, inputs}). Although the @code{pypi} importer normally does a
+good job (@pxref{Invoking guix import}), you may want to check the
+following check list to determine which dependency goes where.
+
address@hidden
+
address@hidden
+We currently package Python 2 with @code{setuptools} and @code{pip}
+installed like Python 3.4 has per default. Thus you don't need to
+specify either of these as an input. @command{guix lint} will warn you
+if you do.
+
address@hidden
+Python dependencies required at run time go into
address@hidden They are typically defined with the
address@hidden keyword in @file{setup.py}, or in the
address@hidden file.
+
address@hidden
+Python packages required only at build time---e.g., those listed with
+the @code{setup_requires} keyword in @file{setup.py}---or only for
+testing---e.g., those in @code{tests_require}---go into
address@hidden The rationale is that (1) they do not need to be
+propagated because they are not needed at run time, and (2) in a
+cross-compilation context, it's the ``native'' input that we'd want.
+
+Examples are the @code{pytest}, @code{mock}, and @code{nose} test
+frameworks. Of course if any of these packages is also required at
+run-time, it needs to go to @code{propagated-inputs}.
+
address@hidden
+Anything that does not fall in the previous categories goes to
address@hidden, for example programs or C libraries required for building
+Python packages containing C extensions.
+
address@hidden
+If a Python package has optional dependencies (@code{extras_require}),
+it is up to you to decide whether to add them or not, based on their
+usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
+size}}).
+
address@hidden itemize
+
+
address@hidden Perl Modules
address@hidden Perl Modules
+
address@hidden perl
+Perl programs standing for themselves are named as any other package,
+using the lowercase upstream name.
+For Perl packages containing a single class, we use the lowercase class name,
+replace all occurrences of @code{::} by dashes and prepend the prefix
address@hidden
+So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
+Modules containing several classes keep their lowercase upstream name and
+are also prepended by @code{perl-}. Such modules tend to have the word
address@hidden somewhere in their name, which gets dropped in favor of the
+prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
+
+
address@hidden Java Packages
address@hidden Java Packages
+
address@hidden java
+Java programs standing for themselves are named as any other package,
+using the lowercase upstream name.
+
+To avoid confusion and naming clashes with other programming languages,
+it is desirable that the name of a package for a Java package is
+prefixed with @code{java-}. If a project already contains the word
address@hidden, we drop this; for instance, the package @code{ngsjava} is
+packaged under the name @code{java-ngs}.
+
+For Java packages containing a single class or a small class hierarchy,
+we use the lowercase class name, replace all occurrences of @code{.} by
+dashes and prepend the prefix @code{java-}. So the class
address@hidden becomes package
address@hidden
+
+
address@hidden Fonts
address@hidden Fonts
+
address@hidden fonts
+For fonts that are in general not installed by a user for typesetting
+purposes, or that are distributed as part of a larger software package,
+we rely on the general packaging rules for software; for instance, this
+applies to the fonts delivered as part of the X.Org system or fonts that
+are part of TeX Live.
+
+To make it easier for a user to search for fonts, names for other packages
+containing only fonts are constructed as follows, independently of the
+upstream package name.
+
+The name of a package containing only one font family starts with
address@hidden; it is followed by the foundry name and a dash @code{-}
+if the foundry is known, and the font family name, in which spaces are
+replaced by dashes (and as usual, all upper case letters are transformed
+to lower case).
+For example, the Gentium font family by SIL is packaged under the name
address@hidden
+
+For a package containing several font families, the name of the collection
+is used in the place of the font family name.
+For instance, the Liberation fonts consist of three families,
+Liberation Sans, Liberation Serif and Liberation Mono.
+These could be packaged separately under the names
address@hidden and so on; but as they are distributed together
+under a common name, we prefer to package them together as
address@hidden
+
+In the case where several formats of the same font family or font collection
+are packaged separately, a short form of the format, prepended by a dash,
+is added to the package name. We use @code{-ttf} for TrueType fonts,
address@hidden for OpenType fonts and @code{-type1} for PostScript Type 1
+fonts.
+
+
@node Coding Style
@section Coding Style
diff --git a/doc/guix.texi b/doc/guix.texi
index 547ab8d..ef23701 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -126,7 +126,6 @@ Project}.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Package Modules:: Packages from the programmer's viewpoint.
-* Packaging Guidelines:: Growing the distribution.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
* Contributing:: Your help needed!
@@ -282,17 +281,6 @@ Defining Services
* Service Reference:: API reference.
* Shepherd Services:: A particular type of service.
-Packaging Guidelines
-
-* Software Freedom:: What may go into the distribution.
-* Package Naming:: What's in a name?
-* Version Numbers:: When the name is not enough.
-* Synopses and Descriptions:: Helping users find the right package.
-* Python Modules:: A touch of British comedy.
-* Perl Modules:: Little pearls.
-* Java Packages:: Coffee break.
-* Fonts:: Fond of fonts.
-
@end detailmenu
@end menu
@@ -24180,456 +24168,6 @@ distribution. The root of this dependency graph is a
small set of
bootstrap)} module. For more information on bootstrapping,
@pxref{Bootstrapping}.
address@hidden Packaging Guidelines
address@hidden Packaging Guidelines
-
address@hidden packages, creating
-The GNU distribution is nascent and may well lack some of your favorite
-packages. This section describes how you can help make the distribution
-grow. @xref{Contributing}, for additional information on how you can
-help.
-
-Free software packages are usually distributed in the form of
address@hidden code tarballs}---typically @file{tar.gz} files that contain
-all the source files. Adding a package to the distribution means
-essentially two things: adding a @dfn{recipe} that describes how to
-build the package, including a list of other packages required to build
-it, and adding @dfn{package metadata} along with that recipe, such as a
-description and licensing information.
-
-In Guix all this information is embodied in @dfn{package definitions}.
-Package definitions provide a high-level view of the package. They are
-written using the syntax of the Scheme programming language; in fact,
-for each package we define a variable bound to the package definition,
-and export that variable from a module (@pxref{Package Modules}).
-However, in-depth Scheme knowledge is @emph{not} a prerequisite for
-creating packages. For more information on package definitions,
address@hidden Packages}.
-
-Once a package definition is in place, stored in a file in the Guix
-source tree, it can be tested using the @command{guix build} command
-(@pxref{Invoking guix build}). For example, assuming the new package is
-called @code{gnew}, you may run this command from the Guix build tree
-(@pxref{Running Guix Before It Is Installed}):
-
address@hidden
-./pre-inst-env guix build gnew --keep-failed
address@hidden example
-
-Using @code{--keep-failed} makes it easier to debug build failures since
-it provides access to the failed build tree. Another useful
-command-line option when debugging is @code{--log-file}, to access the
-build log.
-
-If the package is unknown to the @command{guix} command, it may be that
-the source file contains a syntax error, or lacks a @code{define-public}
-clause to export the package variable. To figure it out, you may load
-the module from Guile to get more information about the actual error:
-
address@hidden
-./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
address@hidden example
-
-Once your package builds correctly, please send us a patch
-(@pxref{Contributing}). Well, if you need help, we will be happy to
-help you too. Once the patch is committed in the Guix repository, the
-new package automatically gets built on the supported platforms by
address@hidden://hydra.gnu.org/jobset/gnu/master, our continuous integration
-system}.
-
address@hidden substituter
-Users can obtain the new package definition simply by running
address@hidden pull} (@pxref{Invoking guix pull}). When
address@hidden@value{SUBSTITUTE-SERVER}} is done building the package,
installing the
-package automatically downloads binaries from there
-(@pxref{Substitutes}). The only place where human intervention is
-needed is to review and apply the patch.
-
-
address@hidden
-* Software Freedom:: What may go into the distribution.
-* Package Naming:: What's in a name?
-* Version Numbers:: When the name is not enough.
-* Synopses and Descriptions:: Helping users find the right package.
-* Python Modules:: A touch of British comedy.
-* Perl Modules:: Little pearls.
-* Java Packages:: Coffee break.
-* Fonts:: Fond of fonts.
address@hidden menu
-
address@hidden Software Freedom
address@hidden Software Freedom
-
address@hidden Adapted from http://www.gnu.org/philosophy/philosophy.html.
address@hidden free software
-The GNU operating system has been developed so that users can have
-freedom in their computing. GNU is @dfn{free software}, meaning that
-users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
-essential freedoms}: to run the program, to study and change the program
-in source code form, to redistribute exact copies, and to distribute
-modified versions. Packages found in the GNU distribution provide only
-software that conveys these four freedoms.
-
-In addition, the GNU distribution follow the
address@hidden://www.gnu.org/distros/free-system-distribution-guidelines.html,free
-software distribution guidelines}. Among other things, these guidelines
-reject non-free firmware, recommendations of non-free software, and
-discuss ways to deal with trademarks and patents.
-
-Some otherwise free upstream package sources contain a small and optional
-subset that violates the above guidelines, for instance because this subset
-is itself non-free code. When that happens, the offending items are removed
-with appropriate patches or code snippets in the @code{origin} form of the
-package (@pxref{Defining Packages}). This way, @code{guix
-build --source} returns the ``freed'' source rather than the unmodified
-upstream source.
-
-
address@hidden Package Naming
address@hidden Package Naming
-
address@hidden package name
-A package has actually two names associated with it:
-First, there is the name of the @emph{Scheme variable}, the one following
address@hidden 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 package management commands such as
address@hidden package} and @command{guix build}.
-
-Both are usually the same and correspond to the lowercase conversion of
-the project name chosen upstream, with underscores replaced with
-hyphens. For instance, GNUnet is available as @code{gnunet}, and
-SDL_net as @code{sdl-net}.
-
-We do not add @code{lib} prefixes for library packages, unless these are
-already part of the official project name. But @pxref{Python
-Modules} and @ref{Perl Modules} for special rules concerning modules for
-the Python and Perl languages.
-
-Font package names are handled differently, @pxref{Fonts}.
-
-
address@hidden Version Numbers
address@hidden Version Numbers
-
address@hidden package version
-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:
-
address@hidden
-(define-public gtk+
- (package
- (name "gtk+")
- (version "3.9.12")
- ...))
-(define-public gtk+-2
- (package
- (name "gtk+")
- (version "2.24.20")
- ...))
address@hidden example
-If we also wanted GTK+ 3.8.2, this would be packaged as
address@hidden
-(define-public gtk+-3.8
- (package
- (name "gtk+")
- (version "3.8.2")
- ...))
address@hidden example
-
address@hidden See
<https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
address@hidden for a discussion of what follows.
address@hidden version number, for VCS snapshots
-Occasionally, we package snapshots of upstream's version control system
-(VCS) instead of formal releases. This should remain exceptional,
-because it is up to upstream developers to clarify what the stable
-release is. Yet, it is sometimes necessary. So, what should we put in
-the @code{version} field?
-
-Clearly, we need to make the commit identifier of the VCS snapshot
-visible in the version string, but we also need to make sure that the
-version string is monotonically increasing so that @command{guix package
---upgrade} can determine which version is newer. Since commit
-identifiers, notably with Git, are not monotonically increasing, we add
-a revision number that we increase each time we upgrade to a newer
-snapshot. The resulting version string looks like this:
-
address@hidden
-2.0.11-3.cabba9e
- ^ ^ ^
- | | `-- upstream commit ID
- | |
- | `--- Guix package revision
- |
-latest upstream version
address@hidden example
-
-It is a good idea to strip commit identifiers in the @code{version}
-field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
-aesthetics have a role to play here) as well as problems related to OS
-limits such as the maximum shebang length (127 bytes for the Linux
-kernel.) It is best to use the full commit identifiers in
address@hidden, though, to avoid ambiguities. A typical package
-definition may look like this:
-
address@hidden
-(define my-package
- (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
- (revision "1")) ;Guix package revision
- (package
- (version (git-version "0.9" revision commit))
- (source (origin
- (method git-fetch)
- (uri (git-reference
- (url "git://example.org/my-package.git")
- (commit commit)))
- (sha256 (base32 "address@hidden"))
- (file-name (git-file-name name version))))
- ;; @dots{}
- )))
address@hidden example
-
address@hidden Synopses and Descriptions
address@hidden Synopses and Descriptions
-
address@hidden package description
address@hidden package synopsis
-As we have seen before, each package in address@hidden includes a
-synopsis and a description (@pxref{Defining Packages}). Synopses and
-descriptions are important: They are what @command{guix package
---search} searches, and a crucial piece of information to help users
-determine whether a given package suits their needs. Consequently,
-packagers should pay attention to what goes into them.
-
-Synopses must start with a capital letter and must not end with a
-period. They must not start with ``a'' or ``the'', which usually does
-not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
-tool that frobs files''. The synopsis should say what the package
-is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
-used for---e.g., the synopsis for address@hidden is ``Print lines
-matching a pattern''.
-
-Keep in mind that the synopsis must be meaningful for a very wide
-audience. For example, ``Manipulate alignments in the SAM format''
-might make sense for a seasoned bioinformatics researcher, but might be
-fairly unhelpful or even misleading to a non-specialized audience. It
-is a good idea to come up with a synopsis that gives an idea of the
-application domain of the package. In this example, this might give
-something like ``Manipulate nucleotide sequence alignments'', which
-hopefully gives the user a better idea of whether this is what they are
-looking for.
-
-Descriptions should take between five and ten lines. Use full
-sentences, and avoid using acronyms without first introducing them.
-Please avoid marketing phrases such as ``world-leading'',
-``industrial-strength'', and ``next-generation'', and avoid superlatives
-like ``the most advanced''---they are not helpful to users looking for a
-package and may even sound suspicious. Instead, try to be factual,
-mentioning use cases and features.
-
address@hidden Texinfo markup, in package descriptions
-Descriptions can include Texinfo markup, which is useful to introduce
-ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
-hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
-should be careful when using some characters for example @samp{@@} and
-curly braces which are the basic special characters in Texinfo
-(@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
-such as @command{guix package --show} take care of rendering it
-appropriately.
-
-Synopses and descriptions are translated by volunteers
address@hidden://translationproject.org/domain/guix-packages.html, at the
-Translation Project} so that as many users as possible can read them in
-their native language. User interfaces search them and display them in
-the language specified by the current locale.
-
-To allow @command{xgettext} to extract them as translatable strings,
-synopses and descriptions @emph{must be literal strings}. This means
-that you cannot use @code{string-append} or @code{format} to construct
-these strings:
-
address@hidden
-(package
- ;; @dots{}
- (synopsis "This is translatable")
- (description (string-append "This is " "*not*" " translatable.")))
address@hidden lisp
-
-Translation is a lot of work so, as a packager, please pay even more
-attention to your synopses and descriptions as every change may entail
-additional work for translators. In order to help them, it is possible
-to make recommendations or instructions visible to them by inserting
-special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
-Gettext}):
-
address@hidden
-;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
-(description "ARandR is designed to provide a simple visual front end
-for the X11 resize-and-rotate (RandR) extension. @dots{}")
address@hidden example
-
-
address@hidden Python Modules
address@hidden Python Modules
-
address@hidden python
-We currently package Python 2 and Python 3, under the Scheme variable names
address@hidden 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
address@hidden; if it compiles only with Python 2, we name it
address@hidden 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
address@hidden and @code{python2-dateutil}. If the project name
-starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
-described above.
-
address@hidden Specifying Dependencies
address@hidden inputs, for Python packages
-
-Dependency information for Python packages is usually available in the
-package source tree, with varying degrees of accuracy: in the
address@hidden file, in @file{requirements.txt}, or in @file{tox.ini}.
-
-Your mission, when writing a recipe for a Python package, is to map
-these dependencies to the appropriate type of ``input'' (@pxref{package
-Reference, inputs}). Although the @code{pypi} importer normally does a
-good job (@pxref{Invoking guix import}), you may want to check the
-following check list to determine which dependency goes where.
-
address@hidden
-
address@hidden
-We currently package Python 2 with @code{setuptools} and @code{pip}
-installed like Python 3.4 has per default. Thus you don't need to
-specify either of these as an input. @command{guix lint} will warn you
-if you do.
-
address@hidden
-Python dependencies required at run time go into
address@hidden They are typically defined with the
address@hidden keyword in @file{setup.py}, or in the
address@hidden file.
-
address@hidden
-Python packages required only at build time---e.g., those listed with
-the @code{setup_requires} keyword in @file{setup.py}---or only for
-testing---e.g., those in @code{tests_require}---go into
address@hidden The rationale is that (1) they do not need to be
-propagated because they are not needed at run time, and (2) in a
-cross-compilation context, it's the ``native'' input that we'd want.
-
-Examples are the @code{pytest}, @code{mock}, and @code{nose} test
-frameworks. Of course if any of these packages is also required at
-run-time, it needs to go to @code{propagated-inputs}.
-
address@hidden
-Anything that does not fall in the previous categories goes to
address@hidden, for example programs or C libraries required for building
-Python packages containing C extensions.
-
address@hidden
-If a Python package has optional dependencies (@code{extras_require}),
-it is up to you to decide whether to add them or not, based on their
-usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
-size}}).
-
address@hidden itemize
-
-
address@hidden Perl Modules
address@hidden Perl Modules
-
address@hidden perl
-Perl programs standing for themselves are named as any other package,
-using the lowercase upstream name.
-For Perl packages containing a single class, we use the lowercase class name,
-replace all occurrences of @code{::} by dashes and prepend the prefix
address@hidden
-So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
-Modules containing several classes keep their lowercase upstream name and
-are also prepended by @code{perl-}. Such modules tend to have the word
address@hidden somewhere in their name, which gets dropped in favor of the
-prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
-
-
address@hidden Java Packages
address@hidden Java Packages
-
address@hidden java
-Java programs standing for themselves are named as any other package,
-using the lowercase upstream name.
-
-To avoid confusion and naming clashes with other programming languages,
-it is desirable that the name of a package for a Java package is
-prefixed with @code{java-}. If a project already contains the word
address@hidden, we drop this; for instance, the package @code{ngsjava} is
-packaged under the name @code{java-ngs}.
-
-For Java packages containing a single class or a small class hierarchy,
-we use the lowercase class name, replace all occurrences of @code{.} by
-dashes and prepend the prefix @code{java-}. So the class
address@hidden becomes package
address@hidden
-
-
address@hidden Fonts
address@hidden Fonts
-
address@hidden fonts
-For fonts that are in general not installed by a user for typesetting
-purposes, or that are distributed as part of a larger software package,
-we rely on the general packaging rules for software; for instance, this
-applies to the fonts delivered as part of the X.Org system or fonts that
-are part of TeX Live.
-
-To make it easier for a user to search for fonts, names for other packages
-containing only fonts are constructed as follows, independently of the
-upstream package name.
-
-The name of a package containing only one font family starts with
address@hidden; it is followed by the foundry name and a dash @code{-}
-if the foundry is known, and the font family name, in which spaces are
-replaced by dashes (and as usual, all upper case letters are transformed
-to lower case).
-For example, the Gentium font family by SIL is packaged under the name
address@hidden
-
-For a package containing several font families, the name of the collection
-is used in the place of the font family name.
-For instance, the Liberation fonts consist of three families,
-Liberation Sans, Liberation Serif and Liberation Mono.
-These could be packaged separately under the names
address@hidden and so on; but as they are distributed together
-under a common name, we prefer to package them together as
address@hidden
-
-In the case where several formats of the same font family or font collection
-are packaged separately, a short form of the format, prepended by a dash,
-is added to the package name. We use @code{-ttf} for TrueType fonts,
address@hidden for OpenType fonts and @code{-type1} for PostScript Type 1
-fonts.
-
-
@node Bootstrapping
@chapter Bootstrapping
- branch master updated (d1dfcc7 -> ce6236f), guix-commits, 2019/01/22
- 02/11: self: Remove leftover export., guix-commits, 2019/01/22
- 04/11: compile: Let compiler warnings through during the load phase., guix-commits, 2019/01/22
- 03/11: gnu: Remove duplicate record fields., guix-commits, 2019/01/22
- 01/11: vm: Remove unnecessary import., guix-commits, 2019/01/22
- 05/11: records: Detect duplicate field initializers., guix-commits, 2019/01/22
- 07/11: self: System tests depend on CLI modules., guix-commits, 2019/01/22
- 06/11: offload: 'status' reports the time difference., guix-commits, 2019/01/22
- 11/11: doc: Move "Package Modules" under "Programming Interface"., guix-commits, 2019/01/22
- 08/11: doc: Move sections under "GNU Distribution" one level higher., guix-commits, 2019/01/22
- 10/11: doc: Move "Packaging Guidelines" under "Contributing".,
guix-commits <=
- 09/11: doc: Move "System Installation" right after "Installation"., guix-commits, 2019/01/22