mirror of
https://git.in.rschanz.org/ryan77627/guix.git
synced 2024-12-23 21:17:11 -05:00
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".
This commit is contained in:
Ludovic Courtès
parent
83db020506
commit
afe7408e19
2 changed files with 450 additions and 462 deletions
|
|
@ -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.
|
||||
|
||||
|
||||
@node Packaging Guidelines
|
||||
@section Packaging Guidelines
|
||||
|
||||
@cindex 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
|
||||
@dfn{source 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,
|
||||
@pxref{Defining 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}):
|
||||
|
||||
@example
|
||||
./pre-inst-env guix build gnew --keep-failed
|
||||
@end 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:
|
||||
|
||||
@example
|
||||
./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
|
||||
@end 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
|
||||
@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
|
||||
system}.
|
||||
|
||||
@cindex substituter
|
||||
Users can obtain the new package definition simply by running
|
||||
@command{guix pull} (@pxref{Invoking guix pull}). When
|
||||
@code{@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.
|
||||
|
||||
|
||||
@menu
|
||||
* 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 menu
|
||||
|
||||
@node Software Freedom
|
||||
@subsection Software Freedom
|
||||
|
||||
@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
|
||||
@cindex 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
|
||||
@url{http://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.
|
||||
|
||||
|
||||
@node Package Naming
|
||||
@subsection Package Naming
|
||||
|
||||
@cindex package name
|
||||
A package has actually two names associated with 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 package management commands such as
|
||||
@command{guix 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}.
|
||||
|
||||
|
||||
@node Version Numbers
|
||||
@subsection Version Numbers
|
||||
|
||||
@cindex 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:
|
||||
|
||||
@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
|
||||
|
||||
@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
|
||||
@c for a discussion of what follows.
|
||||
@cindex 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:
|
||||
|
||||
@example
|
||||
2.0.11-3.cabba9e
|
||||
^ ^ ^
|
||||
| | `-- upstream commit ID
|
||||
| |
|
||||
| `--- Guix package revision
|
||||
|
|
||||
latest upstream version
|
||||
@end 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
|
||||
@code{origin}s, though, to avoid ambiguities. A typical package
|
||||
definition may look like this:
|
||||
|
||||
@example
|
||||
(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 "1mbikn@dots{}"))
|
||||
(file-name (git-file-name name version))))
|
||||
;; @dots{}
|
||||
)))
|
||||
@end example
|
||||
|
||||
@node Synopses and Descriptions
|
||||
@subsection Synopses and Descriptions
|
||||
|
||||
@cindex package description
|
||||
@cindex package synopsis
|
||||
As we have seen before, each package in GNU@tie{}Guix 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 GNU@tie{}grep 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.
|
||||
|
||||
@cindex 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
|
||||
@uref{http://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:
|
||||
|
||||
@lisp
|
||||
(package
|
||||
;; @dots{}
|
||||
(synopsis "This is translatable")
|
||||
(description (string-append "This is " "*not*" " translatable.")))
|
||||
@end 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}):
|
||||
|
||||
@example
|
||||
;; 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{}")
|
||||
@end example
|
||||
|
||||
|
||||
@node Python Modules
|
||||
@subsection Python Modules
|
||||
|
||||
@cindex python
|
||||
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}. If the project name
|
||||
starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
|
||||
described above.
|
||||
|
||||
@subsubsection Specifying Dependencies
|
||||
@cindex inputs, for Python packages
|
||||
|
||||
Dependency information for Python packages is usually available in the
|
||||
package source tree, with varying degrees of accuracy: in the
|
||||
@file{setup.py} 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.
|
||||
|
||||
@itemize
|
||||
|
||||
@item
|
||||
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.
|
||||
|
||||
@item
|
||||
Python dependencies required at run time go into
|
||||
@code{propagated-inputs}. They are typically defined with the
|
||||
@code{install_requires} keyword in @file{setup.py}, or in the
|
||||
@file{requirements.txt} file.
|
||||
|
||||
@item
|
||||
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
|
||||
@code{native-inputs}. 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}.
|
||||
|
||||
@item
|
||||
Anything that does not fall in the previous categories goes to
|
||||
@code{inputs}, for example programs or C libraries required for building
|
||||
Python packages containing C extensions.
|
||||
|
||||
@item
|
||||
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}}).
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
@node Perl Modules
|
||||
@subsection Perl Modules
|
||||
|
||||
@cindex 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
|
||||
@code{perl-}.
|
||||
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
|
||||
@code{perl} somewhere in their name, which gets dropped in favor of the
|
||||
prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
|
||||
|
||||
|
||||
@node Java Packages
|
||||
@subsection Java Packages
|
||||
|
||||
@cindex 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
|
||||
@code{java}, 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
|
||||
@code{apache.commons.cli} becomes package
|
||||
@code{java-apache-commons-cli}.
|
||||
|
||||
|
||||
@node Fonts
|
||||
@subsection Fonts
|
||||
|
||||
@cindex 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
|
||||
@code{font-}; 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
|
||||
@code{font-sil-gentium}.
|
||||
|
||||
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
|
||||
@code{font-liberation-sans} and so on; but as they are distributed together
|
||||
under a common name, we prefer to package them together as
|
||||
@code{font-liberation}.
|
||||
|
||||
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,
|
||||
@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
|
||||
fonts.
|
||||
|
||||
|
||||
@node Coding Style
|
||||
@section Coding Style
|
||||
|
||||
|
|
|
|||
462
doc/guix.texi
462
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}.
|
||||
|
||||
@node Packaging Guidelines
|
||||
@chapter Packaging Guidelines
|
||||
|
||||
@cindex 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
|
||||
@dfn{source 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,
|
||||
@pxref{Defining 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}):
|
||||
|
||||
@example
|
||||
./pre-inst-env guix build gnew --keep-failed
|
||||
@end 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:
|
||||
|
||||
@example
|
||||
./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
|
||||
@end 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
|
||||
@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
|
||||
system}.
|
||||
|
||||
@cindex substituter
|
||||
Users can obtain the new package definition simply by running
|
||||
@command{guix pull} (@pxref{Invoking guix pull}). When
|
||||
@code{@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.
|
||||
|
||||
|
||||
@menu
|
||||
* 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 menu
|
||||
|
||||
@node Software Freedom
|
||||
@section Software Freedom
|
||||
|
||||
@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
|
||||
@cindex 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
|
||||
@url{http://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.
|
||||
|
||||
|
||||
@node Package Naming
|
||||
@section Package Naming
|
||||
|
||||
@cindex package name
|
||||
A package has actually two names associated with 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 package management commands such as
|
||||
@command{guix 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}.
|
||||
|
||||
|
||||
@node Version Numbers
|
||||
@section Version Numbers
|
||||
|
||||
@cindex 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:
|
||||
|
||||
@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
|
||||
|
||||
@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
|
||||
@c for a discussion of what follows.
|
||||
@cindex 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:
|
||||
|
||||
@example
|
||||
2.0.11-3.cabba9e
|
||||
^ ^ ^
|
||||
| | `-- upstream commit ID
|
||||
| |
|
||||
| `--- Guix package revision
|
||||
|
|
||||
latest upstream version
|
||||
@end 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
|
||||
@code{origin}s, though, to avoid ambiguities. A typical package
|
||||
definition may look like this:
|
||||
|
||||
@example
|
||||
(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 "1mbikn@dots{}"))
|
||||
(file-name (git-file-name name version))))
|
||||
;; @dots{}
|
||||
)))
|
||||
@end example
|
||||
|
||||
@node Synopses and Descriptions
|
||||
@section Synopses and Descriptions
|
||||
|
||||
@cindex package description
|
||||
@cindex package synopsis
|
||||
As we have seen before, each package in GNU@tie{}Guix 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 GNU@tie{}grep 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.
|
||||
|
||||
@cindex 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
|
||||
@uref{http://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:
|
||||
|
||||
@lisp
|
||||
(package
|
||||
;; @dots{}
|
||||
(synopsis "This is translatable")
|
||||
(description (string-append "This is " "*not*" " translatable.")))
|
||||
@end 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}):
|
||||
|
||||
@example
|
||||
;; 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{}")
|
||||
@end example
|
||||
|
||||
|
||||
@node Python Modules
|
||||
@section Python Modules
|
||||
|
||||
@cindex python
|
||||
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}. If the project name
|
||||
starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
|
||||
described above.
|
||||
|
||||
@subsection Specifying Dependencies
|
||||
@cindex inputs, for Python packages
|
||||
|
||||
Dependency information for Python packages is usually available in the
|
||||
package source tree, with varying degrees of accuracy: in the
|
||||
@file{setup.py} 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.
|
||||
|
||||
@itemize
|
||||
|
||||
@item
|
||||
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.
|
||||
|
||||
@item
|
||||
Python dependencies required at run time go into
|
||||
@code{propagated-inputs}. They are typically defined with the
|
||||
@code{install_requires} keyword in @file{setup.py}, or in the
|
||||
@file{requirements.txt} file.
|
||||
|
||||
@item
|
||||
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
|
||||
@code{native-inputs}. 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}.
|
||||
|
||||
@item
|
||||
Anything that does not fall in the previous categories goes to
|
||||
@code{inputs}, for example programs or C libraries required for building
|
||||
Python packages containing C extensions.
|
||||
|
||||
@item
|
||||
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}}).
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
@node Perl Modules
|
||||
@section Perl Modules
|
||||
|
||||
@cindex 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
|
||||
@code{perl-}.
|
||||
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
|
||||
@code{perl} somewhere in their name, which gets dropped in favor of the
|
||||
prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
|
||||
|
||||
|
||||
@node Java Packages
|
||||
@section Java Packages
|
||||
|
||||
@cindex 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
|
||||
@code{java}, 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
|
||||
@code{apache.commons.cli} becomes package
|
||||
@code{java-apache-commons-cli}.
|
||||
|
||||
|
||||
@node Fonts
|
||||
@section Fonts
|
||||
|
||||
@cindex 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
|
||||
@code{font-}; 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
|
||||
@code{font-sil-gentium}.
|
||||
|
||||
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
|
||||
@code{font-liberation-sans} and so on; but as they are distributed together
|
||||
under a common name, we prefer to package them together as
|
||||
@code{font-liberation}.
|
||||
|
||||
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,
|
||||
@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
|
||||
fonts.
|
||||
|
||||
|
||||
|
||||
@node Bootstrapping
|
||||
@chapter Bootstrapping
|
||||
|
|
|
|||
Loading…
Reference in a new issue