17.4 Packaging Guidelines

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 source code tarballs—typically tar.gz files that contain all the source files. Adding a package to the distribution means essentially two things: adding a recipe that describes how to build the package, including a list of other packages required to build it, and adding package metadata along with that recipe, such as a description and licensing information.

In Guix all this information is embodied in 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 (see Package Modules). However, in-depth Scheme knowledge is not a prerequisite for creating packages. For more information on package definitions, see Defining Packages.

Once a package definition is in place, stored in a file in the Guix source tree, it can be tested using the guix build command (see Invoking guix build). For example, assuming the new package is called gnew, you may run this command from the Guix build tree (see Running Guix Before It Is Installed):

./pre-inst-env guix build gnew --keep-failed

Using --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 --log-file, to access the build log.

If the package is unknown to the guix command, it may be that the source file contains a syntax error, or lacks a 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:

./pre-inst-env guile -c '(use-modules (gnu packages gnew))'

Once your package builds correctly, please send us a patch (see 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 our continuous integration system.

Users can obtain the new package definition simply by running guix pull (see Invoking guix pull). When ci.guix.gnu.org is done building the package, installing the package automatically downloads binaries from there (see Substitutes). The only place where human intervention is needed is to review and apply the patch.