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{http://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.
278 @node Packaging Guidelines
279 @section Packaging Guidelines
281 @cindex packages, creating
282 The GNU distribution is nascent and may well lack some of your favorite
283 packages. This section describes how you can help make the distribution
286 Free software packages are usually distributed in the form of
287 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
288 all the source files. Adding a package to the distribution means
289 essentially two things: adding a @dfn{recipe} that describes how to
290 build the package, including a list of other packages required to build
291 it, and adding @dfn{package metadata} along with that recipe, such as a
292 description and licensing information.
294 In Guix all this information is embodied in @dfn{package definitions}.
295 Package definitions provide a high-level view of the package. They are
296 written using the syntax of the Scheme programming language; in fact,
297 for each package we define a variable bound to the package definition,
298 and export that variable from a module (@pxref{Package Modules}).
299 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
300 creating packages. For more information on package definitions,
301 @pxref{Defining Packages}.
303 Once a package definition is in place, stored in a file in the Guix
304 source tree, it can be tested using the @command{guix build} command
305 (@pxref{Invoking guix build}). For example, assuming the new package is
306 called @code{gnew}, you may run this command from the Guix build tree
307 (@pxref{Running Guix Before It Is Installed}):
310 ./pre-inst-env guix build gnew --keep-failed
313 Using @code{--keep-failed} makes it easier to debug build failures since
314 it provides access to the failed build tree. Another useful
315 command-line option when debugging is @code{--log-file}, to access the
318 If the package is unknown to the @command{guix} command, it may be that
319 the source file contains a syntax error, or lacks a @code{define-public}
320 clause to export the package variable. To figure it out, you may load
321 the module from Guile to get more information about the actual error:
324 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
327 Once your package builds correctly, please send us a patch
328 (@pxref{Submitting Patches}). Well, if you need help, we will be happy to
329 help you too. Once the patch is committed in the Guix repository, the
330 new package automatically gets built on the supported platforms by
331 @url{@value{SUBSTITUTE-SERVER}, our continuous integration system}.
334 Users can obtain the new package definition simply by running
335 @command{guix pull} (@pxref{Invoking guix pull}). When
336 @code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
337 package automatically downloads binaries from there
338 (@pxref{Substitutes}). The only place where human intervention is
339 needed is to review and apply the patch.
343 * Software Freedom:: What may go into the distribution.
344 * Package Naming:: What's in a name?
345 * Version Numbers:: When the name is not enough.
346 * Synopses and Descriptions:: Helping users find the right package.
347 * Python Modules:: A touch of British comedy.
348 * Perl Modules:: Little pearls.
349 * Java Packages:: Coffee break.
350 * Fonts:: Fond of fonts.
353 @node Software Freedom
354 @subsection Software Freedom
356 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
357 @cindex free software
358 The GNU operating system has been developed so that users can have
359 freedom in their computing. GNU is @dfn{free software}, meaning that
360 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
361 essential freedoms}: to run the program, to study and change the program
362 in source code form, to redistribute exact copies, and to distribute
363 modified versions. Packages found in the GNU distribution provide only
364 software that conveys these four freedoms.
366 In addition, the GNU distribution follow the
367 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
368 software distribution guidelines}. Among other things, these guidelines
369 reject non-free firmware, recommendations of non-free software, and
370 discuss ways to deal with trademarks and patents.
372 Some otherwise free upstream package sources contain a small and optional
373 subset that violates the above guidelines, for instance because this subset
374 is itself non-free code. When that happens, the offending items are removed
375 with appropriate patches or code snippets in the @code{origin} form of the
376 package (@pxref{Defining Packages}). This way, @code{guix
377 build --source} returns the ``freed'' source rather than the unmodified
382 @subsection Package Naming
385 A package has actually two names associated with it:
386 First, there is the name of the @emph{Scheme variable}, the one following
387 @code{define-public}. By this name, the package can be made known in the
388 Scheme code, for instance as input to another package. Second, there is
389 the string in the @code{name} field of a package definition. This name
390 is used by package management commands such as
391 @command{guix package} and @command{guix build}.
393 Both are usually the same and correspond to the lowercase conversion of
394 the project name chosen upstream, with underscores replaced with
395 hyphens. For instance, GNUnet is available as @code{gnunet}, and
396 SDL_net as @code{sdl-net}.
398 We do not add @code{lib} prefixes for library packages, unless these are
399 already part of the official project name. But @pxref{Python
400 Modules} and @ref{Perl Modules} for special rules concerning modules for
401 the Python and Perl languages.
403 Font package names are handled differently, @pxref{Fonts}.
406 @node Version Numbers
407 @subsection Version Numbers
409 @cindex package version
410 We usually package only the latest version of a given free software
411 project. But sometimes, for instance for incompatible library versions,
412 two (or more) versions of the same package are needed. These require
413 different Scheme variable names. We use the name as defined
414 in @ref{Package Naming}
415 for the most recent version; previous versions use the same name, suffixed
416 by @code{-} and the smallest prefix of the version number that may
417 distinguish the two versions.
419 The name inside the package definition is the same for all versions of a
420 package and does not contain any version number.
422 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
430 (define-public gtk+-2
436 If we also wanted GTK+ 3.8.2, this would be packaged as
438 (define-public gtk+-3.8
445 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
446 @c for a discussion of what follows.
447 @cindex version number, for VCS snapshots
448 Occasionally, we package snapshots of upstream's version control system
449 (VCS) instead of formal releases. This should remain exceptional,
450 because it is up to upstream developers to clarify what the stable
451 release is. Yet, it is sometimes necessary. So, what should we put in
452 the @code{version} field?
454 Clearly, we need to make the commit identifier of the VCS snapshot
455 visible in the version string, but we also need to make sure that the
456 version string is monotonically increasing so that @command{guix package
457 --upgrade} can determine which version is newer. Since commit
458 identifiers, notably with Git, are not monotonically increasing, we add
459 a revision number that we increase each time we upgrade to a newer
460 snapshot. The resulting version string looks like this:
465 | | `-- upstream commit ID
467 | `--- Guix package revision
469 latest upstream version
472 It is a good idea to strip commit identifiers in the @code{version}
473 field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
474 aesthetics have a role to play here) as well as problems related to OS
475 limits such as the maximum shebang length (127 bytes for the Linux
476 kernel.) It is best to use the full commit identifiers in
477 @code{origin}s, though, to avoid ambiguities. A typical package
478 definition may look like this:
482 (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
483 (revision "1")) ;Guix package revision
485 (version (git-version "0.9" revision commit))
489 (url "git://example.org/my-package.git")
491 (sha256 (base32 "1mbikn@dots{}"))
492 (file-name (git-file-name name version))))
497 @node Synopses and Descriptions
498 @subsection Synopses and Descriptions
500 @cindex package description
501 @cindex package synopsis
502 As we have seen before, each package in GNU@tie{}Guix includes a
503 synopsis and a description (@pxref{Defining Packages}). Synopses and
504 descriptions are important: They are what @command{guix package
505 --search} searches, and a crucial piece of information to help users
506 determine whether a given package suits their needs. Consequently,
507 packagers should pay attention to what goes into them.
509 Synopses must start with a capital letter and must not end with a
510 period. They must not start with ``a'' or ``the'', which usually does
511 not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
512 tool that frobs files''. The synopsis should say what the package
513 is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
514 used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
515 matching a pattern''.
517 Keep in mind that the synopsis must be meaningful for a very wide
518 audience. For example, ``Manipulate alignments in the SAM format''
519 might make sense for a seasoned bioinformatics researcher, but might be
520 fairly unhelpful or even misleading to a non-specialized audience. It
521 is a good idea to come up with a synopsis that gives an idea of the
522 application domain of the package. In this example, this might give
523 something like ``Manipulate nucleotide sequence alignments'', which
524 hopefully gives the user a better idea of whether this is what they are
527 Descriptions should take between five and ten lines. Use full
528 sentences, and avoid using acronyms without first introducing them.
529 Please avoid marketing phrases such as ``world-leading'',
530 ``industrial-strength'', and ``next-generation'', and avoid superlatives
531 like ``the most advanced''---they are not helpful to users looking for a
532 package and may even sound suspicious. Instead, try to be factual,
533 mentioning use cases and features.
535 @cindex Texinfo markup, in package descriptions
536 Descriptions can include Texinfo markup, which is useful to introduce
537 ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
538 hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
539 should be careful when using some characters for example @samp{@@} and
540 curly braces which are the basic special characters in Texinfo
541 (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
542 such as @command{guix package --show} take care of rendering it
545 Synopses and descriptions are translated by volunteers
546 @uref{http://translationproject.org/domain/guix-packages.html, at the
547 Translation Project} so that as many users as possible can read them in
548 their native language. User interfaces search them and display them in
549 the language specified by the current locale.
551 To allow @command{xgettext} to extract them as translatable strings,
552 synopses and descriptions @emph{must be literal strings}. This means
553 that you cannot use @code{string-append} or @code{format} to construct
559 (synopsis "This is translatable")
560 (description (string-append "This is " "*not*" " translatable.")))
563 Translation is a lot of work so, as a packager, please pay even more
564 attention to your synopses and descriptions as every change may entail
565 additional work for translators. In order to help them, it is possible
566 to make recommendations or instructions visible to them by inserting
567 special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
571 ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
572 (description "ARandR is designed to provide a simple visual front end
573 for the X11 resize-and-rotate (RandR) extension. @dots{}")
578 @subsection Python Modules
581 We currently package Python 2 and Python 3, under the Scheme variable names
582 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
583 To avoid confusion and naming clashes with other programming languages, it
584 seems desirable that the name of a package for a Python module contains
585 the word @code{python}.
587 Some modules are compatible with only one version of Python, others with both.
588 If the package Foo compiles only with Python 3, we name it
589 @code{python-foo}; if it compiles only with Python 2, we name it
590 @code{python2-foo}. If it is compatible with both versions, we create two
591 packages with the corresponding names.
593 If a project already contains the word @code{python}, we drop this;
594 for instance, the module python-dateutil is packaged under the names
595 @code{python-dateutil} and @code{python2-dateutil}. If the project name
596 starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
599 @subsubsection Specifying Dependencies
600 @cindex inputs, for Python packages
602 Dependency information for Python packages is usually available in the
603 package source tree, with varying degrees of accuracy: in the
604 @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
606 Your mission, when writing a recipe for a Python package, is to map
607 these dependencies to the appropriate type of ``input'' (@pxref{package
608 Reference, inputs}). Although the @code{pypi} importer normally does a
609 good job (@pxref{Invoking guix import}), you may want to check the
610 following check list to determine which dependency goes where.
615 We currently package Python 2 with @code{setuptools} and @code{pip}
616 installed like Python 3.4 has per default. Thus you don't need to
617 specify either of these as an input. @command{guix lint} will warn you
621 Python dependencies required at run time go into
622 @code{propagated-inputs}. They are typically defined with the
623 @code{install_requires} keyword in @file{setup.py}, or in the
624 @file{requirements.txt} file.
627 Python packages required only at build time---e.g., those listed with
628 the @code{setup_requires} keyword in @file{setup.py}---or only for
629 testing---e.g., those in @code{tests_require}---go into
630 @code{native-inputs}. The rationale is that (1) they do not need to be
631 propagated because they are not needed at run time, and (2) in a
632 cross-compilation context, it's the ``native'' input that we'd want.
634 Examples are the @code{pytest}, @code{mock}, and @code{nose} test
635 frameworks. Of course if any of these packages is also required at
636 run-time, it needs to go to @code{propagated-inputs}.
639 Anything that does not fall in the previous categories goes to
640 @code{inputs}, for example programs or C libraries required for building
641 Python packages containing C extensions.
644 If a Python package has optional dependencies (@code{extras_require}),
645 it is up to you to decide whether to add them or not, based on their
646 usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
653 @subsection Perl Modules
656 Perl programs standing for themselves are named as any other package,
657 using the lowercase upstream name.
658 For Perl packages containing a single class, we use the lowercase class name,
659 replace all occurrences of @code{::} by dashes and prepend the prefix
661 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
662 Modules containing several classes keep their lowercase upstream name and
663 are also prepended by @code{perl-}. Such modules tend to have the word
664 @code{perl} somewhere in their name, which gets dropped in favor of the
665 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
669 @subsection Java Packages
672 Java programs standing for themselves are named as any other package,
673 using the lowercase upstream name.
675 To avoid confusion and naming clashes with other programming languages,
676 it is desirable that the name of a package for a Java package is
677 prefixed with @code{java-}. If a project already contains the word
678 @code{java}, we drop this; for instance, the package @code{ngsjava} is
679 packaged under the name @code{java-ngs}.
681 For Java packages containing a single class or a small class hierarchy,
682 we use the lowercase class name, replace all occurrences of @code{.} by
683 dashes and prepend the prefix @code{java-}. So the class
684 @code{apache.commons.cli} becomes package
685 @code{java-apache-commons-cli}.
692 For fonts that are in general not installed by a user for typesetting
693 purposes, or that are distributed as part of a larger software package,
694 we rely on the general packaging rules for software; for instance, this
695 applies to the fonts delivered as part of the X.Org system or fonts that
696 are part of TeX Live.
698 To make it easier for a user to search for fonts, names for other packages
699 containing only fonts are constructed as follows, independently of the
700 upstream package name.
702 The name of a package containing only one font family starts with
703 @code{font-}; it is followed by the foundry name and a dash @code{-}
704 if the foundry is known, and the font family name, in which spaces are
705 replaced by dashes (and as usual, all upper case letters are transformed
707 For example, the Gentium font family by SIL is packaged under the name
708 @code{font-sil-gentium}.
710 For a package containing several font families, the name of the collection
711 is used in the place of the font family name.
712 For instance, the Liberation fonts consist of three families,
713 Liberation Sans, Liberation Serif and Liberation Mono.
714 These could be packaged separately under the names
715 @code{font-liberation-sans} and so on; but as they are distributed together
716 under a common name, we prefer to package them together as
717 @code{font-liberation}.
719 In the case where several formats of the same font family or font collection
720 are packaged separately, a short form of the format, prepended by a dash,
721 is added to the package name. We use @code{-ttf} for TrueType fonts,
722 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
727 @section Coding Style
729 In general our code follows the GNU Coding Standards (@pxref{Top,,,
730 standards, GNU Coding Standards}). However, they do not say much about
731 Scheme, so here are some additional rules.
734 * Programming Paradigm:: How to compose your elements.
735 * Modules:: Where to store your code?
736 * Data Types and Pattern Matching:: Implementing data structures.
737 * Formatting Code:: Writing conventions.
740 @node Programming Paradigm
741 @subsection Programming Paradigm
743 Scheme code in Guix is written in a purely functional style. One
744 exception is code that involves input/output, and procedures that
745 implement low-level concepts, such as the @code{memoize} procedure.
750 Guile modules that are meant to be used on the builder side must live in
751 the @code{(guix build @dots{})} name space. They must not refer to
752 other Guix or GNU modules. However, it is OK for a ``host-side'' module
753 to use a build-side module.
755 Modules that deal with the broader GNU system should be in the
756 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
758 @node Data Types and Pattern Matching
759 @subsection Data Types and Pattern Matching
761 The tendency in classical Lisp is to use lists to represent everything,
762 and then to browse them ``by hand'' using @code{car}, @code{cdr},
763 @code{cadr}, and co. There are several problems with that style,
764 notably the fact that it is hard to read, error-prone, and a hindrance
765 to proper type error reports.
767 Guix code should define appropriate data types (for instance, using
768 @code{define-record-type*}) rather than abuse lists. In addition, it
769 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
770 especially when matching lists.
772 @node Formatting Code
773 @subsection Formatting Code
775 @cindex formatting code
777 When writing Scheme code, we follow common wisdom among Scheme
778 programmers. In general, we follow the
779 @url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
780 Style Rules}. This document happens to describe the conventions mostly
781 used in Guile’s code too. It is very thoughtful and well written, so
784 Some special forms introduced in Guix, such as the @code{substitute*}
785 macro, have special indentation rules. These are defined in the
786 @file{.dir-locals.el} file, which Emacs automatically uses. Also note
787 that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
788 highlights Guix code properly (@pxref{Development,,, emacs-guix, The
789 Emacs-Guix Reference Manual}).
791 @cindex indentation, of code
792 @cindex formatting, of code
793 If you do not use Emacs, please make sure to let your editor knows these
794 rules. To automatically indent a package definition, you can also run:
797 ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
801 This automatically indents the definition of @var{package} in
802 @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
803 indent a whole file, omit the second argument:
806 ./etc/indent-code.el gnu/services/@var{file}.scm
809 @cindex Vim, Scheme code editing
810 If you are editing code with Vim, we recommend that you run @code{:set
811 autoindent} so that your code is automatically indented as you type.
813 @uref{https://www.vim.org/scripts/script.php?script_id=3998,
814 @code{paredit.vim}} may help you deal with all these parentheses.
816 We require all top-level procedures to carry a docstring. This
817 requirement can be relaxed for simple private procedures in the
818 @code{(guix build @dots{})} name space, though.
820 Procedures should not have more than four positional parameters. Use
821 keyword parameters for procedures that take more than four parameters.
824 @node Submitting Patches
825 @section Submitting Patches
827 Development is done using the Git distributed version control system.
828 Thus, access to the repository is not strictly necessary. We welcome
829 contributions in the form of patches as produced by @code{git
830 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
831 Seasoned Guix developers may also want to look at the section on commit
832 access (@pxref{Commit Access}).
834 This mailing list is backed by a Debbugs instance, which allows us to
835 keep track of submissions (@pxref{Tracking Bugs and Patches}). Each
836 message sent to that mailing list gets a new tracking number assigned;
837 people can then follow up on the submission by sending email to
838 @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
839 number (@pxref{Sending a Patch Series}).
841 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
842 standards, GNU Coding Standards}); you can check the commit history for
845 Before submitting a patch that adds or modifies a package definition,
846 please run through this check list:
850 If the authors of the packaged software provide a cryptographic
851 signature for the release tarball, make an effort to verify the
852 authenticity of the archive. For a detached GPG signature file this
853 would be done with the @code{gpg --verify} command.
856 Take some time to provide an adequate synopsis and description for the
857 package. @xref{Synopses and Descriptions}, for some guidelines.
860 Run @code{guix lint @var{package}}, where @var{package} is the
861 name of the new or modified package, and fix any errors it reports
862 (@pxref{Invoking guix lint}).
865 Make sure the package builds on your platform, using @code{guix build
869 We recommend you also try building the package on other supported
870 platforms. As you may not have access to actual hardware platforms, we
871 recommend using the @code{qemu-binfmt-service-type} to emulate them. In
872 order to enable it, add the following service to the list of services in
873 your @code{operating-system} configuration:
876 (service qemu-binfmt-service-type
877 (qemu-binfmt-configuration
878 (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
882 Then reconfigure your system.
884 You can then build packages for different platforms by specifying the
885 @code{--system} option. For example, to build the "hello" package for
886 the armhf, aarch64, or mips64 architectures, you would run the following
887 commands, respectively:
889 guix build --system=armhf-linux --rounds=2 hello
890 guix build --system=aarch64-linux --rounds=2 hello
891 guix build --system=mips64el-linux --rounds=2 hello
896 Make sure the package does not use bundled copies of software already
897 available as separate packages.
899 Sometimes, packages include copies of the source code of their
900 dependencies as a convenience for users. However, as a distribution, we
901 want to make sure that such packages end up using the copy we already
902 have in the distribution, if there is one. This improves resource usage
903 (the dependency is built and stored only once), and allows the
904 distribution to make transverse changes such as applying security
905 updates for a given software package in a single place and have them
906 affect the whole system---something that bundled copies prevent.
909 Take a look at the profile reported by @command{guix size}
910 (@pxref{Invoking guix size}). This will allow you to notice references
911 to other packages unwillingly retained. It may also help determine
912 whether to split the package (@pxref{Packages with Multiple Outputs}),
913 and which optional dependencies should be used. In particular, avoid adding
914 @code{texlive} as a dependency: because of its extreme size, use
915 @code{texlive-tiny} or @code{texlive-union} instead.
918 For important changes, check that dependent package (if applicable) are
919 not affected by the change; @code{guix refresh --list-dependent
920 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
922 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
923 @cindex branching strategy
924 @cindex rebuild scheduling strategy
925 Depending on the number of dependent packages and thus the amount of
926 rebuilding induced, commits go to different branches, along these lines:
929 @item 300 dependent packages or less
930 @code{master} branch (non-disruptive changes).
932 @item between 300 and 1,200 dependent packages
933 @code{staging} branch (non-disruptive changes). This branch is intended
934 to be merged in @code{master} every 3 weeks or so. Topical changes
935 (e.g., an update of the GNOME stack) can instead go to a specific branch
936 (say, @code{gnome-updates}).
938 @item more than 1,200 dependent packages
939 @code{core-updates} branch (may include major and potentially disruptive
940 changes). This branch is intended to be merged in @code{master} every
944 All these branches are @uref{@value{SUBSTITUTE-SERVER},
945 tracked by our build farm} and merged into @code{master} once
946 everything has been successfully built. This allows us to fix issues
947 before they hit users, and to reduce the window during which pre-built
948 binaries are not available.
950 Generally, branches other than @code{master} are considered
951 @emph{frozen} if there has been a recent evaluation, or there is a
952 corresponding @code{-next} branch. Please ask on the mailing list or
953 IRC if unsure where to place a patch.
954 @c TODO: It would be good with badges on the website that tracks these
955 @c branches. Or maybe even a status page.
958 @cindex determinism, of build processes
959 @cindex reproducible builds, checking
960 Check whether the package's build process is deterministic. This
961 typically means checking whether an independent build of the package
962 yields the exact same result that you obtained, bit for bit.
964 A simple way to do that is by building the same package several times in
965 a row on your machine (@pxref{Invoking guix build}):
968 guix build --rounds=2 my-package
971 This is enough to catch a class of common non-determinism issues, such
972 as timestamps or randomly-generated output in the build result.
974 Another option is to use @command{guix challenge} (@pxref{Invoking guix
975 challenge}). You may run it once the package has been committed and
976 built by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
977 result as you did. Better yet: Find another machine that can build it
978 and run @command{guix publish}. Since the remote build machine is
979 likely different from yours, this can catch non-determinism issues
980 related to the hardware---e.g., use of different instruction set
981 extensions---or to the operating system kernel---e.g., reliance on
982 @code{uname} or @file{/proc} files.
985 When writing documentation, please use gender-neutral wording when
986 referring to people, such as
987 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
988 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
991 Verify that your patch contains only one set of related changes.
992 Bundling unrelated changes together makes reviewing harder and slower.
994 Examples of unrelated changes include the addition of several packages,
995 or a package update along with fixes to that package.
998 Please follow our code formatting rules, possibly running the
999 @command{etc/indent-code.el} script to do that automatically for you
1000 (@pxref{Formatting Code}).
1003 When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
1004 Use reliable URLs, not generated ones. For instance, GitHub archives are not
1005 necessarily identical from one generation to the next, so in this case it's
1006 often better to clone the repository. Don't use the @command{name} field in
1007 the URL: it is not very useful and if the name changes, the URL will probably
1011 Check if Guix builds (@pxref{Building from Git}) and address the
1012 warnings, especially those about use of undefined symbols.
1015 Make sure your changes do not break Guix and simulate a @code{guix pull} with:
1017 guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
1022 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
1023 a subject. You may use your email client or the @command{git
1024 send-email} command (@pxref{Sending a Patch Series}). We prefer to get
1025 patches in plain text messages, either inline or as MIME attachments.
1026 You are advised to pay attention if your email client changes anything
1027 like line breaks or indentation which could potentially break the
1030 When a bug is resolved, please close the thread by sending an email to
1031 @email{@var{NNN}-done@@debbugs.gnu.org}.
1033 @unnumberedsubsec Sending a Patch Series
1034 @anchor{Sending a Patch Series}
1035 @cindex patch series
1036 @cindex @code{git send-email}
1037 @cindex @code{git-send-email}
1039 When sending a patch series (e.g., using @code{git send-email}), please
1040 first send one message to @email{guix-patches@@gnu.org}, and then send
1041 subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
1042 they are kept together. See
1043 @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
1044 for more information. You can install @command{git send-email} with
1045 @command{guix install git:send-email}.
1046 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
1048 @node Tracking Bugs and Patches
1049 @section Tracking Bugs and Patches
1051 @cindex bug reports, tracking
1052 @cindex patch submissions, tracking
1053 @cindex issue tracking
1054 @cindex Debbugs, issue tracking system
1055 Bug reports and patch submissions are currently tracked using the
1056 Debbugs instance at @uref{https://bugs.gnu.org}. Bug reports are filed
1057 against the @code{guix} ``package'' (in Debbugs parlance), by sending
1058 email to @email{bug-guix@@gnu.org}, while patch submissions are filed
1059 against the @code{guix-patches} package by sending email to
1060 @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
1062 A web interface (actually @emph{two} web interfaces!) are available to
1067 @url{https://bugs.gnu.org/guix} lists bug reports;
1069 @url{https://bugs.gnu.org/guix-patches} lists patch submissions.
1072 You can also access both of these @i{via} the (nicer)
1073 @url{https://issues.guix.gnu.org} interface@footnote{The web interface
1074 at @url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
1075 software written in Guile, and you can help! See
1076 @url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.}. To view
1077 discussions related to issue number @var{n}, go to
1078 @indicateurl{https://issues.guix.gnu.org/issue/@var{n}} or
1079 @indicateurl{https://bugs.gnu.org/@var{n}}.
1081 If you use Emacs, you may find it more convenient to interact with
1082 issues using @file{debbugs.el}, which you can install with:
1085 guix install emacs-debbugs
1088 For example, to list all open issues on @code{guix-patches}, hit:
1091 @kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
1094 @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
1098 @section Commit Access
1100 @cindex commit access, for developers
1101 For frequent contributors, having write access to the repository is
1102 convenient. When you deem it necessary, consider applying for commit
1103 access by following these steps:
1107 Find three committers who would vouch for you. You can view the list of
1109 @url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Each
1110 of them should email a statement to @email{guix-maintainers@@gnu.org} (a
1111 private alias for the collective of maintainers), signed with their
1114 Committers are expected to have had some interactions with you as a
1115 contributor and to be able to judge whether you are sufficiently
1116 familiar with the project's practices. It is @emph{not} a judgment on
1117 the value of your work, so a refusal should rather be interpreted as
1118 ``let's try again later''.
1121 Send @email{guix-maintainers@@gnu.org} a message stating your intent,
1122 listing the three committers who support your application, signed with
1123 the OpenPGP key you will use to sign commits, and giving its fingerprint
1124 (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
1125 introduction to public-key cryptography with GnuPG.
1128 Maintainers ultimately decide whether to grant you commit access,
1129 usually following your referrals' recommendation.
1132 If and once you've been given access, please send a message to
1133 @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
1134 you will use to sign commits (do that before pushing your first commit).
1135 That way, everyone can notice and ensure you control that OpenPGP key.
1137 @c TODO: Add note about adding the fingerprint to the list of authorized
1138 @c keys once that has stabilized.
1141 Make sure to read the rest of this section and... profit!
1145 Maintainers are happy to give commit access to people who have been
1146 contributing for some time and have a track record---don't be shy and
1147 don't underestimate your work!
1149 However, note that the project is working towards a more automated patch
1150 review and merging system, which, as a consequence, may lead us to have
1151 fewer people with commit access to the main repository. Stay tuned!
1154 If you get commit access, please make sure to follow
1155 the policy below (discussions of the policy can take place on
1156 @email{guix-devel@@gnu.org}).
1158 Non-trivial patches should always be posted to
1159 @email{guix-patches@@gnu.org} (trivial patches include fixing typos,
1160 etc.). This mailing list fills the patch-tracking database
1161 (@pxref{Tracking Bugs and Patches}).
1163 For patches that just add a new package, and a simple one, it's OK to
1164 commit, if you're confident (which means you successfully built it in a
1165 chroot setup, and have done a reasonable copyright and license
1166 auditing). Likewise for package upgrades, except upgrades that trigger
1167 a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a
1168 mailing list for commit notifications (@email{guix-commits@@gnu.org}),
1169 so people can notice. Before pushing your changes, make sure to run
1170 @code{git pull --rebase}.
1172 All commits that are pushed to the central repository on Savannah must
1173 be signed with an OpenPGP key, and the public key should be uploaded to
1174 your user account on Savannah and to public key servers, such as
1175 @code{keys.openpgp.org}. To configure Git to automatically sign
1179 git config commit.gpgsign true
1180 git config user.signingkey CABBA6EA1DC0FF33
1183 You can prevent yourself from accidentally pushing unsigned commits to
1184 Savannah by using the pre-push Git hook called located at
1185 @file{etc/git/pre-push}:
1188 cp etc/git/pre-push .git/hooks/pre-push
1191 When pushing a commit on behalf of somebody else, please add a
1192 @code{Signed-off-by} line at the end of the commit log message---e.g.,
1193 with @command{git am --signoff}. This improves tracking of who did
1196 For anything else, please post to @email{guix-patches@@gnu.org} and
1197 leave time for a review, without committing anything (@pxref{Submitting
1198 Patches}). If you didn’t receive any reply after two weeks, and if
1199 you're confident, it's OK to commit.
1201 That last part is subject to being adjusted, allowing individuals to commit
1202 directly on non-controversial changes on parts they’re familiar with.
1204 One last thing: the project keeps moving forward because committers not
1205 only push their own awesome changes, but also offer some of their time
1206 @emph{reviewing} and pushing other people's changes. As a committer,
1207 you're welcome to use your expertise and commit rights to help other