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.
31 @node Building from Git
32 @section Building from Git
34 If you want to hack Guix itself, it is recommended to use the latest
35 version from the Git repository:
38 git clone https://git.savannah.gnu.org/git/guix.git
41 When building Guix from a checkout,
42 the following packages are required in addition to those mentioned in
43 the installation instructions (@pxref{Requirements}).
46 @item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
47 @item @url{http://gnu.org/software/automake/, GNU Automake};
48 @item @url{http://gnu.org/software/gettext/, GNU Gettext};
49 @item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
50 @item @url{http://www.graphviz.org/, Graphviz};
51 @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
54 The easiest way to set up a development environment for Guix is, of
55 course, by using Guix! The following command starts a new shell where
56 all the dependencies and appropriate environment variables are set up to
63 @xref{Invoking guix environment}, for more information on that command.
64 Extra dependencies can be added with @option{--ad-hoc}:
67 guix environment guix --ad-hoc help2man git strace
70 Run @command{./bootstrap} to generate the build system infrastructure
71 using Autoconf and Automake. If you get an error like this one:
74 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
78 it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
79 provided by pkg-config. Make sure that @file{pkg.m4} is available. The
80 same holds for the @file{guile.m4} set of macros provided by Guile. For
81 instance, if you installed Automake in @file{/usr/local}, it wouldn’t
82 look for @file{.m4} files in @file{/usr/share}. In that case, you have
83 to invoke the following command:
86 export ACLOCAL_PATH=/usr/share/aclocal
89 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
92 Then, run @command{./configure} as usual. Make sure to pass
93 @code{--localstatedir=@var{directory}} where @var{directory} is the
94 @code{localstatedir} value used by your current installation (@pxref{The
95 Store}, for information about this).
97 Finally, you have to invoke @code{make check} to run tests
98 (@pxref{Running the Test Suite}). If anything
99 fails, take a look at installation instructions (@pxref{Installation})
100 or send a message to the @email{guix-devel@@gnu.org, mailing list}.
103 @node Running Guix Before It Is Installed
104 @section Running Guix Before It Is Installed
106 In order to keep a sane working environment, you will find it useful to
107 test the changes made in your local source tree checkout without
108 actually installing them. So that you can distinguish between your
109 ``end-user'' hat and your ``motley'' costume.
111 To that end, all the command-line tools can be used even if you have not
112 run @code{make install}. To do that, you first need to have an environment
113 with all the dependencies available (@pxref{Building from Git}), and then
114 simply prefix each command with
115 @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
116 top build tree of Guix; it is generated by @command{./configure}),
117 as in@footnote{The @option{-E} flag to
118 @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
119 such that @command{guix-daemon} and the tools it uses can find the Guile
123 $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
124 $ ./pre-inst-env guix build hello
128 Similarly, for a Guile session using the Guix modules:
131 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
138 @cindex read-eval-print loop
139 @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
143 $ ./pre-inst-env guile
144 scheme@@(guile-user)> ,use(guix)
145 scheme@@(guile-user)> ,use(gnu)
146 scheme@@(guile-user)> (define snakes
148 (lambda (package lst)
149 (if (string-prefix? "python"
150 (package-name package))
154 scheme@@(guile-user)> (length snakes)
158 The @command{pre-inst-env} script sets up all the environment variables
159 necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
161 Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
162 local source tree; it simply updates the @file{~/.config/guix/current}
163 symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
164 you want to upgrade your local source tree.
167 @node The Perfect Setup
168 @section The Perfect Setup
170 The Perfect Setup to hack on Guix is basically the perfect setup used
171 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
172 Manual}). First, you need more than an editor, you need
173 @url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
174 wonderful @url{http://nongnu.org/geiser/, Geiser}.
176 Geiser allows for interactive and incremental development from within
177 Emacs: code compilation and evaluation from within buffers, access to
178 on-line documentation (docstrings), context-sensitive completion,
179 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
180 and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
181 convenient Guix development, make sure to augment Guile’s load path so
182 that it finds source files from your checkout:
185 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
186 (with-eval-after-load 'geiser-guile
187 (add-to-list 'geiser-guile-load-path "~/src/guix"))
190 To actually edit the code, Emacs already has a neat Scheme mode. But in
191 addition to that, you must not miss
192 @url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
193 facilities to directly operate on the syntax tree, such as raising an
194 s-expression or wrapping it, swallowing or rejecting the following
197 @cindex code snippets
199 @cindex reducing boilerplate
200 We also provide templates for common git commit messages and package
201 definitions in the @file{etc/snippets} directory. These templates can
202 be used with @url{http://joaotavora.github.io/yasnippet/, YASnippet} to
203 expand short trigger strings to interactive text snippets. You may want
204 to add the snippets directory to the @var{yas-snippet-dirs} variable in
208 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
209 (with-eval-after-load 'yasnippet
210 (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
213 The commit message snippets depend on @url{https://magit.vc/, Magit} to
214 display staged files. When editing a commit message type @code{add}
215 followed by @kbd{TAB} to insert a commit message template for adding a
216 package; type @code{update} followed by @kbd{TAB} to insert a template
217 for updating a package; type @code{https} followed by @kbd{TAB} to
218 insert a template for changing the home page URI of a package to HTTPS.
220 The main snippet for @code{scheme-mode} is triggered by typing
221 @code{package...} followed by @kbd{TAB}. This snippet also inserts the
222 trigger string @code{origin...}, which can be expanded further. The
223 @code{origin} snippet in turn may insert other trigger strings ending on
224 @code{...}, which also can be expanded further.
227 @node Packaging Guidelines
228 @section Packaging Guidelines
230 @cindex packages, creating
231 The GNU distribution is nascent and may well lack some of your favorite
232 packages. This section describes how you can help make the distribution
235 Free software packages are usually distributed in the form of
236 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
237 all the source files. Adding a package to the distribution means
238 essentially two things: adding a @dfn{recipe} that describes how to
239 build the package, including a list of other packages required to build
240 it, and adding @dfn{package metadata} along with that recipe, such as a
241 description and licensing information.
243 In Guix all this information is embodied in @dfn{package definitions}.
244 Package definitions provide a high-level view of the package. They are
245 written using the syntax of the Scheme programming language; in fact,
246 for each package we define a variable bound to the package definition,
247 and export that variable from a module (@pxref{Package Modules}).
248 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
249 creating packages. For more information on package definitions,
250 @pxref{Defining Packages}.
252 Once a package definition is in place, stored in a file in the Guix
253 source tree, it can be tested using the @command{guix build} command
254 (@pxref{Invoking guix build}). For example, assuming the new package is
255 called @code{gnew}, you may run this command from the Guix build tree
256 (@pxref{Running Guix Before It Is Installed}):
259 ./pre-inst-env guix build gnew --keep-failed
262 Using @code{--keep-failed} makes it easier to debug build failures since
263 it provides access to the failed build tree. Another useful
264 command-line option when debugging is @code{--log-file}, to access the
267 If the package is unknown to the @command{guix} command, it may be that
268 the source file contains a syntax error, or lacks a @code{define-public}
269 clause to export the package variable. To figure it out, you may load
270 the module from Guile to get more information about the actual error:
273 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
276 Once your package builds correctly, please send us a patch
277 (@pxref{Submitting Patches}). Well, if you need help, we will be happy to
278 help you too. Once the patch is committed in the Guix repository, the
279 new package automatically gets built on the supported platforms by
280 @url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
284 Users can obtain the new package definition simply by running
285 @command{guix pull} (@pxref{Invoking guix pull}). When
286 @code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
287 package automatically downloads binaries from there
288 (@pxref{Substitutes}). The only place where human intervention is
289 needed is to review and apply the patch.
293 * Software Freedom:: What may go into the distribution.
294 * Package Naming:: What's in a name?
295 * Version Numbers:: When the name is not enough.
296 * Synopses and Descriptions:: Helping users find the right package.
297 * Python Modules:: A touch of British comedy.
298 * Perl Modules:: Little pearls.
299 * Java Packages:: Coffee break.
300 * Fonts:: Fond of fonts.
303 @node Software Freedom
304 @subsection Software Freedom
306 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
307 @cindex free software
308 The GNU operating system has been developed so that users can have
309 freedom in their computing. GNU is @dfn{free software}, meaning that
310 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
311 essential freedoms}: to run the program, to study and change the program
312 in source code form, to redistribute exact copies, and to distribute
313 modified versions. Packages found in the GNU distribution provide only
314 software that conveys these four freedoms.
316 In addition, the GNU distribution follow the
317 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
318 software distribution guidelines}. Among other things, these guidelines
319 reject non-free firmware, recommendations of non-free software, and
320 discuss ways to deal with trademarks and patents.
322 Some otherwise free upstream package sources contain a small and optional
323 subset that violates the above guidelines, for instance because this subset
324 is itself non-free code. When that happens, the offending items are removed
325 with appropriate patches or code snippets in the @code{origin} form of the
326 package (@pxref{Defining Packages}). This way, @code{guix
327 build --source} returns the ``freed'' source rather than the unmodified
332 @subsection Package Naming
335 A package has actually two names associated with it:
336 First, there is the name of the @emph{Scheme variable}, the one following
337 @code{define-public}. By this name, the package can be made known in the
338 Scheme code, for instance as input to another package. Second, there is
339 the string in the @code{name} field of a package definition. This name
340 is used by package management commands such as
341 @command{guix package} and @command{guix build}.
343 Both are usually the same and correspond to the lowercase conversion of
344 the project name chosen upstream, with underscores replaced with
345 hyphens. For instance, GNUnet is available as @code{gnunet}, and
346 SDL_net as @code{sdl-net}.
348 We do not add @code{lib} prefixes for library packages, unless these are
349 already part of the official project name. But @pxref{Python
350 Modules} and @ref{Perl Modules} for special rules concerning modules for
351 the Python and Perl languages.
353 Font package names are handled differently, @pxref{Fonts}.
356 @node Version Numbers
357 @subsection Version Numbers
359 @cindex package version
360 We usually package only the latest version of a given free software
361 project. But sometimes, for instance for incompatible library versions,
362 two (or more) versions of the same package are needed. These require
363 different Scheme variable names. We use the name as defined
364 in @ref{Package Naming}
365 for the most recent version; previous versions use the same name, suffixed
366 by @code{-} and the smallest prefix of the version number that may
367 distinguish the two versions.
369 The name inside the package definition is the same for all versions of a
370 package and does not contain any version number.
372 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
380 (define-public gtk+-2
386 If we also wanted GTK+ 3.8.2, this would be packaged as
388 (define-public gtk+-3.8
395 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
396 @c for a discussion of what follows.
397 @cindex version number, for VCS snapshots
398 Occasionally, we package snapshots of upstream's version control system
399 (VCS) instead of formal releases. This should remain exceptional,
400 because it is up to upstream developers to clarify what the stable
401 release is. Yet, it is sometimes necessary. So, what should we put in
402 the @code{version} field?
404 Clearly, we need to make the commit identifier of the VCS snapshot
405 visible in the version string, but we also need to make sure that the
406 version string is monotonically increasing so that @command{guix package
407 --upgrade} can determine which version is newer. Since commit
408 identifiers, notably with Git, are not monotonically increasing, we add
409 a revision number that we increase each time we upgrade to a newer
410 snapshot. The resulting version string looks like this:
415 | | `-- upstream commit ID
417 | `--- Guix package revision
419 latest upstream version
422 It is a good idea to strip commit identifiers in the @code{version}
423 field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
424 aesthetics have a role to play here) as well as problems related to OS
425 limits such as the maximum shebang length (127 bytes for the Linux
426 kernel.) It is best to use the full commit identifiers in
427 @code{origin}s, though, to avoid ambiguities. A typical package
428 definition may look like this:
432 (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
433 (revision "1")) ;Guix package revision
435 (version (git-version "0.9" revision commit))
439 (url "git://example.org/my-package.git")
441 (sha256 (base32 "1mbikn@dots{}"))
442 (file-name (git-file-name name version))))
447 @node Synopses and Descriptions
448 @subsection Synopses and Descriptions
450 @cindex package description
451 @cindex package synopsis
452 As we have seen before, each package in GNU@tie{}Guix includes a
453 synopsis and a description (@pxref{Defining Packages}). Synopses and
454 descriptions are important: They are what @command{guix package
455 --search} searches, and a crucial piece of information to help users
456 determine whether a given package suits their needs. Consequently,
457 packagers should pay attention to what goes into them.
459 Synopses must start with a capital letter and must not end with a
460 period. They must not start with ``a'' or ``the'', which usually does
461 not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
462 tool that frobs files''. The synopsis should say what the package
463 is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
464 used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
465 matching a pattern''.
467 Keep in mind that the synopsis must be meaningful for a very wide
468 audience. For example, ``Manipulate alignments in the SAM format''
469 might make sense for a seasoned bioinformatics researcher, but might be
470 fairly unhelpful or even misleading to a non-specialized audience. It
471 is a good idea to come up with a synopsis that gives an idea of the
472 application domain of the package. In this example, this might give
473 something like ``Manipulate nucleotide sequence alignments'', which
474 hopefully gives the user a better idea of whether this is what they are
477 Descriptions should take between five and ten lines. Use full
478 sentences, and avoid using acronyms without first introducing them.
479 Please avoid marketing phrases such as ``world-leading'',
480 ``industrial-strength'', and ``next-generation'', and avoid superlatives
481 like ``the most advanced''---they are not helpful to users looking for a
482 package and may even sound suspicious. Instead, try to be factual,
483 mentioning use cases and features.
485 @cindex Texinfo markup, in package descriptions
486 Descriptions can include Texinfo markup, which is useful to introduce
487 ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
488 hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
489 should be careful when using some characters for example @samp{@@} and
490 curly braces which are the basic special characters in Texinfo
491 (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
492 such as @command{guix package --show} take care of rendering it
495 Synopses and descriptions are translated by volunteers
496 @uref{http://translationproject.org/domain/guix-packages.html, at the
497 Translation Project} so that as many users as possible can read them in
498 their native language. User interfaces search them and display them in
499 the language specified by the current locale.
501 To allow @command{xgettext} to extract them as translatable strings,
502 synopses and descriptions @emph{must be literal strings}. This means
503 that you cannot use @code{string-append} or @code{format} to construct
509 (synopsis "This is translatable")
510 (description (string-append "This is " "*not*" " translatable.")))
513 Translation is a lot of work so, as a packager, please pay even more
514 attention to your synopses and descriptions as every change may entail
515 additional work for translators. In order to help them, it is possible
516 to make recommendations or instructions visible to them by inserting
517 special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
521 ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
522 (description "ARandR is designed to provide a simple visual front end
523 for the X11 resize-and-rotate (RandR) extension. @dots{}")
528 @subsection Python Modules
531 We currently package Python 2 and Python 3, under the Scheme variable names
532 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
533 To avoid confusion and naming clashes with other programming languages, it
534 seems desirable that the name of a package for a Python module contains
535 the word @code{python}.
537 Some modules are compatible with only one version of Python, others with both.
538 If the package Foo compiles only with Python 3, we name it
539 @code{python-foo}; if it compiles only with Python 2, we name it
540 @code{python2-foo}. If it is compatible with both versions, we create two
541 packages with the corresponding names.
543 If a project already contains the word @code{python}, we drop this;
544 for instance, the module python-dateutil is packaged under the names
545 @code{python-dateutil} and @code{python2-dateutil}. If the project name
546 starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
549 @subsubsection Specifying Dependencies
550 @cindex inputs, for Python packages
552 Dependency information for Python packages is usually available in the
553 package source tree, with varying degrees of accuracy: in the
554 @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
556 Your mission, when writing a recipe for a Python package, is to map
557 these dependencies to the appropriate type of ``input'' (@pxref{package
558 Reference, inputs}). Although the @code{pypi} importer normally does a
559 good job (@pxref{Invoking guix import}), you may want to check the
560 following check list to determine which dependency goes where.
565 We currently package Python 2 with @code{setuptools} and @code{pip}
566 installed like Python 3.4 has per default. Thus you don't need to
567 specify either of these as an input. @command{guix lint} will warn you
571 Python dependencies required at run time go into
572 @code{propagated-inputs}. They are typically defined with the
573 @code{install_requires} keyword in @file{setup.py}, or in the
574 @file{requirements.txt} file.
577 Python packages required only at build time---e.g., those listed with
578 the @code{setup_requires} keyword in @file{setup.py}---or only for
579 testing---e.g., those in @code{tests_require}---go into
580 @code{native-inputs}. The rationale is that (1) they do not need to be
581 propagated because they are not needed at run time, and (2) in a
582 cross-compilation context, it's the ``native'' input that we'd want.
584 Examples are the @code{pytest}, @code{mock}, and @code{nose} test
585 frameworks. Of course if any of these packages is also required at
586 run-time, it needs to go to @code{propagated-inputs}.
589 Anything that does not fall in the previous categories goes to
590 @code{inputs}, for example programs or C libraries required for building
591 Python packages containing C extensions.
594 If a Python package has optional dependencies (@code{extras_require}),
595 it is up to you to decide whether to add them or not, based on their
596 usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
603 @subsection Perl Modules
606 Perl programs standing for themselves are named as any other package,
607 using the lowercase upstream name.
608 For Perl packages containing a single class, we use the lowercase class name,
609 replace all occurrences of @code{::} by dashes and prepend the prefix
611 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
612 Modules containing several classes keep their lowercase upstream name and
613 are also prepended by @code{perl-}. Such modules tend to have the word
614 @code{perl} somewhere in their name, which gets dropped in favor of the
615 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
619 @subsection Java Packages
622 Java programs standing for themselves are named as any other package,
623 using the lowercase upstream name.
625 To avoid confusion and naming clashes with other programming languages,
626 it is desirable that the name of a package for a Java package is
627 prefixed with @code{java-}. If a project already contains the word
628 @code{java}, we drop this; for instance, the package @code{ngsjava} is
629 packaged under the name @code{java-ngs}.
631 For Java packages containing a single class or a small class hierarchy,
632 we use the lowercase class name, replace all occurrences of @code{.} by
633 dashes and prepend the prefix @code{java-}. So the class
634 @code{apache.commons.cli} becomes package
635 @code{java-apache-commons-cli}.
642 For fonts that are in general not installed by a user for typesetting
643 purposes, or that are distributed as part of a larger software package,
644 we rely on the general packaging rules for software; for instance, this
645 applies to the fonts delivered as part of the X.Org system or fonts that
646 are part of TeX Live.
648 To make it easier for a user to search for fonts, names for other packages
649 containing only fonts are constructed as follows, independently of the
650 upstream package name.
652 The name of a package containing only one font family starts with
653 @code{font-}; it is followed by the foundry name and a dash @code{-}
654 if the foundry is known, and the font family name, in which spaces are
655 replaced by dashes (and as usual, all upper case letters are transformed
657 For example, the Gentium font family by SIL is packaged under the name
658 @code{font-sil-gentium}.
660 For a package containing several font families, the name of the collection
661 is used in the place of the font family name.
662 For instance, the Liberation fonts consist of three families,
663 Liberation Sans, Liberation Serif and Liberation Mono.
664 These could be packaged separately under the names
665 @code{font-liberation-sans} and so on; but as they are distributed together
666 under a common name, we prefer to package them together as
667 @code{font-liberation}.
669 In the case where several formats of the same font family or font collection
670 are packaged separately, a short form of the format, prepended by a dash,
671 is added to the package name. We use @code{-ttf} for TrueType fonts,
672 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
677 @section Coding Style
679 In general our code follows the GNU Coding Standards (@pxref{Top,,,
680 standards, GNU Coding Standards}). However, they do not say much about
681 Scheme, so here are some additional rules.
684 * Programming Paradigm:: How to compose your elements.
685 * Modules:: Where to store your code?
686 * Data Types and Pattern Matching:: Implementing data structures.
687 * Formatting Code:: Writing conventions.
690 @node Programming Paradigm
691 @subsection Programming Paradigm
693 Scheme code in Guix is written in a purely functional style. One
694 exception is code that involves input/output, and procedures that
695 implement low-level concepts, such as the @code{memoize} procedure.
700 Guile modules that are meant to be used on the builder side must live in
701 the @code{(guix build @dots{})} name space. They must not refer to
702 other Guix or GNU modules. However, it is OK for a ``host-side'' module
703 to use a build-side module.
705 Modules that deal with the broader GNU system should be in the
706 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
708 @node Data Types and Pattern Matching
709 @subsection Data Types and Pattern Matching
711 The tendency in classical Lisp is to use lists to represent everything,
712 and then to browse them ``by hand'' using @code{car}, @code{cdr},
713 @code{cadr}, and co. There are several problems with that style,
714 notably the fact that it is hard to read, error-prone, and a hindrance
715 to proper type error reports.
717 Guix code should define appropriate data types (for instance, using
718 @code{define-record-type*}) rather than abuse lists. In addition, it
719 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
720 especially when matching lists.
722 @node Formatting Code
723 @subsection Formatting Code
725 @cindex formatting code
727 When writing Scheme code, we follow common wisdom among Scheme
728 programmers. In general, we follow the
729 @url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
730 Style Rules}. This document happens to describe the conventions mostly
731 used in Guile’s code too. It is very thoughtful and well written, so
734 Some special forms introduced in Guix, such as the @code{substitute*}
735 macro, have special indentation rules. These are defined in the
736 @file{.dir-locals.el} file, which Emacs automatically uses. Also note
737 that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
738 highlights Guix code properly (@pxref{Development,,, emacs-guix, The
739 Emacs-Guix Reference Manual}).
741 @cindex indentation, of code
742 @cindex formatting, of code
743 If you do not use Emacs, please make sure to let your editor knows these
744 rules. To automatically indent a package definition, you can also run:
747 ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
751 This automatically indents the definition of @var{package} in
752 @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
753 indent a whole file, omit the second argument:
756 ./etc/indent-code.el gnu/services/@var{file}.scm
759 @cindex Vim, Scheme code editing
760 If you are editing code with Vim, we recommend that you run @code{:set
761 autoindent} so that your code is automatically indented as you type.
763 @uref{https://www.vim.org/scripts/script.php?script_id=3998,
764 @code{paredit.vim}} may help you deal with all these parentheses.
766 We require all top-level procedures to carry a docstring. This
767 requirement can be relaxed for simple private procedures in the
768 @code{(guix build @dots{})} name space, though.
770 Procedures should not have more than four positional parameters. Use
771 keyword parameters for procedures that take more than four parameters.
774 @node Submitting Patches
775 @section Submitting Patches
777 Development is done using the Git distributed version control system.
778 Thus, access to the repository is not strictly necessary. We welcome
779 contributions in the form of patches as produced by @code{git
780 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
782 This mailing list is backed by a Debbugs instance accessible at
783 @uref{https://bugs.gnu.org/guix-patches}, which allows us to keep track
784 of submissions. Each message sent to that mailing list gets a new
785 tracking number assigned; people can then follow up on the submission by
786 sending email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is
787 the tracking number (@pxref{Sending a Patch Series}).
789 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
790 standards, GNU Coding Standards}); you can check the commit history for
793 Before submitting a patch that adds or modifies a package definition,
794 please run through this check list:
798 If the authors of the packaged software provide a cryptographic
799 signature for the release tarball, make an effort to verify the
800 authenticity of the archive. For a detached GPG signature file this
801 would be done with the @code{gpg --verify} command.
804 Take some time to provide an adequate synopsis and description for the
805 package. @xref{Synopses and Descriptions}, for some guidelines.
808 Run @code{guix lint @var{package}}, where @var{package} is the
809 name of the new or modified package, and fix any errors it reports
810 (@pxref{Invoking guix lint}).
813 Make sure the package builds on your platform, using @code{guix build
818 Make sure the package does not use bundled copies of software already
819 available as separate packages.
821 Sometimes, packages include copies of the source code of their
822 dependencies as a convenience for users. However, as a distribution, we
823 want to make sure that such packages end up using the copy we already
824 have in the distribution, if there is one. This improves resource usage
825 (the dependency is built and stored only once), and allows the
826 distribution to make transverse changes such as applying security
827 updates for a given software package in a single place and have them
828 affect the whole system---something that bundled copies prevent.
831 Take a look at the profile reported by @command{guix size}
832 (@pxref{Invoking guix size}). This will allow you to notice references
833 to other packages unwillingly retained. It may also help determine
834 whether to split the package (@pxref{Packages with Multiple Outputs}),
835 and which optional dependencies should be used. In particular, avoid adding
836 @code{texlive} as a dependency: because of its extreme size, use
837 @code{texlive-tiny} or @code{texlive-union} instead.
840 For important changes, check that dependent package (if applicable) are
841 not affected by the change; @code{guix refresh --list-dependent
842 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
844 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
845 @cindex branching strategy
846 @cindex rebuild scheduling strategy
847 Depending on the number of dependent packages and thus the amount of
848 rebuilding induced, commits go to different branches, along these lines:
851 @item 300 dependent packages or less
852 @code{master} branch (non-disruptive changes).
854 @item between 300 and 1,200 dependent packages
855 @code{staging} branch (non-disruptive changes). This branch is intended
856 to be merged in @code{master} every 3 weeks or so. Topical changes
857 (e.g., an update of the GNOME stack) can instead go to a specific branch
858 (say, @code{gnome-updates}).
860 @item more than 1,200 dependent packages
861 @code{core-updates} branch (may include major and potentially disruptive
862 changes). This branch is intended to be merged in @code{master} every
866 All these branches are @uref{https://hydra.gnu.org/project/gnu,
867 tracked by our build farm} and merged into @code{master} once
868 everything has been successfully built. This allows us to fix issues
869 before they hit users, and to reduce the window during which pre-built
870 binaries are not available.
872 Generally, branches other than @code{master} are considered
873 @emph{frozen} if there has been a recent evaluation, or there is a
874 corresponding @code{-next} branch. Please ask on the mailing list or
875 IRC if unsure where to place a patch.
876 @c TODO: It would be good with badges on the website that tracks these
877 @c branches. Or maybe even a status page.
880 @cindex determinism, of build processes
881 @cindex reproducible builds, checking
882 Check whether the package's build process is deterministic. This
883 typically means checking whether an independent build of the package
884 yields the exact same result that you obtained, bit for bit.
886 A simple way to do that is by building the same package several times in
887 a row on your machine (@pxref{Invoking guix build}):
890 guix build --rounds=2 my-package
893 This is enough to catch a class of common non-determinism issues, such
894 as timestamps or randomly-generated output in the build result.
896 Another option is to use @command{guix challenge} (@pxref{Invoking guix
897 challenge}). You may run it once the package has been committed and
898 built by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
899 result as you did. Better yet: Find another machine that can build it
900 and run @command{guix publish}. Since the remote build machine is
901 likely different from yours, this can catch non-determinism issues
902 related to the hardware---e.g., use of different instruction set
903 extensions---or to the operating system kernel---e.g., reliance on
904 @code{uname} or @file{/proc} files.
907 When writing documentation, please use gender-neutral wording when
908 referring to people, such as
909 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
910 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
913 Verify that your patch contains only one set of related changes.
914 Bundling unrelated changes together makes reviewing harder and slower.
916 Examples of unrelated changes include the addition of several packages,
917 or a package update along with fixes to that package.
920 Please follow our code formatting rules, possibly running the
921 @command{etc/indent-code.el} script to do that automatically for you
922 (@pxref{Formatting Code}).
925 When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
926 Use reliable URLs, not generated ones. For instance, GitHub archives are not
927 necessarily identical from one generation to the next, so in this case it's
928 often better to clone the repository. Don't use the @command{name} field in
929 the URL: it is not very useful and if the name changes, the URL will probably
934 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
935 a subject. You may use your email client or the @command{git
936 send-email} command (@pxref{Sending a Patch Series}). We prefer to get
937 patches in plain text messages, either inline or as MIME attachments.
938 You are advised to pay attention if your email client changes anything
939 like line breaks or indentation which could potentially break the
942 When a bug is resolved, please close the thread by sending an email to
943 @email{@var{NNN}-done@@debbugs.gnu.org}.
945 @unnumberedsubsec Sending a Patch Series
946 @anchor{Sending a Patch Series}
948 @cindex @code{git send-email}
949 @cindex @code{git-send-email}
951 When sending a patch series (e.g., using @code{git send-email}), please
952 first send one message to @email{guix-patches@@gnu.org}, and then send
953 subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
954 they are kept together. See
955 @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
956 for more information.
957 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html