4 This project is a cooperative effort, and we need your help to make it
5 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
6 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
7 reports, patches, and anything that may be helpful to the project. We
8 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
10 @cindex code of conduct, of contributors
11 @cindex contributor covenant
12 We want to provide a warm, friendly, and harassment-free environment, so
13 that anyone can contribute to the best of their abilities. To this end
14 our project uses a ``Contributor Covenant'', which was adapted from
15 @url{http://contributor-covenant.org/}. You can find a local version in
16 the @file{CODE-OF-CONDUCT} file in the source tree.
18 Contributors are not required to use their legal name in patches and
19 on-line communication; they can use any name or pseudonym of their
23 * Building from Git:: The latest and greatest.
24 * Running Guix Before It Is Installed:: Hacker tricks.
25 * The Perfect Setup:: The right tools.
26 * Packaging Guidelines:: Growing the distribution.
27 * Coding Style:: Hygiene of the contributor.
28 * Submitting Patches:: Share your work.
29 * Tracking Bugs and Patches:: Using Debbugs.
30 * Commit Access:: Pushing to the official repository.
33 @node Building from Git
34 @section Building from Git
36 If you want to hack Guix itself, it is recommended to use the latest
37 version from the Git repository:
40 git clone https://git.savannah.gnu.org/git/guix.git
43 @cindex authentication, of a Guix checkout
44 How do you ensure that you obtained a genuine copy of the repository?
45 Guix itself provides a tool to @dfn{authenticate} your checkout, but you
46 must first make sure this tool is genuine in order to ``bootstrap'' the
47 trust chain. To do that, run:
49 @c XXX: Adjust instructions when there's a known tag to start from.
51 git verify-commit `git log --format=%H build-aux/git-authenticate.scm`
54 The output must look something like:
57 gpg: Signature made Fri 27 Dec 2019 01:27:41 PM CET
58 gpg: using RSA key 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
60 gpg: Signature made Fri 27 Dec 2019 01:25:22 PM CET
61 gpg: using RSA key 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
66 ... meaning that changes to this file are all signed with key
67 @code{3CE464558A84FDC69DB40CFB090B11993D9AEBB5} (you may need to fetch
68 this key from a key server, if you have not done it yet).
70 From there on, you can authenticate all the commits included in your
77 The first run takes a couple of minutes, but subsequent runs are faster.
80 You are advised to run @command{make authenticate} after every
81 @command{git pull} invocation. This ensures you keep receiving valid
82 changes to the repository
85 The easiest way to set up a development environment for Guix is, of
86 course, by using Guix! The following command starts a new shell where
87 all the dependencies and appropriate environment variables are set up to
91 guix environment guix --pure
94 @xref{Invoking guix environment}, for more information on that command.
96 If you are unable to use Guix when building Guix from a checkout, the
97 following are the required packages in addition to those mentioned in the
98 installation instructions (@pxref{Requirements}).
101 @item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
102 @item @url{http://gnu.org/software/automake/, GNU Automake};
103 @item @url{http://gnu.org/software/gettext/, GNU Gettext};
104 @item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
105 @item @url{http://www.graphviz.org/, Graphviz};
106 @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
109 On Guix, extra dependencies can be added by instead running @command{guix
110 environment} with @option{--ad-hoc}:
113 guix environment guix --pure --ad-hoc help2man git strace
116 Run @command{./bootstrap} to generate the build system infrastructure
117 using Autoconf and Automake. If you get an error like this one:
120 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
124 it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
125 provided by pkg-config. Make sure that @file{pkg.m4} is available. The
126 same holds for the @file{guile.m4} set of macros provided by Guile. For
127 instance, if you installed Automake in @file{/usr/local}, it wouldn’t
128 look for @file{.m4} files in @file{/usr/share}. In that case, you have
129 to invoke the following command:
132 export ACLOCAL_PATH=/usr/share/aclocal
135 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
138 Then, run @command{./configure} as usual. Make sure to pass
139 @code{--localstatedir=@var{directory}} where @var{directory} is the
140 @code{localstatedir} value used by your current installation (@pxref{The
141 Store}, for information about this). We recommend to use the value
144 Finally, you have to invoke @code{make check} to run tests
145 (@pxref{Running the Test Suite}). If anything
146 fails, take a look at installation instructions (@pxref{Installation})
147 or send a message to the @email{guix-devel@@gnu.org, mailing list}.
150 @node Running Guix Before It Is Installed
151 @section Running Guix Before It Is Installed
153 In order to keep a sane working environment, you will find it useful to
154 test the changes made in your local source tree checkout without
155 actually installing them. So that you can distinguish between your
156 ``end-user'' hat and your ``motley'' costume.
158 To that end, all the command-line tools can be used even if you have not
159 run @code{make install}. To do that, you first need to have an environment
160 with all the dependencies available (@pxref{Building from Git}), and then
161 simply prefix each command with
162 @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
163 top build tree of Guix; it is generated by @command{./configure}).
164 An example@footnote{The @option{-E} flag to
165 @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
166 such that @command{guix-daemon} and the tools it uses can find the Guile
170 $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
171 $ ./pre-inst-env guix build hello
175 Similarly, an example for a Guile session using the Guix modules:
178 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
185 @cindex read-eval-print loop
186 @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
190 $ ./pre-inst-env guile
191 scheme@@(guile-user)> ,use(guix)
192 scheme@@(guile-user)> ,use(gnu)
193 scheme@@(guile-user)> (define snakes
195 (lambda (package lst)
196 (if (string-prefix? "python"
197 (package-name package))
201 scheme@@(guile-user)> (length snakes)
205 The @command{pre-inst-env} script sets up all the environment variables
206 necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
208 Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
209 local source tree; it simply updates the @file{~/.config/guix/current}
210 symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
211 you want to upgrade your local source tree.
214 @node The Perfect Setup
215 @section The Perfect Setup
217 The Perfect Setup to hack on Guix is basically the perfect setup used
218 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
219 Manual}). First, you need more than an editor, you need
220 @url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
221 wonderful @url{http://nongnu.org/geiser/, Geiser}. To set that up, run:
224 guix package -i emacs guile emacs-geiser
227 Geiser allows for interactive and incremental development from within
228 Emacs: code compilation and evaluation from within buffers, access to
229 on-line documentation (docstrings), context-sensitive completion,
230 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
231 and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
232 convenient Guix development, make sure to augment Guile’s load path so
233 that it finds source files from your checkout:
236 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
237 (with-eval-after-load 'geiser-guile
238 (add-to-list 'geiser-guile-load-path "~/src/guix"))
241 To actually edit the code, Emacs already has a neat Scheme mode. But in
242 addition to that, you must not miss
243 @url{https://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
244 facilities to directly operate on the syntax tree, such as raising an
245 s-expression or wrapping it, swallowing or rejecting the following
248 @cindex code snippets
250 @cindex reducing boilerplate
251 We also provide templates for common git commit messages and package
252 definitions in the @file{etc/snippets} directory. These templates can
253 be used with @url{http://joaotavora.github.io/yasnippet/, YASnippet} to
254 expand short trigger strings to interactive text snippets. You may want
255 to add the snippets directory to the @var{yas-snippet-dirs} variable in
259 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
260 (with-eval-after-load 'yasnippet
261 (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
264 The commit message snippets depend on @url{https://magit.vc/, Magit} to
265 display staged files. When editing a commit message type @code{add}
266 followed by @kbd{TAB} to insert a commit message template for adding a
267 package; type @code{update} followed by @kbd{TAB} to insert a template
268 for updating a package; type @code{https} followed by @kbd{TAB} to
269 insert a template for changing the home page URI of a package to HTTPS.
271 The main snippet for @code{scheme-mode} is triggered by typing
272 @code{package...} followed by @kbd{TAB}. This snippet also inserts the
273 trigger string @code{origin...}, which can be expanded further. The
274 @code{origin} snippet in turn may insert other trigger strings ending on
275 @code{...}, which also can be expanded further.
277 @cindex insert or update copyright
278 @cindex @code{M-x guix-copyright}
279 @cindex @code{M-x copyright-update}
280 Additionaly we provide insertion and automatic update of a copyright in
281 @file{etc/copyright.el}. You may want to set your full name, mail, and
285 (setq user-full-name "Alice Doe")
286 (setq user-mail-address "alice@@mail.org")
287 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
288 (load-file "~/src/guix/etc/copyright.el")
291 To insert a copyright at the current line invoke @code{M-x guix-copyright}.
293 To update a copyright you need to specify a @code{copyright-names-regexp}.
296 (setq copyright-names-regexp
297 (format "%s <%s>" user-full-name user-mail-address))
300 You can check if your copyright is up to date by evaluating @code{M-x
301 copyright-update}. If you want to do it automatically after each buffer
302 save then add @code{(add-hook 'after-save-hook 'copyright-update)} in
305 @node Packaging Guidelines
306 @section Packaging Guidelines
308 @cindex packages, creating
309 The GNU distribution is nascent and may well lack some of your favorite
310 packages. This section describes how you can help make the distribution
313 Free software packages are usually distributed in the form of
314 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
315 all the source files. Adding a package to the distribution means
316 essentially two things: adding a @dfn{recipe} that describes how to
317 build the package, including a list of other packages required to build
318 it, and adding @dfn{package metadata} along with that recipe, such as a
319 description and licensing information.
321 In Guix all this information is embodied in @dfn{package definitions}.
322 Package definitions provide a high-level view of the package. They are
323 written using the syntax of the Scheme programming language; in fact,
324 for each package we define a variable bound to the package definition,
325 and export that variable from a module (@pxref{Package Modules}).
326 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
327 creating packages. For more information on package definitions,
328 @pxref{Defining Packages}.
330 Once a package definition is in place, stored in a file in the Guix
331 source tree, it can be tested using the @command{guix build} command
332 (@pxref{Invoking guix build}). For example, assuming the new package is
333 called @code{gnew}, you may run this command from the Guix build tree
334 (@pxref{Running Guix Before It Is Installed}):
337 ./pre-inst-env guix build gnew --keep-failed
340 Using @code{--keep-failed} makes it easier to debug build failures since
341 it provides access to the failed build tree. Another useful
342 command-line option when debugging is @code{--log-file}, to access the
345 If the package is unknown to the @command{guix} command, it may be that
346 the source file contains a syntax error, or lacks a @code{define-public}
347 clause to export the package variable. To figure it out, you may load
348 the module from Guile to get more information about the actual error:
351 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
354 Once your package builds correctly, please send us a patch
355 (@pxref{Submitting Patches}). Well, if you need help, we will be happy to
356 help you too. Once the patch is committed in the Guix repository, the
357 new package automatically gets built on the supported platforms by
358 @url{@value{SUBSTITUTE-SERVER}, our continuous integration system}.
361 Users can obtain the new package definition simply by running
362 @command{guix pull} (@pxref{Invoking guix pull}). When
363 @code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
364 package automatically downloads binaries from there
365 (@pxref{Substitutes}). The only place where human intervention is
366 needed is to review and apply the patch.
370 * Software Freedom:: What may go into the distribution.
371 * Package Naming:: What's in a name?
372 * Version Numbers:: When the name is not enough.
373 * Synopses and Descriptions:: Helping users find the right package.
374 * Python Modules:: A touch of British comedy.
375 * Perl Modules:: Little pearls.
376 * Java Packages:: Coffee break.
377 * Rust Crates:: Beware of oxidation.
378 * Fonts:: Fond of fonts.
381 @node Software Freedom
382 @subsection Software Freedom
384 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
385 @cindex free software
386 The GNU operating system has been developed so that users can have
387 freedom in their computing. GNU is @dfn{free software}, meaning that
388 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
389 essential freedoms}: to run the program, to study and change the program
390 in source code form, to redistribute exact copies, and to distribute
391 modified versions. Packages found in the GNU distribution provide only
392 software that conveys these four freedoms.
394 In addition, the GNU distribution follow the
395 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
396 software distribution guidelines}. Among other things, these guidelines
397 reject non-free firmware, recommendations of non-free software, and
398 discuss ways to deal with trademarks and patents.
400 Some otherwise free upstream package sources contain a small and optional
401 subset that violates the above guidelines, for instance because this subset
402 is itself non-free code. When that happens, the offending items are removed
403 with appropriate patches or code snippets in the @code{origin} form of the
404 package (@pxref{Defining Packages}). This way, @code{guix
405 build --source} returns the ``freed'' source rather than the unmodified
410 @subsection Package Naming
413 A package has actually two names associated with it:
414 First, there is the name of the @emph{Scheme variable}, the one following
415 @code{define-public}. By this name, the package can be made known in the
416 Scheme code, for instance as input to another package. Second, there is
417 the string in the @code{name} field of a package definition. This name
418 is used by package management commands such as
419 @command{guix package} and @command{guix build}.
421 Both are usually the same and correspond to the lowercase conversion of
422 the project name chosen upstream, with underscores replaced with
423 hyphens. For instance, GNUnet is available as @code{gnunet}, and
424 SDL_net as @code{sdl-net}.
426 We do not add @code{lib} prefixes for library packages, unless these are
427 already part of the official project name. But @pxref{Python
428 Modules} and @ref{Perl Modules} for special rules concerning modules for
429 the Python and Perl languages.
431 Font package names are handled differently, @pxref{Fonts}.
434 @node Version Numbers
435 @subsection Version Numbers
437 @cindex package version
438 We usually package only the latest version of a given free software
439 project. But sometimes, for instance for incompatible library versions,
440 two (or more) versions of the same package are needed. These require
441 different Scheme variable names. We use the name as defined
442 in @ref{Package Naming}
443 for the most recent version; previous versions use the same name, suffixed
444 by @code{-} and the smallest prefix of the version number that may
445 distinguish the two versions.
447 The name inside the package definition is the same for all versions of a
448 package and does not contain any version number.
450 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
458 (define-public gtk+-2
464 If we also wanted GTK+ 3.8.2, this would be packaged as
466 (define-public gtk+-3.8
473 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
474 @c for a discussion of what follows.
475 @cindex version number, for VCS snapshots
476 Occasionally, we package snapshots of upstream's version control system
477 (VCS) instead of formal releases. This should remain exceptional,
478 because it is up to upstream developers to clarify what the stable
479 release is. Yet, it is sometimes necessary. So, what should we put in
480 the @code{version} field?
482 Clearly, we need to make the commit identifier of the VCS snapshot
483 visible in the version string, but we also need to make sure that the
484 version string is monotonically increasing so that @command{guix package
485 --upgrade} can determine which version is newer. Since commit
486 identifiers, notably with Git, are not monotonically increasing, we add
487 a revision number that we increase each time we upgrade to a newer
488 snapshot. The resulting version string looks like this:
493 | | `-- upstream commit ID
495 | `--- Guix package revision
497 latest upstream version
500 It is a good idea to strip commit identifiers in the @code{version}
501 field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
502 aesthetics have a role to play here) as well as problems related to OS
503 limits such as the maximum shebang length (127 bytes for the Linux
504 kernel.) It is best to use the full commit identifiers in
505 @code{origin}s, though, to avoid ambiguities. A typical package
506 definition may look like this:
510 (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
511 (revision "1")) ;Guix package revision
513 (version (git-version "0.9" revision commit))
517 (url "git://example.org/my-package.git")
519 (sha256 (base32 "1mbikn@dots{}"))
520 (file-name (git-file-name name version))))
525 @node Synopses and Descriptions
526 @subsection Synopses and Descriptions
528 @cindex package description
529 @cindex package synopsis
530 As we have seen before, each package in GNU@tie{}Guix includes a
531 synopsis and a description (@pxref{Defining Packages}). Synopses and
532 descriptions are important: They are what @command{guix package
533 --search} searches, and a crucial piece of information to help users
534 determine whether a given package suits their needs. Consequently,
535 packagers should pay attention to what goes into them.
537 Synopses must start with a capital letter and must not end with a
538 period. They must not start with ``a'' or ``the'', which usually does
539 not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
540 tool that frobs files''. The synopsis should say what the package
541 is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
542 used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
543 matching a pattern''.
545 Keep in mind that the synopsis must be meaningful for a very wide
546 audience. For example, ``Manipulate alignments in the SAM format''
547 might make sense for a seasoned bioinformatics researcher, but might be
548 fairly unhelpful or even misleading to a non-specialized audience. It
549 is a good idea to come up with a synopsis that gives an idea of the
550 application domain of the package. In this example, this might give
551 something like ``Manipulate nucleotide sequence alignments'', which
552 hopefully gives the user a better idea of whether this is what they are
555 Descriptions should take between five and ten lines. Use full
556 sentences, and avoid using acronyms without first introducing them.
557 Please avoid marketing phrases such as ``world-leading'',
558 ``industrial-strength'', and ``next-generation'', and avoid superlatives
559 like ``the most advanced''---they are not helpful to users looking for a
560 package and may even sound suspicious. Instead, try to be factual,
561 mentioning use cases and features.
563 @cindex Texinfo markup, in package descriptions
564 Descriptions can include Texinfo markup, which is useful to introduce
565 ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
566 hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
567 should be careful when using some characters for example @samp{@@} and
568 curly braces which are the basic special characters in Texinfo
569 (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
570 such as @command{guix package --show} take care of rendering it
573 Synopses and descriptions are translated by volunteers
574 @uref{http://translationproject.org/domain/guix-packages.html, at the
575 Translation Project} so that as many users as possible can read them in
576 their native language. User interfaces search them and display them in
577 the language specified by the current locale.
579 To allow @command{xgettext} to extract them as translatable strings,
580 synopses and descriptions @emph{must be literal strings}. This means
581 that you cannot use @code{string-append} or @code{format} to construct
587 (synopsis "This is translatable")
588 (description (string-append "This is " "*not*" " translatable.")))
591 Translation is a lot of work so, as a packager, please pay even more
592 attention to your synopses and descriptions as every change may entail
593 additional work for translators. In order to help them, it is possible
594 to make recommendations or instructions visible to them by inserting
595 special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
599 ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
600 (description "ARandR is designed to provide a simple visual front end
601 for the X11 resize-and-rotate (RandR) extension. @dots{}")
606 @subsection Python Modules
609 We currently package Python 2 and Python 3, under the Scheme variable names
610 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
611 To avoid confusion and naming clashes with other programming languages, it
612 seems desirable that the name of a package for a Python module contains
613 the word @code{python}.
615 Some modules are compatible with only one version of Python, others with both.
616 If the package Foo compiles only with Python 3, we name it
617 @code{python-foo}; if it compiles only with Python 2, we name it
618 @code{python2-foo}. If it is compatible with both versions, we create two
619 packages with the corresponding names.
621 If a project already contains the word @code{python}, we drop this;
622 for instance, the module python-dateutil is packaged under the names
623 @code{python-dateutil} and @code{python2-dateutil}. If the project name
624 starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
627 @subsubsection Specifying Dependencies
628 @cindex inputs, for Python packages
630 Dependency information for Python packages is usually available in the
631 package source tree, with varying degrees of accuracy: in the
632 @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
634 Your mission, when writing a recipe for a Python package, is to map
635 these dependencies to the appropriate type of ``input'' (@pxref{package
636 Reference, inputs}). Although the @code{pypi} importer normally does a
637 good job (@pxref{Invoking guix import}), you may want to check the
638 following check list to determine which dependency goes where.
643 We currently package Python 2 with @code{setuptools} and @code{pip}
644 installed like Python 3.4 has per default. Thus you don't need to
645 specify either of these as an input. @command{guix lint} will warn you
649 Python dependencies required at run time go into
650 @code{propagated-inputs}. They are typically defined with the
651 @code{install_requires} keyword in @file{setup.py}, or in the
652 @file{requirements.txt} file.
655 Python packages required only at build time---e.g., those listed with
656 the @code{setup_requires} keyword in @file{setup.py}---or only for
657 testing---e.g., those in @code{tests_require}---go into
658 @code{native-inputs}. The rationale is that (1) they do not need to be
659 propagated because they are not needed at run time, and (2) in a
660 cross-compilation context, it's the ``native'' input that we'd want.
662 Examples are the @code{pytest}, @code{mock}, and @code{nose} test
663 frameworks. Of course if any of these packages is also required at
664 run-time, it needs to go to @code{propagated-inputs}.
667 Anything that does not fall in the previous categories goes to
668 @code{inputs}, for example programs or C libraries required for building
669 Python packages containing C extensions.
672 If a Python package has optional dependencies (@code{extras_require}),
673 it is up to you to decide whether to add them or not, based on their
674 usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
681 @subsection Perl Modules
684 Perl programs standing for themselves are named as any other package,
685 using the lowercase upstream name.
686 For Perl packages containing a single class, we use the lowercase class name,
687 replace all occurrences of @code{::} by dashes and prepend the prefix
689 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
690 Modules containing several classes keep their lowercase upstream name and
691 are also prepended by @code{perl-}. Such modules tend to have the word
692 @code{perl} somewhere in their name, which gets dropped in favor of the
693 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
697 @subsection Java Packages
700 Java programs standing for themselves are named as any other package,
701 using the lowercase upstream name.
703 To avoid confusion and naming clashes with other programming languages,
704 it is desirable that the name of a package for a Java package is
705 prefixed with @code{java-}. If a project already contains the word
706 @code{java}, we drop this; for instance, the package @code{ngsjava} is
707 packaged under the name @code{java-ngs}.
709 For Java packages containing a single class or a small class hierarchy,
710 we use the lowercase class name, replace all occurrences of @code{.} by
711 dashes and prepend the prefix @code{java-}. So the class
712 @code{apache.commons.cli} becomes package
713 @code{java-apache-commons-cli}.
717 @subsection Rust Crates
720 Rust programs standing for themselves are named as any other package, using the
721 lowercase upstream name.
723 To prevent namespace collisions we prefix all other Rust packages with the
724 @code{rust-} prefix. The name should be changed to lowercase as appropriate and
725 dashes should remain in place.
727 In the rust ecosystem it is common for multiple incompatible versions of a
728 package to be used at any given time, so all packages should have a versioned
729 suffix. If a package has passed version 1.0.0 then just the major version
730 number is sufficient (e.g.@: @code{rust-clap-2}), otherwise the version suffix
731 should contain both the major and minor version (e.g.@: @code{rust-rand-0.6}).
733 Because of the difficulty in reusing rust packages as pre-compiled inputs for
734 other packages the Cargo build system (@pxref{Build Systems,
735 @code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
736 @code{cargo-development-inputs} keywords as build system arguments. It would be
737 helpful to think of these as similar to @code{propagated-inputs} and
738 @code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies}
739 should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
740 @code{#:cargo-development-inputs}. If a Rust package links to other libraries
741 then the standard placement in @code{inputs} and the like should be used.
743 Care should be taken to ensure the correct version of dependencies are used; to
744 this end we try to refrain from skipping the tests or using @code{#:skip-build?}
745 when possible. Of course this is not always possible, as the package may be
746 developed for a different Operating System, depend on features from the Nightly
747 Rust compiler, or the test suite may have atrophied since it was released.
754 For fonts that are in general not installed by a user for typesetting
755 purposes, or that are distributed as part of a larger software package,
756 we rely on the general packaging rules for software; for instance, this
757 applies to the fonts delivered as part of the X.Org system or fonts that
758 are part of TeX Live.
760 To make it easier for a user to search for fonts, names for other packages
761 containing only fonts are constructed as follows, independently of the
762 upstream package name.
764 The name of a package containing only one font family starts with
765 @code{font-}; it is followed by the foundry name and a dash @code{-}
766 if the foundry is known, and the font family name, in which spaces are
767 replaced by dashes (and as usual, all upper case letters are transformed
769 For example, the Gentium font family by SIL is packaged under the name
770 @code{font-sil-gentium}.
772 For a package containing several font families, the name of the collection
773 is used in the place of the font family name.
774 For instance, the Liberation fonts consist of three families,
775 Liberation Sans, Liberation Serif and Liberation Mono.
776 These could be packaged separately under the names
777 @code{font-liberation-sans} and so on; but as they are distributed together
778 under a common name, we prefer to package them together as
779 @code{font-liberation}.
781 In the case where several formats of the same font family or font collection
782 are packaged separately, a short form of the format, prepended by a dash,
783 is added to the package name. We use @code{-ttf} for TrueType fonts,
784 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
789 @section Coding Style
791 In general our code follows the GNU Coding Standards (@pxref{Top,,,
792 standards, GNU Coding Standards}). However, they do not say much about
793 Scheme, so here are some additional rules.
796 * Programming Paradigm:: How to compose your elements.
797 * Modules:: Where to store your code?
798 * Data Types and Pattern Matching:: Implementing data structures.
799 * Formatting Code:: Writing conventions.
802 @node Programming Paradigm
803 @subsection Programming Paradigm
805 Scheme code in Guix is written in a purely functional style. One
806 exception is code that involves input/output, and procedures that
807 implement low-level concepts, such as the @code{memoize} procedure.
812 Guile modules that are meant to be used on the builder side must live in
813 the @code{(guix build @dots{})} name space. They must not refer to
814 other Guix or GNU modules. However, it is OK for a ``host-side'' module
815 to use a build-side module.
817 Modules that deal with the broader GNU system should be in the
818 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
820 @node Data Types and Pattern Matching
821 @subsection Data Types and Pattern Matching
823 The tendency in classical Lisp is to use lists to represent everything,
824 and then to browse them ``by hand'' using @code{car}, @code{cdr},
825 @code{cadr}, and co. There are several problems with that style,
826 notably the fact that it is hard to read, error-prone, and a hindrance
827 to proper type error reports.
829 Guix code should define appropriate data types (for instance, using
830 @code{define-record-type*}) rather than abuse lists. In addition, it
831 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
832 especially when matching lists.
834 @node Formatting Code
835 @subsection Formatting Code
837 @cindex formatting code
839 When writing Scheme code, we follow common wisdom among Scheme
840 programmers. In general, we follow the
841 @url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
842 Style Rules}. This document happens to describe the conventions mostly
843 used in Guile’s code too. It is very thoughtful and well written, so
846 Some special forms introduced in Guix, such as the @code{substitute*}
847 macro, have special indentation rules. These are defined in the
848 @file{.dir-locals.el} file, which Emacs automatically uses. Also note
849 that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
850 highlights Guix code properly (@pxref{Development,,, emacs-guix, The
851 Emacs-Guix Reference Manual}).
853 @cindex indentation, of code
854 @cindex formatting, of code
855 If you do not use Emacs, please make sure to let your editor knows these
856 rules. To automatically indent a package definition, you can also run:
859 ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
863 This automatically indents the definition of @var{package} in
864 @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
865 indent a whole file, omit the second argument:
868 ./etc/indent-code.el gnu/services/@var{file}.scm
871 @cindex Vim, Scheme code editing
872 If you are editing code with Vim, we recommend that you run @code{:set
873 autoindent} so that your code is automatically indented as you type.
875 @uref{https://www.vim.org/scripts/script.php?script_id=3998,
876 @code{paredit.vim}} may help you deal with all these parentheses.
878 We require all top-level procedures to carry a docstring. This
879 requirement can be relaxed for simple private procedures in the
880 @code{(guix build @dots{})} name space, though.
882 Procedures should not have more than four positional parameters. Use
883 keyword parameters for procedures that take more than four parameters.
886 @node Submitting Patches
887 @section Submitting Patches
889 Development is done using the Git distributed version control system.
890 Thus, access to the repository is not strictly necessary. We welcome
891 contributions in the form of patches as produced by @code{git
892 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
893 Seasoned Guix developers may also want to look at the section on commit
894 access (@pxref{Commit Access}).
896 This mailing list is backed by a Debbugs instance, which allows us to
897 keep track of submissions (@pxref{Tracking Bugs and Patches}). Each
898 message sent to that mailing list gets a new tracking number assigned;
899 people can then follow up on the submission by sending email to
900 @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
901 number (@pxref{Sending a Patch Series}).
903 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
904 standards, GNU Coding Standards}); you can check the commit history for
907 Before submitting a patch that adds or modifies a package definition,
908 please run through this check list:
912 If the authors of the packaged software provide a cryptographic
913 signature for the release tarball, make an effort to verify the
914 authenticity of the archive. For a detached GPG signature file this
915 would be done with the @code{gpg --verify} command.
918 Take some time to provide an adequate synopsis and description for the
919 package. @xref{Synopses and Descriptions}, for some guidelines.
922 Run @code{guix lint @var{package}}, where @var{package} is the
923 name of the new or modified package, and fix any errors it reports
924 (@pxref{Invoking guix lint}).
927 Make sure the package builds on your platform, using @code{guix build
931 We recommend you also try building the package on other supported
932 platforms. As you may not have access to actual hardware platforms, we
933 recommend using the @code{qemu-binfmt-service-type} to emulate them. In
934 order to enable it, add the following service to the list of services in
935 your @code{operating-system} configuration:
938 (service qemu-binfmt-service-type
939 (qemu-binfmt-configuration
940 (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
944 Then reconfigure your system.
946 You can then build packages for different platforms by specifying the
947 @code{--system} option. For example, to build the "hello" package for
948 the armhf, aarch64, or mips64 architectures, you would run the following
949 commands, respectively:
951 guix build --system=armhf-linux --rounds=2 hello
952 guix build --system=aarch64-linux --rounds=2 hello
953 guix build --system=mips64el-linux --rounds=2 hello
958 Make sure the package does not use bundled copies of software already
959 available as separate packages.
961 Sometimes, packages include copies of the source code of their
962 dependencies as a convenience for users. However, as a distribution, we
963 want to make sure that such packages end up using the copy we already
964 have in the distribution, if there is one. This improves resource usage
965 (the dependency is built and stored only once), and allows the
966 distribution to make transverse changes such as applying security
967 updates for a given software package in a single place and have them
968 affect the whole system---something that bundled copies prevent.
971 Take a look at the profile reported by @command{guix size}
972 (@pxref{Invoking guix size}). This will allow you to notice references
973 to other packages unwillingly retained. It may also help determine
974 whether to split the package (@pxref{Packages with Multiple Outputs}),
975 and which optional dependencies should be used. In particular, avoid adding
976 @code{texlive} as a dependency: because of its extreme size, use
977 @code{texlive-tiny} or @code{texlive-union} instead.
980 For important changes, check that dependent package (if applicable) are
981 not affected by the change; @code{guix refresh --list-dependent
982 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
984 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
985 @cindex branching strategy
986 @cindex rebuild scheduling strategy
987 Depending on the number of dependent packages and thus the amount of
988 rebuilding induced, commits go to different branches, along these lines:
991 @item 300 dependent packages or less
992 @code{master} branch (non-disruptive changes).
994 @item between 300 and 1,200 dependent packages
995 @code{staging} branch (non-disruptive changes). This branch is intended
996 to be merged in @code{master} every 3 weeks or so. Topical changes
997 (e.g., an update of the GNOME stack) can instead go to a specific branch
998 (say, @code{gnome-updates}).
1000 @item more than 1,200 dependent packages
1001 @code{core-updates} branch (may include major and potentially disruptive
1002 changes). This branch is intended to be merged in @code{master} every
1006 All these branches are @uref{@value{SUBSTITUTE-SERVER},
1007 tracked by our build farm} and merged into @code{master} once
1008 everything has been successfully built. This allows us to fix issues
1009 before they hit users, and to reduce the window during which pre-built
1010 binaries are not available.
1012 Generally, branches other than @code{master} are considered
1013 @emph{frozen} if there has been a recent evaluation, or there is a
1014 corresponding @code{-next} branch. Please ask on the mailing list or
1015 IRC if unsure where to place a patch.
1016 @c TODO: It would be good with badges on the website that tracks these
1017 @c branches. Or maybe even a status page.
1020 @cindex determinism, of build processes
1021 @cindex reproducible builds, checking
1022 Check whether the package's build process is deterministic. This
1023 typically means checking whether an independent build of the package
1024 yields the exact same result that you obtained, bit for bit.
1026 A simple way to do that is by building the same package several times in
1027 a row on your machine (@pxref{Invoking guix build}):
1030 guix build --rounds=2 my-package
1033 This is enough to catch a class of common non-determinism issues, such
1034 as timestamps or randomly-generated output in the build result.
1036 Another option is to use @command{guix challenge} (@pxref{Invoking guix
1037 challenge}). You may run it once the package has been committed and
1038 built by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
1039 result as you did. Better yet: Find another machine that can build it
1040 and run @command{guix publish}. Since the remote build machine is
1041 likely different from yours, this can catch non-determinism issues
1042 related to the hardware---e.g., use of different instruction set
1043 extensions---or to the operating system kernel---e.g., reliance on
1044 @code{uname} or @file{/proc} files.
1047 When writing documentation, please use gender-neutral wording when
1048 referring to people, such as
1049 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
1050 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
1053 Verify that your patch contains only one set of related changes.
1054 Bundling unrelated changes together makes reviewing harder and slower.
1056 Examples of unrelated changes include the addition of several packages,
1057 or a package update along with fixes to that package.
1060 Please follow our code formatting rules, possibly running the
1061 @command{etc/indent-code.el} script to do that automatically for you
1062 (@pxref{Formatting Code}).
1065 When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
1066 Use reliable URLs, not generated ones. For instance, GitHub archives are not
1067 necessarily identical from one generation to the next, so in this case it's
1068 often better to clone the repository. Don't use the @command{name} field in
1069 the URL: it is not very useful and if the name changes, the URL will probably
1073 Check if Guix builds (@pxref{Building from Git}) and address the
1074 warnings, especially those about use of undefined symbols.
1077 Make sure your changes do not break Guix and simulate a @code{guix pull} with:
1079 guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
1084 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
1085 a subject. You may use your email client or the @command{git
1086 send-email} command (@pxref{Sending a Patch Series}). We prefer to get
1087 patches in plain text messages, either inline or as MIME attachments.
1088 You are advised to pay attention if your email client changes anything
1089 like line breaks or indentation which could potentially break the
1092 When a bug is resolved, please close the thread by sending an email to
1093 @email{@var{NNN}-done@@debbugs.gnu.org}.
1095 @unnumberedsubsec Sending a Patch Series
1096 @anchor{Sending a Patch Series}
1097 @cindex patch series
1098 @cindex @code{git send-email}
1099 @cindex @code{git-send-email}
1101 When sending a patch series (e.g., using @code{git send-email}), please
1102 first send one message to @email{guix-patches@@gnu.org}, and then send
1103 subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
1104 they are kept together. See
1105 @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
1106 for more information. You can install @command{git send-email} with
1107 @command{guix install git:send-email}.
1108 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
1110 @node Tracking Bugs and Patches
1111 @section Tracking Bugs and Patches
1113 @cindex bug reports, tracking
1114 @cindex patch submissions, tracking
1115 @cindex issue tracking
1116 @cindex Debbugs, issue tracking system
1117 Bug reports and patch submissions are currently tracked using the
1118 Debbugs instance at @uref{https://bugs.gnu.org}. Bug reports are filed
1119 against the @code{guix} ``package'' (in Debbugs parlance), by sending
1120 email to @email{bug-guix@@gnu.org}, while patch submissions are filed
1121 against the @code{guix-patches} package by sending email to
1122 @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
1124 A web interface (actually @emph{two} web interfaces!) are available to
1129 @url{https://bugs.gnu.org/guix} lists bug reports;
1131 @url{https://bugs.gnu.org/guix-patches} lists patch submissions.
1134 You can also access both of these @i{via} the (nicer)
1135 @url{https://issues.guix.gnu.org} interface@footnote{The web interface
1136 at @url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
1137 software written in Guile, and you can help! See
1138 @url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.}. To view
1139 discussions related to issue number @var{n}, go to
1140 @indicateurl{https://issues.guix.gnu.org/issue/@var{n}} or
1141 @indicateurl{https://bugs.gnu.org/@var{n}}.
1143 If you use Emacs, you may find it more convenient to interact with
1144 issues using @file{debbugs.el}, which you can install with:
1147 guix install emacs-debbugs
1150 For example, to list all open issues on @code{guix-patches}, hit:
1153 @kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
1156 @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
1160 @section Commit Access
1162 @cindex commit access, for developers
1163 For frequent contributors, having write access to the repository is
1164 convenient. When you deem it necessary, consider applying for commit
1165 access by following these steps:
1169 Find three committers who would vouch for you. You can view the list of
1171 @url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Each
1172 of them should email a statement to @email{guix-maintainers@@gnu.org} (a
1173 private alias for the collective of maintainers), signed with their
1176 Committers are expected to have had some interactions with you as a
1177 contributor and to be able to judge whether you are sufficiently
1178 familiar with the project's practices. It is @emph{not} a judgment on
1179 the value of your work, so a refusal should rather be interpreted as
1180 ``let's try again later''.
1183 Send @email{guix-maintainers@@gnu.org} a message stating your intent,
1184 listing the three committers who support your application, signed with
1185 the OpenPGP key you will use to sign commits, and giving its fingerprint
1186 (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
1187 introduction to public-key cryptography with GnuPG.
1190 Maintainers ultimately decide whether to grant you commit access,
1191 usually following your referrals' recommendation.
1194 If and once you've been given access, please send a message to
1195 @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
1196 you will use to sign commits (do that before pushing your first commit).
1197 That way, everyone can notice and ensure you control that OpenPGP key.
1199 @c TODO: Add note about adding the fingerprint to the list of authorized
1200 @c keys once that has stabilized.
1203 Make sure to read the rest of this section and... profit!
1207 Maintainers are happy to give commit access to people who have been
1208 contributing for some time and have a track record---don't be shy and
1209 don't underestimate your work!
1211 However, note that the project is working towards a more automated patch
1212 review and merging system, which, as a consequence, may lead us to have
1213 fewer people with commit access to the main repository. Stay tuned!
1216 If you get commit access, please make sure to follow
1217 the policy below (discussions of the policy can take place on
1218 @email{guix-devel@@gnu.org}).
1220 Non-trivial patches should always be posted to
1221 @email{guix-patches@@gnu.org} (trivial patches include fixing typos,
1222 etc.). This mailing list fills the patch-tracking database
1223 (@pxref{Tracking Bugs and Patches}).
1225 For patches that just add a new package, and a simple one, it's OK to
1226 commit, if you're confident (which means you successfully built it in a
1227 chroot setup, and have done a reasonable copyright and license
1228 auditing). Likewise for package upgrades, except upgrades that trigger
1229 a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a
1230 mailing list for commit notifications (@email{guix-commits@@gnu.org}),
1231 so people can notice. Before pushing your changes, make sure to run
1232 @code{git pull --rebase}.
1234 All commits that are pushed to the central repository on Savannah must
1235 be signed with an OpenPGP key, and the public key should be uploaded to
1236 your user account on Savannah and to public key servers, such as
1237 @code{keys.openpgp.org}. To configure Git to automatically sign
1241 git config commit.gpgsign true
1242 git config user.signingkey CABBA6EA1DC0FF33
1245 You can prevent yourself from accidentally pushing unsigned commits to
1246 Savannah by using the pre-push Git hook called located at
1247 @file{etc/git/pre-push}:
1250 cp etc/git/pre-push .git/hooks/pre-push
1253 When pushing a commit on behalf of somebody else, please add a
1254 @code{Signed-off-by} line at the end of the commit log message---e.g.,
1255 with @command{git am --signoff}. This improves tracking of who did
1258 For anything else, please post to @email{guix-patches@@gnu.org} and
1259 leave time for a review, without committing anything (@pxref{Submitting
1260 Patches}). If you didn’t receive any reply after two weeks, and if
1261 you're confident, it's OK to commit.
1263 That last part is subject to being adjusted, allowing individuals to commit
1264 directly on non-controversial changes on parts they’re familiar with.
1266 One last thing: the project keeps moving forward because committers not
1267 only push their own awesome changes, but also offer some of their time
1268 @emph{reviewing} and pushing other people's changes. As a committer,
1269 you're welcome to use your expertise and commit rights to help other