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.

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,