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 Libera Chat 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{https://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.
31 * Updating the Guix Package:: Updating the Guix package definition.
32 * Translating Guix:: Make Guix speak your native language.
35 @node Building from Git
36 @section Building from Git
38 If you want to hack Guix itself, it is recommended to use the latest
39 version from the Git repository:
42 git clone https://git.savannah.gnu.org/git/guix.git
45 @cindex authentication, of a Guix checkout
46 How do you ensure that you obtained a genuine copy of the repository?
47 To do that, run @command{guix git authenticate}, passing it the commit
48 and OpenPGP fingerprint of the @dfn{channel introduction}
49 (@pxref{Invoking guix git authenticate}):
51 @c The commit and fingerprint below must match those of the channel
52 @c introduction in '%default-channels'.
54 git fetch origin keyring:keyring
55 guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
56 "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"
60 This command completes with exit code zero on success; it prints an
61 error message and exits with a non-zero code otherwise.
63 As you can see, there is a chicken-and-egg problem: you first need to
64 have Guix installed. Typically you would install Guix System
65 (@pxref{System Installation}) or Guix on top of another distro
66 (@pxref{Binary Installation}); in either case, you would verify the
67 OpenPGP signature on the installation medium. This ``bootstraps'' the
70 The easiest way to set up a development environment for Guix is, of
71 course, by using Guix! The following command starts a new shell where
72 all the dependencies and appropriate environment variables are set up to
76 guix environment guix --pure
79 @xref{Invoking guix environment}, for more information on that command.
81 If you are unable to use Guix when building Guix from a checkout, the
82 following are the required packages in addition to those mentioned in the
83 installation instructions (@pxref{Requirements}).
86 @item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
87 @item @url{https://gnu.org/software/automake/, GNU Automake};
88 @item @url{https://gnu.org/software/gettext/, GNU Gettext};
89 @item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
90 @item @url{https://www.graphviz.org/, Graphviz};
91 @item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
94 On Guix, extra dependencies can be added by instead running @command{guix
95 environment} with @option{--ad-hoc}:
98 guix environment guix --pure --ad-hoc help2man git strace
101 Run @command{./bootstrap} to generate the build system infrastructure
102 using Autoconf and Automake. If you get an error like this one:
105 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
109 it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
110 provided by pkg-config. Make sure that @file{pkg.m4} is available. The
111 same holds for the @file{guile.m4} set of macros provided by Guile. For
112 instance, if you installed Automake in @file{/usr/local}, it wouldn’t
113 look for @file{.m4} files in @file{/usr/share}. In that case, you have
114 to invoke the following command:
117 export ACLOCAL_PATH=/usr/share/aclocal
120 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
123 Then, run @command{./configure} as usual. Make sure to pass
124 @code{--localstatedir=@var{directory}} where @var{directory} is the
125 @code{localstatedir} value used by your current installation (@pxref{The
126 Store}, for information about this), usually @file{/var}. Note that you
127 will probably not run @command{make install} at the end (you don't have
128 to) but it's still important to pass the right @code{localstatedir}.
130 Finally, you have to invoke @code{make && make check} to build Guix and
131 run the tests (@pxref{Running the Test Suite}). If anything fails, take
132 a look at installation instructions (@pxref{Installation}) or send a
133 message to the @email{guix-devel@@gnu.org, mailing list}.
135 From there on, you can authenticate all the commits included in your
142 The first run takes a couple of minutes, but subsequent runs are faster.
144 Or, when your configuration for your local Git repository doesn't match
145 the default one, you can provide the reference for the @code{keyring}
146 branch through the variable @code{GUIX_GIT_KEYRING}. The following
147 example assumes that you have a Git remote called @samp{myremote}
148 pointing to the official repository:
151 make authenticate GUIX_GIT_KEYRING=myremote/keyring
155 You are advised to run @command{make authenticate} after every
156 @command{git pull} invocation. This ensures you keep receiving valid
157 changes to the repository.
161 @node Running Guix Before It Is Installed
162 @section Running Guix Before It Is Installed
164 In order to keep a sane working environment, you will find it useful to
165 test the changes made in your local source tree checkout without
166 actually installing them. So that you can distinguish between your
167 ``end-user'' hat and your ``motley'' costume.
169 To that end, all the command-line tools can be used even if you have not
170 run @code{make install}. To do that, you first need to have an
171 environment with all the dependencies available (@pxref{Building from
172 Git}), and then simply prefix each command with @command{./pre-inst-env}
173 (the @file{pre-inst-env} script lives in the top build tree of Guix; it
174 is generated by running @command{./bootstrap} followed by
175 @command{./configure}). As an example, here is how you would build the
176 @code{hello} package as defined in your working tree (this assumes
177 @command{guix-daemon} is already running on your system; it's OK if it's
178 a different version):
181 $ ./pre-inst-env guix build hello
185 Similarly, an example for a Guile session using the Guix modules:
188 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
195 @cindex read-eval-print loop
196 @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
200 $ ./pre-inst-env guile
201 scheme@@(guile-user)> ,use(guix)
202 scheme@@(guile-user)> ,use(gnu)
203 scheme@@(guile-user)> (define snakes
205 (lambda (package lst)
206 (if (string-prefix? "python"
207 (package-name package))
211 scheme@@(guile-user)> (length snakes)
215 If you are hacking on the daemon and its supporting code or if
216 @command{guix-daemon} is not already running on your system, you can
217 launch it straight from the build tree@footnote{The @option{-E} flag to
218 @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
219 such that @command{guix-daemon} and the tools it uses can find the Guile
223 $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
226 The @command{pre-inst-env} script sets up all the environment variables
227 necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
229 Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
230 local source tree; it simply updates the @file{~/.config/guix/current}
231 symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
232 you want to upgrade your local source tree.
235 @node The Perfect Setup
236 @section The Perfect Setup
238 The Perfect Setup to hack on Guix is basically the perfect setup used
239 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
240 Manual}). First, you need more than an editor, you need
241 @url{https://www.gnu.org/software/emacs, Emacs}, empowered by the
242 wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run:
245 guix package -i emacs guile emacs-geiser emacs-geiser-guile
248 Geiser allows for interactive and incremental development from within
249 Emacs: code compilation and evaluation from within buffers, access to
250 on-line documentation (docstrings), context-sensitive completion,
251 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
252 and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
253 convenient Guix development, make sure to augment Guile’s load path so
254 that it finds source files from your checkout:
257 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
258 (with-eval-after-load 'geiser-guile
259 (add-to-list 'geiser-guile-load-path "~/src/guix"))
262 To actually edit the code, Emacs already has a neat Scheme mode. But in
263 addition to that, you must not miss
264 @url{https://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
265 facilities to directly operate on the syntax tree, such as raising an
266 s-expression or wrapping it, swallowing or rejecting the following
269 @cindex code snippets
271 @cindex reducing boilerplate
272 We also provide templates for common git commit messages and package
273 definitions in the @file{etc/snippets} directory. These templates can
274 be used with @url{https://joaotavora.github.io/yasnippet/, YASnippet} to
275 expand short trigger strings to interactive text snippets. You may want
276 to add the snippets directory to the @var{yas-snippet-dirs} variable in
280 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
281 (with-eval-after-load 'yasnippet
282 (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
285 The commit message snippets depend on @url{https://magit.vc/, Magit} to
286 display staged files. When editing a commit message type @code{add}
287 followed by @kbd{TAB} to insert a commit message template for adding a
288 package; type @code{update} followed by @kbd{TAB} to insert a template
289 for updating a package; type @code{https} followed by @kbd{TAB} to
290 insert a template for changing the home page URI of a package to HTTPS.
292 The main snippet for @code{scheme-mode} is triggered by typing
293 @code{package...} followed by @kbd{TAB}. This snippet also inserts the
294 trigger string @code{origin...}, which can be expanded further. The
295 @code{origin} snippet in turn may insert other trigger strings ending on
296 @code{...}, which also can be expanded further.
298 @cindex insert or update copyright
299 @cindex @code{M-x guix-copyright}
300 @cindex @code{M-x copyright-update}
301 We additionally provide insertion and automatic update of a copyright in
302 @file{etc/copyright.el}. You may want to set your full name, mail, and
306 (setq user-full-name "Alice Doe")
307 (setq user-mail-address "alice@@mail.org")
308 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
309 (load-file "~/src/guix/etc/copyright.el")
312 To insert a copyright at the current line invoke @code{M-x guix-copyright}.
314 To update a copyright you need to specify a @code{copyright-names-regexp}.
317 (setq copyright-names-regexp
318 (format "%s <%s>" user-full-name user-mail-address))
321 You can check if your copyright is up to date by evaluating @code{M-x
322 copyright-update}. If you want to do it automatically after each buffer
323 save then add @code{(add-hook 'after-save-hook 'copyright-update)} in
326 @node Packaging Guidelines
327 @section Packaging Guidelines
329 @cindex packages, creating
330 The GNU distribution is nascent and may well lack some of your favorite
331 packages. This section describes how you can help make the distribution
334 Free software packages are usually distributed in the form of
335 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
336 all the source files. Adding a package to the distribution means
337 essentially two things: adding a @dfn{recipe} that describes how to
338 build the package, including a list of other packages required to build
339 it, and adding @dfn{package metadata} along with that recipe, such as a
340 description and licensing information.
342 In Guix all this information is embodied in @dfn{package definitions}.
343 Package definitions provide a high-level view of the package. They are
344 written using the syntax of the Scheme programming language; in fact,
345 for each package we define a variable bound to the package definition,
346 and export that variable from a module (@pxref{Package Modules}).
347 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
348 creating packages. For more information on package definitions,
349 @pxref{Defining Packages}.
351 Once a package definition is in place, stored in a file in the Guix
352 source tree, it can be tested using the @command{guix build} command
353 (@pxref{Invoking guix build}). For example, assuming the new package is
354 called @code{gnew}, you may run this command from the Guix build tree
355 (@pxref{Running Guix Before It Is Installed}):
358 ./pre-inst-env guix build gnew --keep-failed
361 Using @code{--keep-failed} makes it easier to debug build failures since
362 it provides access to the failed build tree. Another useful
363 command-line option when debugging is @code{--log-file}, to access the
366 If the package is unknown to the @command{guix} command, it may be that
367 the source file contains a syntax error, or lacks a @code{define-public}
368 clause to export the package variable. To figure it out, you may load
369 the module from Guile to get more information about the actual error:
372 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
375 Once your package builds correctly, please send us a patch
376 (@pxref{Submitting Patches}). Well, if you need help, we will be happy to
377 help you too. Once the patch is committed in the Guix repository, the
378 new package automatically gets built on the supported platforms by
379 @url{@value{SUBSTITUTE-URL}, our continuous integration system}.
382 Users can obtain the new package definition simply by running
383 @command{guix pull} (@pxref{Invoking guix pull}). When
384 @code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
385 package automatically downloads binaries from there
386 (@pxref{Substitutes}). The only place where human intervention is
387 needed is to review and apply the patch.
391 * Software Freedom:: What may go into the distribution.
392 * Package Naming:: What's in a name?
393 * Version Numbers:: When the name is not enough.
394 * Synopses and Descriptions:: Helping users find the right package.
395 * Snippets versus Phases:: Whether to use a snippet, or a build phase.
396 * Emacs Packages:: Your Elisp fix.
397 * Python Modules:: A touch of British comedy.
398 * Perl Modules:: Little pearls.
399 * Java Packages:: Coffee break.
400 * Rust Crates:: Beware of oxidation.
401 * Fonts:: Fond of fonts.
404 @node Software Freedom
405 @subsection Software Freedom
407 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
408 @cindex free software
409 The GNU operating system has been developed so that users can have
410 freedom in their computing. GNU is @dfn{free software}, meaning that
411 users have the @url{https://www.gnu.org/philosophy/free-sw.html,four
412 essential freedoms}: to run the program, to study and change the program
413 in source code form, to redistribute exact copies, and to distribute
414 modified versions. Packages found in the GNU distribution provide only
415 software that conveys these four freedoms.
417 In addition, the GNU distribution follow the
418 @url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free
419 software distribution guidelines}. Among other things, these guidelines
420 reject non-free firmware, recommendations of non-free software, and
421 discuss ways to deal with trademarks and patents.
423 Some otherwise free upstream package sources contain a small and optional
424 subset that violates the above guidelines, for instance because this subset
425 is itself non-free code. When that happens, the offending items are removed
426 with appropriate patches or code snippets in the @code{origin} form of the
427 package (@pxref{Defining Packages}). This way, @code{guix
428 build --source} returns the ``freed'' source rather than the unmodified
433 @subsection Package Naming
436 A package actually has two names associated with it.
437 First, there is the name of the @emph{Scheme variable}, the one following
438 @code{define-public}. By this name, the package can be made known in the
439 Scheme code, for instance as input to another package. Second, there is
440 the string in the @code{name} field of a package definition. This name
441 is used by package management commands such as
442 @command{guix package} and @command{guix build}.
444 Both are usually the same and correspond to the lowercase conversion of
445 the project name chosen upstream, with underscores replaced with
446 hyphens. For instance, GNUnet is available as @code{gnunet}, and
447 SDL_net as @code{sdl-net}.
449 A noteworthy exception to this rule is when the project name is only a
450 single character, or if an older maintained project with the same name
451 already exists---regardless of whether it has already been packaged for
452 Guix. Use common sense to make such names unambiguous and meaningful.
453 For example, Guix's package for the shell called ``s'' upstream is
454 @code{s-shell} and @emph{not} @code{s}. Feel free to ask your fellow
455 hackers for inspiration.
457 We do not add @code{lib} prefixes for library packages, unless these are
458 already part of the official project name. But @pxref{Python
459 Modules} and @ref{Perl Modules} for special rules concerning modules for
460 the Python and Perl languages.
462 Font package names are handled differently, @pxref{Fonts}.
465 @node Version Numbers
466 @subsection Version Numbers
468 @cindex package version
469 We usually package only the latest version of a given free software
470 project. But sometimes, for instance for incompatible library versions,
471 two (or more) versions of the same package are needed. These require
472 different Scheme variable names. We use the name as defined
473 in @ref{Package Naming}
474 for the most recent version; previous versions use the same name, suffixed
475 by @code{-} and the smallest prefix of the version number that may
476 distinguish the two versions.
478 The name inside the package definition is the same for all versions of a
479 package and does not contain any version number.
481 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
489 (define-public gtk+-2
495 If we also wanted GTK+ 3.8.2, this would be packaged as
497 (define-public gtk+-3.8
504 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
505 @c for a discussion of what follows.
506 @cindex version number, for VCS snapshots
507 Occasionally, we package snapshots of upstream's version control system
508 (VCS) instead of formal releases. This should remain exceptional,
509 because it is up to upstream developers to clarify what the stable
510 release is. Yet, it is sometimes necessary. So, what should we put in
511 the @code{version} field?
513 Clearly, we need to make the commit identifier of the VCS snapshot
514 visible in the version string, but we also need to make sure that the
515 version string is monotonically increasing so that @command{guix package
516 --upgrade} can determine which version is newer. Since commit
517 identifiers, notably with Git, are not monotonically increasing, we add
518 a revision number that we increase each time we upgrade to a newer
519 snapshot. The resulting version string looks like this:
524 | | `-- upstream commit ID
526 | `--- Guix package revision
528 latest upstream version
531 It is a good idea to strip commit identifiers in the @code{version}
532 field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
533 aesthetics have a role to play here) as well as problems related to OS
534 limits such as the maximum shebang length (127 bytes for the Linux
535 kernel). There are helper functions for doing this for packages using
536 @code{git-fetch} or @code{hg-fetch} (see below). It is best to use the
537 full commit identifiers in @code{origin}s, though, to avoid ambiguities.
538 A typical package definition may look like this:
543 (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
544 (revision "1")) ;Guix package revision
546 (version (git-version "0.9" revision commit))
550 (url "git://example.org/my-package.git")
552 (sha256 (base32 "1mbikn@dots{}"))
553 (file-name (git-file-name name version))))
558 @deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
559 Return the version string for packages using @code{git-fetch}.
562 (git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
563 @result{} "0.2.3-0.93818c9"
567 @deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
568 Return the version string for packages using @code{hg-fetch}. It works
569 in the same way as @code{git-version}.
572 @node Synopses and Descriptions
573 @subsection Synopses and Descriptions
575 @cindex package description
576 @cindex package synopsis
577 As we have seen before, each package in GNU@tie{}Guix includes a
578 synopsis and a description (@pxref{Defining Packages}). Synopses and
579 descriptions are important: They are what @command{guix package
580 --search} searches, and a crucial piece of information to help users
581 determine whether a given package suits their needs. Consequently,
582 packagers should pay attention to what goes into them.
584 Synopses must start with a capital letter and must not end with a
585 period. They must not start with ``a'' or ``the'', which usually does
586 not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
587 tool that frobs files''. The synopsis should say what the package
588 is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
589 used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
590 matching a pattern''.
592 Keep in mind that the synopsis must be meaningful for a very wide
593 audience. For example, ``Manipulate alignments in the SAM format''
594 might make sense for a seasoned bioinformatics researcher, but might be
595 fairly unhelpful or even misleading to a non-specialized audience. It
596 is a good idea to come up with a synopsis that gives an idea of the
597 application domain of the package. In this example, this might give
598 something like ``Manipulate nucleotide sequence alignments'', which
599 hopefully gives the user a better idea of whether this is what they are
602 Descriptions should take between five and ten lines. Use full
603 sentences, and avoid using acronyms without first introducing them.
604 Please avoid marketing phrases such as ``world-leading'',
605 ``industrial-strength'', and ``next-generation'', and avoid superlatives
606 like ``the most advanced''---they are not helpful to users looking for a
607 package and may even sound suspicious. Instead, try to be factual,
608 mentioning use cases and features.
610 @cindex Texinfo markup, in package descriptions
611 Descriptions can include Texinfo markup, which is useful to introduce
612 ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
613 hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
614 should be careful when using some characters for example @samp{@@} and
615 curly braces which are the basic special characters in Texinfo
616 (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
617 such as @command{guix package --show} take care of rendering it
620 Synopses and descriptions are translated by volunteers
621 @uref{https://translate.fedoraproject.org/projects/guix/packages, at
622 Weblate} so that as many users as possible can read them in
623 their native language. User interfaces search them and display them in
624 the language specified by the current locale.
626 To allow @command{xgettext} to extract them as translatable strings,
627 synopses and descriptions @emph{must be literal strings}. This means
628 that you cannot use @code{string-append} or @code{format} to construct
634 (synopsis "This is translatable")
635 (description (string-append "This is " "*not*" " translatable.")))
638 Translation is a lot of work so, as a packager, please pay even more
639 attention to your synopses and descriptions as every change may entail
640 additional work for translators. In order to help them, it is possible
641 to make recommendations or instructions visible to them by inserting
642 special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
646 ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
647 (description "ARandR is designed to provide a simple visual front end
648 for the X11 resize-and-rotate (RandR) extension. @dots{}")
651 @node Snippets versus Phases
652 @subsection Snippets versus Phases
654 @cindex snippets, when to use
655 The boundary between using an origin snippet versus a build phase to
656 modify the sources of a package can be elusive. Origin snippets are
657 typically used to remove unwanted files such as bundled libraries,
658 nonfree sources, or to apply simple substitutions. The source derived
659 from an origin should produce a source that can be used to build the
660 package on any system that the upstream package supports (i.e., act as
661 the corresponding source). In particular, origin snippets must not
662 embed store items in the sources; such patching should rather be done
663 using build phases. Refer to the @code{origin} record documentation for
664 more information (@pxref{origin Reference}).
667 @subsection Emacs Packages
669 @cindex emacs, packaging
670 @cindex elisp, packaging
671 Emacs packages should preferably use the Emacs build system
672 (@pxref{emacs-build-system}), for uniformity and the benefits provided
673 by its build phases, such as the auto-generation of the autoloads file
674 and the byte compilation of the sources. Because there is no
675 standardized way to run a test suite for Emacs packages, tests are
676 disabled by default. When a test suite is available, it should be
677 enabled by setting the @code{#:tests?} argument to @code{#true}. By
678 default, the command to run the test is @command{make check}, but any
679 command can be specified via the @code{#:test-command} argument. The
680 @code{#:test-command} argument expects a list containing a command and
681 its arguments, to be invoked during the @code{check} phase.
683 The Elisp dependencies of Emacs packages are typically provided as
684 @code{propagated-inputs} when required at run time. As for other
685 packages, build or test dependencies should be specified as
686 @code{native-inputs}.
688 Emacs packages sometimes depend on resources directories that should be
689 installed along the Elisp files. The @code{#:include} argument can be
690 used for that purpose, by specifying a list of regexps to match. The
691 best practice when using the @code{#:include} argument is to extend
692 rather than override its default value (accessible via the
693 @code{%default-include} variable). As an example, a yasnippet extension
694 package typically include a @file{snippets} directory, which could be
695 copied to the installation directory using:
698 #:include (cons "^snippets/" %default-include))
701 When encountering problems, it is wise to check for the presence of the
702 @code{Package-Requires} extension header in the package main source
703 file, and whether any dependencies and their versions listed therein are
707 @subsection Python Modules
710 We currently package Python 2 and Python 3, under the Scheme variable names
711 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
712 To avoid confusion and naming clashes with other programming languages, it
713 seems desirable that the name of a package for a Python module contains
714 the word @code{python}.
716 Some modules are compatible with only one version of Python, others with
717 both. If the package Foo is compiled with Python 3, we name it
718 @code{python-foo}. If it is compiled with Python 2, we name it
719 @code{python2-foo}. Packages should be added when they are necessary;
720 we don't add Python 2 variants of the package unless we are going to use
723 If a project already contains the word @code{python}, we drop this;
724 for instance, the module python-dateutil is packaged under the names
725 @code{python-dateutil} and @code{python2-dateutil}. If the project name
726 starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
729 @subsubsection Specifying Dependencies
730 @cindex inputs, for Python packages
732 Dependency information for Python packages is usually available in the
733 package source tree, with varying degrees of accuracy: in the
734 @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
736 Your mission, when writing a recipe for a Python package, is to map
737 these dependencies to the appropriate type of ``input'' (@pxref{package
738 Reference, inputs}). Although the @code{pypi} importer normally does a
739 good job (@pxref{Invoking guix import}), you may want to check the
740 following check list to determine which dependency goes where.
745 We currently package Python 2 with @code{setuptools} and @code{pip}
746 installed like Python 3.4 has per default. Thus you don't need to
747 specify either of these as an input. @command{guix lint} will warn you
751 Python dependencies required at run time go into
752 @code{propagated-inputs}. They are typically defined with the
753 @code{install_requires} keyword in @file{setup.py}, or in the
754 @file{requirements.txt} file.
757 Python packages required only at build time---e.g., those listed with
758 the @code{setup_requires} keyword in @file{setup.py}---or only for
759 testing---e.g., those in @code{tests_require}---go into
760 @code{native-inputs}. The rationale is that (1) they do not need to be
761 propagated because they are not needed at run time, and (2) in a
762 cross-compilation context, it's the ``native'' input that we'd want.
764 Examples are the @code{pytest}, @code{mock}, and @code{nose} test
765 frameworks. Of course if any of these packages is also required at
766 run-time, it needs to go to @code{propagated-inputs}.
769 Anything that does not fall in the previous categories goes to
770 @code{inputs}, for example programs or C libraries required for building
771 Python packages containing C extensions.
774 If a Python package has optional dependencies (@code{extras_require}),
775 it is up to you to decide whether to add them or not, based on their
776 usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
783 @subsection Perl Modules
786 Perl programs standing for themselves are named as any other package,
787 using the lowercase upstream name.
788 For Perl packages containing a single class, we use the lowercase class name,
789 replace all occurrences of @code{::} by dashes and prepend the prefix
791 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
792 Modules containing several classes keep their lowercase upstream name and
793 are also prepended by @code{perl-}. Such modules tend to have the word
794 @code{perl} somewhere in their name, which gets dropped in favor of the
795 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
799 @subsection Java Packages
802 Java programs standing for themselves are named as any other package,
803 using the lowercase upstream name.
805 To avoid confusion and naming clashes with other programming languages,
806 it is desirable that the name of a package for a Java package is
807 prefixed with @code{java-}. If a project already contains the word
808 @code{java}, we drop this; for instance, the package @code{ngsjava} is
809 packaged under the name @code{java-ngs}.
811 For Java packages containing a single class or a small class hierarchy,
812 we use the lowercase class name, replace all occurrences of @code{.} by
813 dashes and prepend the prefix @code{java-}. So the class
814 @code{apache.commons.cli} becomes package
815 @code{java-apache-commons-cli}.
819 @subsection Rust Crates
822 Rust programs standing for themselves are named as any other package, using the
823 lowercase upstream name.
825 To prevent namespace collisions we prefix all other Rust packages with the
826 @code{rust-} prefix. The name should be changed to lowercase as appropriate and
827 dashes should remain in place.
829 In the rust ecosystem it is common for multiple incompatible versions of a
830 package to be used at any given time, so all package definitions should have a
831 versioned suffix. The versioned suffix is the left-most non-zero digit (and
832 any leading zeros, of course). This follows the ``caret'' version scheme
833 intended by Cargo. Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
835 Because of the difficulty in reusing rust packages as pre-compiled inputs for
836 other packages the Cargo build system (@pxref{Build Systems,
837 @code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
838 @code{cargo-development-inputs} keywords as build system arguments. It would be
839 helpful to think of these as similar to @code{propagated-inputs} and
840 @code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies}
841 should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
842 @code{#:cargo-development-inputs}. If a Rust package links to other libraries
843 then the standard placement in @code{inputs} and the like should be used.
845 Care should be taken to ensure the correct version of dependencies are used; to
846 this end we try to refrain from skipping the tests or using @code{#:skip-build?}
847 when possible. Of course this is not always possible, as the package may be
848 developed for a different Operating System, depend on features from the Nightly
849 Rust compiler, or the test suite may have atrophied since it was released.
856 For fonts that are in general not installed by a user for typesetting
857 purposes, or that are distributed as part of a larger software package,
858 we rely on the general packaging rules for software; for instance, this
859 applies to the fonts delivered as part of the X.Org system or fonts that
860 are part of TeX Live.
862 To make it easier for a user to search for fonts, names for other packages
863 containing only fonts are constructed as follows, independently of the
864 upstream package name.
866 The name of a package containing only one font family starts with
867 @code{font-}; it is followed by the foundry name and a dash @code{-}
868 if the foundry is known, and the font family name, in which spaces are
869 replaced by dashes (and as usual, all upper case letters are transformed
871 For example, the Gentium font family by SIL is packaged under the name
872 @code{font-sil-gentium}.
874 For a package containing several font families, the name of the collection
875 is used in the place of the font family name.
876 For instance, the Liberation fonts consist of three families,
877 Liberation Sans, Liberation Serif and Liberation Mono.
878 These could be packaged separately under the names
879 @code{font-liberation-sans} and so on; but as they are distributed together
880 under a common name, we prefer to package them together as
881 @code{font-liberation}.
883 In the case where several formats of the same font family or font collection
884 are packaged separately, a short form of the format, prepended by a dash,
885 is added to the package name. We use @code{-ttf} for TrueType fonts,
886 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
891 @section Coding Style
893 In general our code follows the GNU Coding Standards (@pxref{Top,,,
894 standards, GNU Coding Standards}). However, they do not say much about
895 Scheme, so here are some additional rules.
898 * Programming Paradigm:: How to compose your elements.
899 * Modules:: Where to store your code?
900 * Data Types and Pattern Matching:: Implementing data structures.
901 * Formatting Code:: Writing conventions.
904 @node Programming Paradigm
905 @subsection Programming Paradigm
907 Scheme code in Guix is written in a purely functional style. One
908 exception is code that involves input/output, and procedures that
909 implement low-level concepts, such as the @code{memoize} procedure.
914 Guile modules that are meant to be used on the builder side must live in
915 the @code{(guix build @dots{})} name space. They must not refer to
916 other Guix or GNU modules. However, it is OK for a ``host-side'' module
917 to use a build-side module.
919 Modules that deal with the broader GNU system should be in the
920 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
922 @node Data Types and Pattern Matching
923 @subsection Data Types and Pattern Matching
925 The tendency in classical Lisp is to use lists to represent everything,
926 and then to browse them ``by hand'' using @code{car}, @code{cdr},
927 @code{cadr}, and co. There are several problems with that style,
928 notably the fact that it is hard to read, error-prone, and a hindrance
929 to proper type error reports.
931 Guix code should define appropriate data types (for instance, using
932 @code{define-record-type*}) rather than abuse lists. In addition, it
933 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
934 especially when matching lists (@pxref{Pattern Matching,,, guile, GNU
935 Guile Reference Manual}).
937 @node Formatting Code
938 @subsection Formatting Code
940 @cindex formatting code
942 When writing Scheme code, we follow common wisdom among Scheme
943 programmers. In general, we follow the
944 @url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
945 Style Rules}. This document happens to describe the conventions mostly
946 used in Guile’s code too. It is very thoughtful and well written, so
949 Some special forms introduced in Guix, such as the @code{substitute*}
950 macro, have special indentation rules. These are defined in the
951 @file{.dir-locals.el} file, which Emacs automatically uses. Also note
952 that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
953 highlights Guix code properly (@pxref{Development,,, emacs-guix, The
954 Emacs-Guix Reference Manual}).
956 @cindex indentation, of code
957 @cindex formatting, of code
958 If you do not use Emacs, please make sure to let your editor knows these
959 rules. To automatically indent a package definition, you can also run:
962 ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
966 This automatically indents the definition of @var{package} in
967 @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
968 indent a whole file, omit the second argument:
971 ./etc/indent-code.el gnu/services/@var{file}.scm
974 @cindex Vim, Scheme code editing
975 If you are editing code with Vim, we recommend that you run @code{:set
976 autoindent} so that your code is automatically indented as you type.
978 @uref{https://www.vim.org/scripts/script.php?script_id=3998,
979 @code{paredit.vim}} may help you deal with all these parentheses.
981 We require all top-level procedures to carry a docstring. This
982 requirement can be relaxed for simple private procedures in the
983 @code{(guix build @dots{})} name space, though.
985 Procedures should not have more than four positional parameters. Use
986 keyword parameters for procedures that take more than four parameters.
989 @node Submitting Patches
990 @section Submitting Patches
992 Development is done using the Git distributed version control system.
993 Thus, access to the repository is not strictly necessary. We welcome
994 contributions in the form of patches as produced by @code{git
995 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
996 Seasoned Guix developers may also want to look at the section on commit
997 access (@pxref{Commit Access}).
999 This mailing list is backed by a Debbugs instance, which allows us to
1000 keep track of submissions (@pxref{Tracking Bugs and Patches}). Each
1001 message sent to that mailing list gets a new tracking number assigned;
1002 people can then follow up on the submission by sending email to
1003 @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
1004 number (@pxref{Sending a Patch Series}).
1006 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
1007 standards, GNU Coding Standards}); you can check the commit history for
1010 Before submitting a patch that adds or modifies a package definition,
1011 please run through this check list:
1015 If the authors of the packaged software provide a cryptographic
1016 signature for the release tarball, make an effort to verify the
1017 authenticity of the archive. For a detached GPG signature file this
1018 would be done with the @code{gpg --verify} command.
1021 Take some time to provide an adequate synopsis and description for the
1022 package. @xref{Synopses and Descriptions}, for some guidelines.
1025 Run @code{guix lint @var{package}}, where @var{package} is the
1026 name of the new or modified package, and fix any errors it reports
1027 (@pxref{Invoking guix lint}).
1030 Make sure the package builds on your platform, using @code{guix build
1034 We recommend you also try building the package on other supported
1035 platforms. As you may not have access to actual hardware platforms, we
1036 recommend using the @code{qemu-binfmt-service-type} to emulate them. In
1037 order to enable it, add the @code{virtualization} service module and the
1038 following service to the list of services in your @code{operating-system}
1042 (service qemu-binfmt-service-type
1043 (qemu-binfmt-configuration
1044 (platforms (lookup-qemu-platforms "arm" "aarch64"))))
1047 Then reconfigure your system.
1049 You can then build packages for different platforms by specifying the
1050 @code{--system} option. For example, to build the "hello" package for
1051 the armhf or aarch64 architectures, you would run the following
1052 commands, respectively:
1054 guix build --system=armhf-linux --rounds=2 hello
1055 guix build --system=aarch64-linux --rounds=2 hello
1060 Make sure the package does not use bundled copies of software already
1061 available as separate packages.
1063 Sometimes, packages include copies of the source code of their
1064 dependencies as a convenience for users. However, as a distribution, we
1065 want to make sure that such packages end up using the copy we already
1066 have in the distribution, if there is one. This improves resource usage
1067 (the dependency is built and stored only once), and allows the
1068 distribution to make transverse changes such as applying security
1069 updates for a given software package in a single place and have them
1070 affect the whole system---something that bundled copies prevent.
1073 Take a look at the profile reported by @command{guix size}
1074 (@pxref{Invoking guix size}). This will allow you to notice references
1075 to other packages unwillingly retained. It may also help determine
1076 whether to split the package (@pxref{Packages with Multiple Outputs}),
1077 and which optional dependencies should be used. In particular, avoid adding
1078 @code{texlive} as a dependency: because of its extreme size, use
1079 the @code{texlive-tiny} package or @code{texlive-union} procedure instead.
1082 For important changes, check that dependent packages (if applicable) are
1083 not affected by the change; @code{guix refresh --list-dependent
1084 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
1086 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
1087 @cindex branching strategy
1088 @cindex rebuild scheduling strategy
1089 Depending on the number of dependent packages and thus the amount of
1090 rebuilding induced, commits go to different branches, along these lines:
1093 @item 300 dependent packages or less
1094 @code{master} branch (non-disruptive changes).
1096 @item between 300 and 1,800 dependent packages
1097 @code{staging} branch (non-disruptive changes). This branch is intended
1098 to be merged in @code{master} every 6 weeks or so. Topical changes
1099 (e.g., an update of the GNOME stack) can instead go to a specific branch
1100 (say, @code{gnome-updates}). This branch is not expected to be
1101 buildable or usable until late in its development process.
1103 @item more than 1,800 dependent packages
1104 @code{core-updates} branch (may include major and potentially disruptive
1105 changes). This branch is intended to be merged in @code{master} every
1106 6 months or so. This branch is not expected to be buildable or usable
1107 until late in its development process.
1110 All these branches are @uref{@value{SUBSTITUTE-URL},
1111 tracked by our build farm} and merged into @code{master} once
1112 everything has been successfully built. This allows us to fix issues
1113 before they hit users, and to reduce the window during which pre-built
1114 binaries are not available.
1116 When we decide to start building the @code{staging} or
1117 @code{core-updates} branches, they will be forked and renamed with the
1118 suffix @code{-frozen}, at which time only bug fixes may be pushed to the
1119 frozen branches. The @code{core-updates} and @code{staging} branches
1120 will remain open to accept patches for the next cycle. Please ask on
1121 the mailing list or IRC if unsure where to place a patch.
1122 @c TODO: It would be good with badges on the website that tracks these
1123 @c branches. Or maybe even a status page.
1126 @cindex determinism, of build processes
1127 @cindex reproducible builds, checking
1128 Check whether the package's build process is deterministic. This
1129 typically means checking whether an independent build of the package
1130 yields the exact same result that you obtained, bit for bit.
1132 A simple way to do that is by building the same package several times in
1133 a row on your machine (@pxref{Invoking guix build}):
1136 guix build --rounds=2 my-package
1139 This is enough to catch a class of common non-determinism issues, such
1140 as timestamps or randomly-generated output in the build result.
1142 Another option is to use @command{guix challenge} (@pxref{Invoking guix
1143 challenge}). You may run it once the package has been committed and
1144 built by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
1145 result as you did. Better yet: Find another machine that can build it
1146 and run @command{guix publish}. Since the remote build machine is
1147 likely different from yours, this can catch non-determinism issues
1148 related to the hardware---e.g., use of different instruction set
1149 extensions---or to the operating system kernel---e.g., reliance on
1150 @code{uname} or @file{/proc} files.
1153 When writing documentation, please use gender-neutral wording when
1154 referring to people, such as
1155 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
1156 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
1159 Verify that your patch contains only one set of related changes.
1160 Bundling unrelated changes together makes reviewing harder and slower.
1162 Examples of unrelated changes include the addition of several packages,
1163 or a package update along with fixes to that package.
1166 Please follow our code formatting rules, possibly running the
1167 @command{etc/indent-code.el} script to do that automatically for you
1168 (@pxref{Formatting Code}).
1171 When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
1172 Use reliable URLs, not generated ones. For instance, GitHub archives are not
1173 necessarily identical from one generation to the next, so in this case it's
1174 often better to clone the repository. Don't use the @command{name} field in
1175 the URL: it is not very useful and if the name changes, the URL will probably
1179 Check if Guix builds (@pxref{Building from Git}) and address the
1180 warnings, especially those about use of undefined symbols.
1183 Make sure your changes do not break Guix and simulate a @code{guix pull} with:
1185 guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
1190 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
1191 a subject, if your patch is to be applied on a branch other than
1192 @code{master}, say @code{core-updates}, specify it in the subject like
1193 @samp{[PATCH core-updates] @dots{}}. You may use your email client or
1194 the @command{git send-email} command (@pxref{Sending a Patch Series}).
1195 We prefer to get patches in plain text messages, either inline or as
1196 MIME attachments. You are advised to pay attention if your email client
1197 changes anything like line breaks or indentation which could potentially
1200 Expect some delay when you submit your very first patch to
1201 @email{guix-patches@@gnu.org}. You have to wait until you get an
1202 acknowledgement with the assigned tracking number. Future acknowledgements
1203 should not be delayed.
1205 When a bug is resolved, please close the thread by sending an email to
1206 @email{@var{NNN}-done@@debbugs.gnu.org}.
1208 @unnumberedsubsec Sending a Patch Series
1209 @anchor{Sending a Patch Series}
1210 @cindex patch series
1211 @cindex @code{git send-email}
1212 @cindex @code{git-send-email}
1214 When sending a patch series (e.g., using @code{git send-email}), please
1215 first send one message to @email{guix-patches@@gnu.org}, and then send
1216 subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
1217 they are kept together. See
1218 @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
1219 for more information. You can install @command{git send-email} with
1220 @command{guix install git:send-email}.
1221 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
1223 @node Tracking Bugs and Patches
1224 @section Tracking Bugs and Patches
1226 @cindex bug reports, tracking
1227 @cindex patch submissions, tracking
1228 @cindex issue tracking
1229 @cindex Debbugs, issue tracking system
1230 Bug reports and patch submissions are currently tracked using the
1231 Debbugs instance at @uref{https://bugs.gnu.org}. Bug reports are filed
1232 against the @code{guix} ``package'' (in Debbugs parlance), by sending
1233 email to @email{bug-guix@@gnu.org}, while patch submissions are filed
1234 against the @code{guix-patches} package by sending email to
1235 @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
1237 A web interface (actually @emph{two} web interfaces!) are available to
1242 @url{https://issues.guix.gnu.org} provides a pleasant
1243 interface@footnote{The web interface at
1244 @url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
1245 software written in Guile, and you can help! See
1246 @url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} to browse
1247 bug reports and patches, and to participate in discussions;
1249 @url{https://bugs.gnu.org/guix} lists bug reports;
1251 @url{https://bugs.gnu.org/guix-patches} lists patch submissions.
1254 To view discussions related to issue number @var{n}, go to
1255 @indicateurl{https://issues.guix.gnu.org/@var{n}} or
1256 @indicateurl{https://bugs.gnu.org/@var{n}}.
1258 If you use Emacs, you may find it more convenient to interact with
1259 issues using @file{debbugs.el}, which you can install with:
1262 guix install emacs-debbugs
1265 For example, to list all open issues on @code{guix-patches}, hit:
1268 @kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
1271 @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
1275 @section Commit Access
1277 @cindex commit access, for developers
1278 For frequent contributors, having write access to the repository is
1279 convenient. When you deem it necessary, consider applying for commit
1280 access by following these steps:
1284 Find three committers who would vouch for you. You can view the list of
1286 @url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Each
1287 of them should email a statement to @email{guix-maintainers@@gnu.org} (a
1288 private alias for the collective of maintainers), signed with their
1291 Committers are expected to have had some interactions with you as a
1292 contributor and to be able to judge whether you are sufficiently
1293 familiar with the project's practices. It is @emph{not} a judgment on
1294 the value of your work, so a refusal should rather be interpreted as
1295 ``let's try again later''.
1298 Send @email{guix-maintainers@@gnu.org} a message stating your intent,
1299 listing the three committers who support your application, signed with
1300 the OpenPGP key you will use to sign commits, and giving its fingerprint
1301 (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
1302 introduction to public-key cryptography with GnuPG.
1304 @c See <https://sha-mbles.github.io/>.
1305 Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
1306 signatures, which is known to be unsafe since 2019, for instance by
1307 adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG
1308 Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):
1315 Maintainers ultimately decide whether to grant you commit access,
1316 usually following your referrals' recommendation.
1319 @cindex OpenPGP, signed commits
1320 If and once you've been given access, please send a message to
1321 @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
1322 you will use to sign commits (do that before pushing your first commit).
1323 That way, everyone can notice and ensure you control that OpenPGP key.
1325 @quotation Important
1326 Before you can push for the first time, maintainers must:
1330 add your OpenPGP key to the @code{keyring} branch;
1332 add your OpenPGP fingerprint to the @file{.guix-authorizations} file of
1333 the branch(es) you will commit to.
1338 Make sure to read the rest of this section and... profit!
1342 Maintainers are happy to give commit access to people who have been
1343 contributing for some time and have a track record---don't be shy and
1344 don't underestimate your work!
1346 However, note that the project is working towards a more automated patch
1347 review and merging system, which, as a consequence, may lead us to have
1348 fewer people with commit access to the main repository. Stay tuned!
1351 If you get commit access, please make sure to follow
1352 the policy below (discussions of the policy can take place on
1353 @email{guix-devel@@gnu.org}).
1355 Non-trivial patches should always be posted to
1356 @email{guix-patches@@gnu.org} (trivial patches include fixing typos,
1357 etc.). This mailing list fills the patch-tracking database
1358 (@pxref{Tracking Bugs and Patches}).
1360 For patches that just add a new package, and a simple one, it's OK to
1361 commit, if you're confident (which means you successfully built it in a
1362 chroot setup, and have done a reasonable copyright and license
1363 auditing). Likewise for package upgrades, except upgrades that trigger
1364 a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a
1365 mailing list for commit notifications (@email{guix-commits@@gnu.org}),
1366 so people can notice. Before pushing your changes, make sure to run
1367 @code{git pull --rebase}.
1369 All commits that are pushed to the central repository on Savannah must
1370 be signed with an OpenPGP key, and the public key should be uploaded to
1371 your user account on Savannah and to public key servers, such as
1372 @code{keys.openpgp.org}. To configure Git to automatically sign
1376 git config commit.gpgsign true
1377 git config user.signingkey CABBA6EA1DC0FF33
1380 You can prevent yourself from accidentally pushing unsigned commits to
1381 Savannah by using the pre-push Git hook called located at
1382 @file{etc/git/pre-push}:
1385 cp etc/git/pre-push .git/hooks/pre-push
1388 When pushing a commit on behalf of somebody else, please add a
1389 @code{Signed-off-by} line at the end of the commit log message---e.g.,
1390 with @command{git am --signoff}. This improves tracking of who did
1393 When adding channel news entries (@pxref{Channels, Writing Channel
1394 News}), make sure they are well-formed by running the following command
1395 right before pushing:
1398 make check-channel-news
1401 For anything else, please post to @email{guix-patches@@gnu.org} and
1402 leave time for a review, without committing anything (@pxref{Submitting
1403 Patches}). If you didn’t receive any reply after two weeks, and if
1404 you're confident, it's OK to commit.
1406 That last part is subject to being adjusted, allowing individuals to commit
1407 directly on non-controversial changes on parts they’re familiar with.
1409 In order to reduce the possibility of mistakes, committers will have
1410 their Savannah account removed from the Guix Savannah project and their
1411 key removed from @file{.guix-authorizations} after 12 months of
1412 inactivity; they can ask to regain commit access by emailing the
1413 maintainers, without going through the vouching process.
1415 One last thing: the project keeps moving forward because committers not
1416 only push their own awesome changes, but also offer some of their time
1417 @emph{reviewing} and pushing other people's changes. As a committer,
1418 you're welcome to use your expertise and commit rights to help other
1421 @node Updating the Guix Package
1422 @section Updating the Guix Package
1424 @cindex update-guix-package, updating the guix package
1425 It is sometimes desirable to update the @code{guix} package itself (the
1426 package defined in @code{(gnu packages package-management)}), for
1427 example to make new daemon features available for use by the
1428 @code{guix-service-type} service type. In order to simplify this task,
1429 the following command can be used:
1432 make update-guix-package
1435 The @code{update-guix-package} make target will use the last known
1436 @emph{commit} corresponding to @code{HEAD} in your Guix checkout,
1437 compute the hash of the Guix sources corresponding to that commit and
1438 update the @code{commit}, @code{revision} and hash of the @code{guix}
1441 To validate that the updated @code{guix} package hashes are correct and
1442 that it can be built successfully, the following command can be run from
1443 the directory of your Guix checkout:
1446 ./pre-inst-env guix build guix
1449 To guard against accidentally updating the @code{guix} package to a
1450 commit that others can't refer to, a check is made that the commit used
1451 has already been pushed to the Savannah-hosted Guix git repository.
1453 This check can be disabled, @emph{at your own peril}, by setting the
1454 @code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When
1455 this variable is set, the updated package source is also added to the
1456 store. This is used as part of the release process of Guix.
1461 @cindex native language support
1462 @node Translating Guix
1463 @section Translating Guix
1465 Writing code and packages is not the only way to provide a meaningful
1466 contribution to Guix. Translating to a language you speak is another
1467 example of a valuable contribution you can make. This section is designed
1468 to describe the translation process. It gives you advice on how you can
1469 get involved, what can be translated, what mistakes you should avoid and
1470 what we can do to help you!
1472 Guix is a big project that has multiple components that can be translated.
1473 We coordinate the translation effort on a
1474 @uref{https://translate.fedoraproject.org/projects/guix/,Weblate instance}
1475 hosted by our friends at Fedora. You will need an account to submit
1478 Some of the software packaged in Guix also contain translations. We do not
1479 host a translation platform for them. If you want to translate a package
1480 provided by Guix, you should contact their developers or find the information
1481 on their website. As an example, you can find the homepage of the
1482 @code{hello} package by typing @code{guix show hello}. On the ``homepage''
1483 line, you will see @url{https://www.gnu.org/software/hello/} as the homepage.
1485 Many GNU and non-GNU packages can be translated on the
1486 @uref{https://translationproject.org,Translation Project}. Some projects
1487 with multiple components have their own platform. For instance, GNOME has
1488 its own platform, @uref{https://l10n.gnome.org/,Damned Lies}.
1490 Guix has five components hosted on Weblate.
1493 @item @code{guix} contains all the strings from the Guix software (the
1494 guided system installer, the package manager, etc), excluding packages.
1495 @item @code{packages} contains the synopsis (single-sentence description
1496 of a package) and description (longer description) of packages in Guix.
1497 @item @code{website} contains the official Guix website, except for
1498 blog posts and multimedia content.
1499 @item @code{documentation-manual} corresponds to this manual.
1500 @item @code{documentation-cookbook} is the component for the cookbook.
1503 @subsubheading General Directions
1505 Once you get an account, you should be able to select a component from
1506 @uref{https://translate.fedoraproject.org/projects/guix/,the guix project},
1507 and select a language. If your language does not appear in the list, go
1508 to the bottom and click on the ``Start new translation'' button. Select
1509 the language you want to translate to from the list, to start your new
1512 Like lots of other free software packages, Guix uses
1513 @uref{https://www.gnu.org/software/gettext,GNU Gettext} for its translations,
1514 with which translatable strings are extracted from the source code to so-called
1517 Even though PO files are text files, changes should not be made with a text
1518 editor but with PO editing software. Weblate integrates PO editing
1519 functionality. Alternatively, translators can use any of various
1520 free-software tools for filling in translations, of which
1521 @uref{https://poedit.net/,Poedit} is one example, and (after logging in)
1522 @uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed
1523 file. There is also a special
1524 @uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of GNU
1525 Emacs. Over time translators find out what software they are happy with and
1526 what features they need.
1528 On Weblate, you will find various links to the editor, that will show various
1529 subsets (or all) of the strings. Have a look around and at the
1530 @uref{https://docs.weblate.org/en/latest/,documentation} to familiarize
1531 yourself with the platform.
1533 @subsubheading Translation Components
1535 In this section, we provide more detailed guidance on the translation
1536 process, as well as details on what you should or should not do. When in
1537 doubt, please contact us, we will be happy to help!
1541 Guix is written in the Guile programming language, and some strings contain
1542 special formatting that is interpreted by Guile. These special formatting
1543 should be highlighted by Weblate. They start with @code{~} followed by one
1546 When printing the string, Guile replaces the special formatting symbols with
1547 actual values. For instance, the string @samp{ambiguous package specification
1548 `~a'} would be substituted to contain said package specification instead of
1549 @code{~a}. To properly translate this string, you must keep the formatting
1550 code in your translation, although you can place it where it makes sense in
1551 your language. For instance, the French translation says @samp{spécification
1552 du paquet « ~a » ambiguë} because the adjective needs to be placed in the
1553 end of the sentence.
1555 If there are multiple formatting symbols, make sure to respect the order.
1556 Guile does not know in which order you intended the string to be read, so it
1557 will substitute the symbols in the same order as the English sentence.
1559 As an example, you cannot translate @samp{package '~a' has been superseded by
1560 '~a'} by @samp{'~a' superseeds package '~a'}, because the meaning would be
1561 reversed. If @var{foo} is superseded by @var{bar}, the translation would read
1562 @samp{'foo' superseeds package 'bar'}. To work around this problem, it
1563 is possible to use more advanced formatting to select a given piece of data,
1564 instead of following the default English order. @xref{Formatted Output,,,
1565 guile, GNU Guile Reference Manual}, for more information on formatting in Guile.
1569 Package descriptions occasionally contain Texinfo markup (@pxref{Synopses
1570 and Descriptions}). Texinfo markup looks like @samp{@@code@{rm -rf@}},
1571 @samp{@@emph@{important@}}, etc. When translating, please leave markup as is.
1573 The characters after ``@@'' form the name of the markup, and the text between
1574 ``@{'' and ``@}'' is its content. In general, you should not translate the
1575 content of markup like @code{@@code}, as it contains literal code that do not
1576 change with language. You can translate the content of formatting markup such
1577 as @code{@@emph}, @code{@@i}, @code{@@itemize}, @code{@@item}. However, do
1578 not translate the name of the markup, or it will not be recognized. Do
1579 not translate the word after @code{@@end}, it is the name of the markup that
1580 is closed at this position (e.g.@: @code{@@itemize ... @@end itemize}).
1582 @item documentation-manual and documentation-cookbook
1584 The first step to ensure a successful translation of the manual is to find
1585 and translate the following strings @emph{first}:
1588 @item @code{version.texi}: Translate this string as @code{version-xx.texi},
1589 where @code{xx} is your language code (the one shown in the URL on
1591 @item @code{contributing.texi}: Translate this string as
1592 @code{contributing.xx.texi}, where @code{xx} is the same language code.
1593 @item @code{Top}: Do not translate this string, it is important for Texinfo.
1594 If you translate it, the document will be empty (missing a Top node).
1595 Please look for it, and register @code{Top} as its translation.
1598 Translating these strings first ensure we can include your translation in
1599 the guix repository without breaking the make process or the
1600 @command{guix pull} machinery.
1602 The manual and the cookbook both use Texinfo. As for @code{packages}, please
1603 keep Texinfo markup as is. There are more possible markup types in the manual
1604 than in the package descriptions. In general, do not translate the content
1605 of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value}, etc. You
1606 should translate the content of formatting markup such as @code{@@emph},
1609 The manual contains sections that can be referred to by name by @code{@@ref},
1610 @code{@@xref} and @code{@@pxref}. We have a mechanism in place so you do
1611 not have to translate their content. If you keep the English title, we will
1612 automatically replace it with your translation of that title. This ensures
1613 that Texinfo will always be able to find the node. If you decide to change
1614 the translation of the title, the references will automatically be updated
1615 and you will not have to update them all yourself.
1617 When translating references from the cookbook to the manual, you need to
1618 replace the name of the manual and the name of the section. For instance,
1619 to translate @code{@@pxref@{Defining Packages,,, guix, GNU Guix Reference
1620 Manual@}}, you would replace @code{Defining Packages} with the title of that
1621 section in the translated manual @emph{only} if that title is translated.
1622 If the title is not translated in your language yet, do not translate it here,
1623 or the link will be broken. Replace @code{guix} with @code{guix.xx} where
1624 @code{xx} is your language code. @code{GNU Guix Reference Manual} is the
1625 text of the link. You can translate it however you wish.
1629 The website pages are written using SXML, an s-expression version of HTML,
1630 the basic language of the web. We have a process to extract translatable
1631 strings from the source, and replace complex s-expressions with a more familiar
1632 XML markup, where each markup is numbered. Translators can arbitrarily change
1633 the ordering, as in the following example.
1636 #. TRANSLATORS: Defining Packages is a section name
1637 #. in the English (en) manual.
1638 #: apps/base/templates/about.scm:64
1639 msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
1640 msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
1643 Note that you need to include the same markups. You cannot skip any.
1646 In case you make a mistake, the component might fail to build properly with your
1647 language, or even make guix pull fail. To prevent that, we have a process
1648 in place to check the content of the files before pushing to our repository.
1649 We will not be able to update the translation for your language in Guix, so
1650 we will notify you (through weblate and/or by email) so you get a chance to
1653 @subsubheading Outside of Weblate
1655 Currently, some parts of Guix cannot be translated on Weblate, help wanted!
1658 @item @command{guix pull} news can be translated in @file{news.scm}, but is not
1659 available from Weblate. If you want to provide a translation, you
1660 can prepare a patch as described above, or simply send us your
1661 translation with the name of the news entry you translated and your
1662 language. @xref{Writing Channel News}, for more information about
1664 @item Guix blog posts cannot currently be translated.
1665 @item The installer script (for foreign distributions) is entirely in English.
1666 @item Some of the libraries Guix uses cannot be translated or are translated
1667 outside of the Guix project. Guile itself is not internationalized.
1668 @item Other manuals linked from this manual or the cookbook might not be
1672 @subsubheading Translation Infrastructure
1674 Weblate is backed by a git repository from which it discovers new strings to
1675 translate and pushes new and updated translations. Normally, it would be
1676 enough to give it commit access to our repositories. However, we decided
1677 to use a separate repository for two reasons. First, we would have to give
1678 Weblate commit access and authorize its signing key, but we do not trust it
1679 in the same way we trust guix developers, especially since we do not manage
1680 the instance ourselves. Second, if translators mess something up, it can
1681 break the generation of the website and/or guix pull for all our users,
1682 independently of their language.
1684 For these reasons, we use a dedicated repository to host translations, and we
1685 synchronize it with our guix and artworks repositories after checking no issue
1686 was introduced in the translation.
1688 Developers can download the latest PO files from weblate in the Guix
1689 repository by running the @command{make download-po} command. It will
1690 automatically download the latest files from weblate, reformat them to a
1691 canonical form, and check they do not contain issues. The manual needs to be
1692 built again to check for additional issues that might crash Texinfo.
1694 Before pushing new translation files, developers should add them to the
1695 make machinery so the translations are actually available. The process
1696 differs for the various components.
1699 @item New po files for the @code{guix} and @code{packages} components must
1700 be registered by adding the new language to @file{po/guix/LINGUAS} or
1701 @file{po/packages/LINGUAS}.
1702 @item New po files for the @code{documentation-manual} component must be
1703 registered by adding the file name to @code{DOC_PO_FILES} in
1704 @file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
1705 @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
1706 @file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
1707 @code{TRANSLATED_INFO} also in @file{doc/local.mk}.
1708 @item New po files for the @code{documentation-cookbook} component must be
1709 registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
1710 @file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
1711 manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
1712 @file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also
1713 in @file{doc/local.mk}.
1714 @item New po files for the @code{website} component must be added to the
1715 @code{guix-artwork} repository, in @file{website/po/}.
1716 @file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must
1717 be updated accordingly (see @file{website/i18n-howto.txt} for more
1718 information on the process).