summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2013-07-17 11:59:48 +0200
committerLudovic Courtès <ludo@gnu.org>2013-07-17 11:59:48 +0200
commitb81e194706842c889bfebd710d79fe9fdfb12775 (patch)
tree85a3756d773a37d58bb21de258d9680bdc3ef182 /doc
parentc71493c8b9328ff3dbddf3b9430200ef4d174917 (diff)
doc: Add "Adding New Packages".
* doc/guix.texi (Adding New Packages): New section. (Packaging Guidelines): Make a subsection thereof. (From the Source Tarball to the Package): New subsection. (Contributing): Link to "Adding New Packages". (Package Modules): Link to modules in Guile's manual.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi111
1 files changed, 87 insertions, 24 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index ab31ffd575..684382720e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1482,9 +1482,9 @@ tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.
@menu
-* Packaging Guidelines:: What goes into the distribution.
* Installing Debugging Files:: Feeding the debugger.
* Package Modules:: Packages from the programmer's viewpoint.
+* Adding New Packages:: Growing the distribution.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
@end menu
@@ -1492,25 +1492,6 @@ tools that help users exert that freedom.
Building this distribution is a cooperative effort, and you are invited
to join! @ref{Contributing}, for information about how you can help.
-@node Packaging Guidelines
-@section Packaging Guidelines
-
-@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
-
-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.
-
@node Installing Debugging Files
@section Installing Debugging Files
@@ -1575,8 +1556,9 @@ the load. To check whether a package has a @code{debug} output, use
From a programming viewpoint, the package definitions of the
distribution are provided by Guile modules in the @code{(gnu packages
-...)} name space---for instance, the @code{(gnu packages emacs)} module
-exports a variable named @code{emacs}, which is bound to a
+...)} name space (@pxref{Modules, Guile modules,, guile, GNU Guile
+Reference Manual}). For instance, the @code{(gnu packages emacs)}
+module exports a variable named @code{emacs}, which is bound to a
@code{<package>} object (@pxref{Defining Packages}). The @code{(gnu
packages)} module provides facilities for searching for packages.
@@ -1584,7 +1566,87 @@ The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
each package is built based solely on other packages in the
distribution. The root of this dependency graph is a small set of
@dfn{bootstrap binaries}, provided by the @code{(gnu packages
-bootstrap)} module. More on this in the next section.
+bootstrap)} module. For more information on bootstrapping,
+@ref{Bootstrapping}.
+
+@node Adding New Packages
+@section Adding New Packages
+
+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. @ref{Contributing}, for additional information on how you can
+help.
+
+@menu
+* Packaging Guidelines:: What goes into the distribution.
+* From the Source Tarball to the Package:: The story of a package.
+@end menu
+
+@node Packaging Guidelines
+@subsection Packaging Guidelines
+
+@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
+
+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.
+
+@node From the Source Tarball to the Package
+@subsection From the Source Tarball, to the Package Definition, to the Binary Package
+
+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 meta-data} 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,
+@ref{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:
+
+@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.
+
+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/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{hydra.gnu.org} is done building the package, installing the
+package automatically downloads binaries from there (except when using
+@code{--no-substitutes}). The only place where human intervention is
+needed is to review and apply the patch.
@node Bootstrapping
@@ -1756,7 +1818,8 @@ reason.
This project is a cooperative effort, and we need your help to make it
grow! Please get in touch with us on @email{guix-devel@@gnu.org}. We
welcome ideas, bug reports, patches, and anything that may be helpful to
-the project.
+the project. We particularly welcome help on packaging (@pxref{Adding
+New Packages}).
Please see the
@url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,