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{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
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). It is best to use the full commit identifiers in
536 @code{origin}s, though, to avoid ambiguities. A typical package
537 definition may look like this:
541 (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
542 (revision "1")) ;Guix package revision
544 (version (git-version "0.9" revision commit))
548 (url "git://example.org/my-package.git")
550 (sha256 (base32 "1mbikn@dots{}"))
551 (file-name (git-file-name name version))))
556 @node Synopses and Descriptions
557 @subsection Synopses and Descriptions
559 @cindex package description
560 @cindex package synopsis
561 As we have seen before, each package in GNU@tie{}Guix includes a
562 synopsis and a description (@pxref{Defining Packages}). Synopses and
563 descriptions are important: They are what @command{guix package
564 --search} searches, and a crucial piece of information to help users
565 determine whether a given package suits their needs. Consequently,
566 packagers should pay attention to what goes into them.
568 Synopses must start with a capital letter and must not end with a
569 period. They must not start with ``a'' or ``the'', which usually does
570 not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
571 tool that frobs files''. The synopsis should say what the package
572 is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
573 used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
574 matching a pattern''.
576 Keep in mind that the synopsis must be meaningful for a very wide
577 audience. For example, ``Manipulate alignments in the SAM format''
578 might make sense for a seasoned bioinformatics researcher, but might be
579 fairly unhelpful or even misleading to a non-specialized audience. It
580 is a good idea to come up with a synopsis that gives an idea of the
581 application domain of the package. In this example, this might give
582 something like ``Manipulate nucleotide sequence alignments'', which
583 hopefully gives the user a better idea of whether this is what they are
586 Descriptions should take between five and ten lines. Use full
587 sentences, and avoid using acronyms without first introducing them.
588 Please avoid marketing phrases such as ``world-leading'',
589 ``industrial-strength'', and ``next-generation'', and avoid superlatives
590 like ``the most advanced''---they are not helpful to users looking for a
591 package and may even sound suspicious. Instead, try to be factual,
592 mentioning use cases and features.
594 @cindex Texinfo markup, in package descriptions
595 Descriptions can include Texinfo markup, which is useful to introduce
596 ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
597 hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
598 should be careful when using some characters for example @samp{@@} and
599 curly braces which are the basic special characters in Texinfo
600 (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
601 such as @command{guix package --show} take care of rendering it
604 Synopses and descriptions are translated by volunteers
605 @uref{https://translate.fedoraproject.org/projects/guix/packages, at
606 Weblate} so that as many users as possible can read them in
607 their native language. User interfaces search them and display them in
608 the language specified by the current locale.
610 To allow @command{xgettext} to extract them as translatable strings,
611 synopses and descriptions @emph{must be literal strings}. This means
612 that you cannot use @code{string-append} or @code{format} to construct
618 (synopsis "This is translatable")
619 (description (string-append "This is " "*not*" " translatable.")))
622 Translation is a lot of work so, as a packager, please pay even more
623 attention to your synopses and descriptions as every change may entail
624 additional work for translators. In order to help them, it is possible
625 to make recommendations or instructions visible to them by inserting
626 special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
630 ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
631 (description "ARandR is designed to provide a simple visual front end
632 for the X11 resize-and-rotate (RandR) extension. @dots{}")
635 @node Snippets versus Phases
636 @subsection Snippets versus Phases
638 @cindex snippets, when to use
639 The boundary between using an origin snippet versus a build phase to
640 modify the sources of a package can be elusive. Origin snippets are
641 typically used to remove unwanted files such as bundled libraries,
642 nonfree sources, or to apply simple substitutions. The source derived
643 from an origin should produce a source that can be used to build the
644 package on any system that the upstream package supports (i.e., act as
645 the corresponding source). In particular, origin snippets must not
646 embed store items in the sources; such patching should rather be done
647 using build phases. Refer to the @code{origin} record documentation for
648 more information (@pxref{origin Reference}).
651 @subsection Emacs Packages
653 @cindex emacs, packaging
654 @cindex elisp, packaging
655 Emacs packages should preferably use the Emacs build system
656 (@pxref{emacs-build-system}), for uniformity and the benefits provided
657 by its build phases, such as the auto-generation of the autoloads file
658 and the byte compilation of the sources. Because there is no
659 standardized way to run a test suite for Emacs packages, tests are
660 disabled by default. When a test suite is available, it should be
661 enabled by setting the @code{#:tests?} argument to @code{#true}. By
662 default, the command to run the test is @command{make check}, but any
663 command can be specified via the @code{#:test-command} argument. The
664 @code{#:test-command} argument expects a list containing a command and
665 its arguments, to be invoked during the @code{check} phase.
667 The Elisp dependencies of Emacs packages are typically provided as
668 @code{propagated-inputs} when required at run time. As for other
669 packages, build or test dependencies should be specified as
670 @code{native-inputs}.
672 Emacs packages sometimes depend on resources directories that should be
673 installed along the Elisp files. The @code{#:include} argument can be
674 used for that purpose, by specifying a list of regexps to match. The
675 best practice when using the @code{#:include} argument is to extend
676 rather than override its default value (accessible via the
677 @code{%default-include} variable). As an example, a yasnippet extension
678 package typically include a @file{snippets} directory, which could be
679 copied to the installation directory using:
682 #:include (cons "^snippets/" %default-include))
685 When encountering problems, it is wise to check for the presence of the
686 @code{Package-Requires} extension header in the package main source
687 file, and whether any dependencies and their versions listed therein are
691 @subsection Python Modules
694 We currently package Python 2 and Python 3, under the Scheme variable names
695 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
696 To avoid confusion and naming clashes with other programming languages, it
697 seems desirable that the name of a package for a Python module contains
698 the word @code{python}.
700 Some modules are compatible with only one version of Python, others with
701 both. If the package Foo is compiled with Python 3, we name it
702 @code{python-foo}. If it is compiled with Python 2, we name it
703 @code{python2-foo}. Packages should be added when they are necessary;
704 we don't add Python 2 variants of the package unless we are going to use
707 If a project already contains the word @code{python}, we drop this;
708 for instance, the module python-dateutil is packaged under the names
709 @code{python-dateutil} and @code{python2-dateutil}. If the project name
710 starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
713 @subsubsection Specifying Dependencies
714 @cindex inputs, for Python packages
716 Dependency information for Python packages is usually available in the
717 package source tree, with varying degrees of accuracy: in the
718 @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
720 Your mission, when writing a recipe for a Python package, is to map
721 these dependencies to the appropriate type of ``input'' (@pxref{package
722 Reference, inputs}). Although the @code{pypi} importer normally does a
723 good job (@pxref{Invoking guix import}), you may want to check the
724 following check list to determine which dependency goes where.
729 We currently package Python 2 with @code{setuptools} and @code{pip}
730 installed like Python 3.4 has per default. Thus you don't need to
731 specify either of these as an input. @command{guix lint} will warn you
735 Python dependencies required at run time go into
736 @code{propagated-inputs}. They are typically defined with the
737 @code{install_requires} keyword in @file{setup.py}, or in the
738 @file{requirements.txt} file.
741 Python packages required only at build time---e.g., those listed with
742 the @code{setup_requires} keyword in @file{setup.py}---or only for
743 testing---e.g., those in @code{tests_require}---go into
744 @code{native-inputs}. The rationale is that (1) they do not need to be
745 propagated because they are not needed at run time, and (2) in a
746 cross-compilation context, it's the ``native'' input that we'd want.
748 Examples are the @code{pytest}, @code{mock}, and @code{nose} test
749 frameworks. Of course if any of these packages is also required at
750 run-time, it needs to go to @code{propagated-inputs}.
753 Anything that does not fall in the previous categories goes to
754 @code{inputs}, for example programs or C libraries required for building
755 Python packages containing C extensions.
758 If a Python package has optional dependencies (@code{extras_require}),
759 it is up to you to decide whether to add them or not, based on their
760 usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
767 @subsection Perl Modules
770 Perl programs standing for themselves are named as any other package,
771 using the lowercase upstream name.
772 For Perl packages containing a single class, we use the lowercase class name,
773 replace all occurrences of @code{::} by dashes and prepend the prefix
775 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
776 Modules containing several classes keep their lowercase upstream name and
777 are also prepended by @code{perl-}. Such modules tend to have the word
778 @code{perl} somewhere in their name, which gets dropped in favor of the
779 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
783 @subsection Java Packages
786 Java programs standing for themselves are named as any other package,
787 using the lowercase upstream name.
789 To avoid confusion and naming clashes with other programming languages,
790 it is desirable that the name of a package for a Java package is
791 prefixed with @code{java-}. If a project already contains the word
792 @code{java}, we drop this; for instance, the package @code{ngsjava} is
793 packaged under the name @code{java-ngs}.
795 For Java packages containing a single class or a small class hierarchy,
796 we use the lowercase class name, replace all occurrences of @code{.} by
797 dashes and prepend the prefix @code{java-}. So the class
798 @code{apache.commons.cli} becomes package
799 @code{java-apache-commons-cli}.
803 @subsection Rust Crates
806 Rust programs standing for themselves are named as any other package, using the
807 lowercase upstream name.
809 To prevent namespace collisions we prefix all other Rust packages with the
810 @code{rust-} prefix. The name should be changed to lowercase as appropriate and
811 dashes should remain in place.
813 In the rust ecosystem it is common for multiple incompatible versions of a
814 package to be used at any given time, so all package definitions should have a
815 versioned suffix. The versioned suffix is the left-most non-zero digit (and
816 any leading zeros, of course). This follows the ``caret'' version scheme
817 intended by Cargo. Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
819 Because of the difficulty in reusing rust packages as pre-compiled inputs for
820 other packages the Cargo build system (@pxref{Build Systems,
821 @code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
822 @code{cargo-development-inputs} keywords as build system arguments. It would be
823 helpful to think of these as similar to @code{propagated-inputs} and
824 @code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies}
825 should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
826 @code{#:cargo-development-inputs}. If a Rust package links to other libraries
827 then the standard placement in @code{inputs} and the like should be used.
829 Care should be taken to ensure the correct version of dependencies are used; to
830 this end we try to refrain from skipping the tests or using @code{#:skip-build?}
831 when possible. Of course this is not always possible, as the package may be
832 developed for a different Operating System, depend on features from the Nightly
833 Rust compiler, or the test suite may have atrophied since it was released.
840 For fonts that are in general not installed by a user for typesetting
841 purposes, or that are distributed as part of a larger software package,
842 we rely on the general packaging rules for software; for instance, this
843 applies to the fonts delivered as part of the X.Org system or fonts that
844 are part of TeX Live.
846 To make it easier for a user to search for fonts, names for other packages
847 containing only fonts are constructed as follows, independently of the
848 upstream package name.
850 The name of a package containing only one font family starts with
851 @code{font-}; it is followed by the foundry name and a dash @code{-}
852 if the foundry is known, and the font family name, in which spaces are
853 replaced by dashes (and as usual, all upper case letters are transformed
855 For example, the Gentium font family by SIL is packaged under the name
856 @code{font-sil-gentium}.
858 For a package containing several font families, the name of the collection
859 is used in the place of the font family name.
860 For instance, the Liberation fonts consist of three families,
861 Liberation Sans, Liberation Serif and Liberation Mono.
862 These could be packaged separately under the names
863 @code{font-liberation-sans} and so on; but as they are distributed together
864 under a common name, we prefer to package them together as
865 @code{font-liberation}.
867 In the case where several formats of the same font family or font collection
868 are packaged separately, a short form of the format, prepended by a dash,
869 is added to the package name. We use @code{-ttf} for TrueType fonts,
870 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
875 @section Coding Style
877 In general our code follows the GNU Coding Standards (@pxref{Top,,,
878 standards, GNU Coding Standards}). However, they do not say much about
879 Scheme, so here are some additional rules.
882 * Programming Paradigm:: How to compose your elements.
883 * Modules:: Where to store your code?
884 * Data Types and Pattern Matching:: Implementing data structures.
885 * Formatting Code:: Writing conventions.
888 @node Programming Paradigm
889 @subsection Programming Paradigm
891 Scheme code in Guix is written in a purely functional style. One
892 exception is code that involves input/output, and procedures that
893 implement low-level concepts, such as the @code{memoize} procedure.
898 Guile modules that are meant to be used on the builder side must live in
899 the @code{(guix build @dots{})} name space. They must not refer to
900 other Guix or GNU modules. However, it is OK for a ``host-side'' module
901 to use a build-side module.
903 Modules that deal with the broader GNU system should be in the
904 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
906 @node Data Types and Pattern Matching
907 @subsection Data Types and Pattern Matching
909 The tendency in classical Lisp is to use lists to represent everything,
910 and then to browse them ``by hand'' using @code{car}, @code{cdr},
911 @code{cadr}, and co. There are several problems with that style,
912 notably the fact that it is hard to read, error-prone, and a hindrance
913 to proper type error reports.
915 Guix code should define appropriate data types (for instance, using
916 @code{define-record-type*}) rather than abuse lists. In addition, it
917 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
918 especially when matching lists (@pxref{Pattern Matching,,, guile, GNU
919 Guile Reference Manual}).
921 @node Formatting Code
922 @subsection Formatting Code
924 @cindex formatting code
926 When writing Scheme code, we follow common wisdom among Scheme
927 programmers. In general, we follow the
928 @url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
929 Style Rules}. This document happens to describe the conventions mostly
930 used in Guile’s code too. It is very thoughtful and well written, so
933 Some special forms introduced in Guix, such as the @code{substitute*}
934 macro, have special indentation rules. These are defined in the
935 @file{.dir-locals.el} file, which Emacs automatically uses. Also note
936 that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
937 highlights Guix code properly (@pxref{Development,,, emacs-guix, The
938 Emacs-Guix Reference Manual}).
940 @cindex indentation, of code
941 @cindex formatting, of code
942 If you do not use Emacs, please make sure to let your editor knows these
943 rules. To automatically indent a package definition, you can also run:
946 ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
950 This automatically indents the definition of @var{package} in
951 @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
952 indent a whole file, omit the second argument:
955 ./etc/indent-code.el gnu/services/@var{file}.scm
958 @cindex Vim, Scheme code editing
959 If you are editing code with Vim, we recommend that you run @code{:set
960 autoindent} so that your code is automatically indented as you type.
962 @uref{https://www.vim.org/scripts/script.php?script_id=3998,
963 @code{paredit.vim}} may help you deal with all these parentheses.
965 We require all top-level procedures to carry a docstring. This
966 requirement can be relaxed for simple private procedures in the
967 @code{(guix build @dots{})} name space, though.
969 Procedures should not have more than four positional parameters. Use
970 keyword parameters for procedures that take more than four parameters.
973 @node Submitting Patches
974 @section Submitting Patches
976 Development is done using the Git distributed version control system.
977 Thus, access to the repository is not strictly necessary. We welcome
978 contributions in the form of patches as produced by @code{git
979 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
980 Seasoned Guix developers may also want to look at the section on commit
981 access (@pxref{Commit Access}).
983 This mailing list is backed by a Debbugs instance, which allows us to
984 keep track of submissions (@pxref{Tracking Bugs and Patches}). Each
985 message sent to that mailing list gets a new tracking number assigned;
986 people can then follow up on the submission by sending email to
987 @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
988 number (@pxref{Sending a Patch Series}).
990 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
991 standards, GNU Coding Standards}); you can check the commit history for
994 Before submitting a patch that adds or modifies a package definition,
995 please run through this check list:
999 If the authors of the packaged software provide a cryptographic
1000 signature for the release tarball, make an effort to verify the
1001 authenticity of the archive. For a detached GPG signature file this
1002 would be done with the @code{gpg --verify} command.
1005 Take some time to provide an adequate synopsis and description for the
1006 package. @xref{Synopses and Descriptions}, for some guidelines.
1009 Run @code{guix lint @var{package}}, where @var{package} is the
1010 name of the new or modified package, and fix any errors it reports
1011 (@pxref{Invoking guix lint}).
1014 Make sure the package builds on your platform, using @code{guix build
1018 We recommend you also try building the package on other supported
1019 platforms. As you may not have access to actual hardware platforms, we
1020 recommend using the @code{qemu-binfmt-service-type} to emulate them. In
1021 order to enable it, add the following service to the list of services in
1022 your @code{operating-system} configuration:
1025 (service qemu-binfmt-service-type
1026 (qemu-binfmt-configuration
1027 (platforms (lookup-qemu-platforms "arm" "aarch64"))
1030 Then reconfigure your system.
1032 You can then build packages for different platforms by specifying the
1033 @code{--system} option. For example, to build the "hello" package for
1034 the armhf, aarch64, or mips64 architectures, you would run the following
1035 commands, respectively:
1037 guix build --system=armhf-linux --rounds=2 hello
1038 guix build --system=aarch64-linux --rounds=2 hello
1043 Make sure the package does not use bundled copies of software already
1044 available as separate packages.
1046 Sometimes, packages include copies of the source code of their
1047 dependencies as a convenience for users. However, as a distribution, we
1048 want to make sure that such packages end up using the copy we already
1049 have in the distribution, if there is one. This improves resource usage
1050 (the dependency is built and stored only once), and allows the
1051 distribution to make transverse changes such as applying security
1052 updates for a given software package in a single place and have them
1053 affect the whole system---something that bundled copies prevent.
1056 Take a look at the profile reported by @command{guix size}
1057 (@pxref{Invoking guix size}). This will allow you to notice references
1058 to other packages unwillingly retained. It may also help determine
1059 whether to split the package (@pxref{Packages with Multiple Outputs}),
1060 and which optional dependencies should be used. In particular, avoid adding
1061 @code{texlive} as a dependency: because of its extreme size, use
1062 the @code{texlive-tiny} package or @code{texlive-union} procedure instead.
1065 For important changes, check that dependent package (if applicable) are
1066 not affected by the change; @code{guix refresh --list-dependent
1067 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
1069 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
1070 @cindex branching strategy
1071 @cindex rebuild scheduling strategy
1072 Depending on the number of dependent packages and thus the amount of
1073 rebuilding induced, commits go to different branches, along these lines:
1076 @item 300 dependent packages or less
1077 @code{master} branch (non-disruptive changes).
1079 @item between 300 and 1,800 dependent packages
1080 @code{staging} branch (non-disruptive changes). This branch is intended
1081 to be merged in @code{master} every 6 weeks or so. Topical changes
1082 (e.g., an update of the GNOME stack) can instead go to a specific branch
1083 (say, @code{gnome-updates}).
1085 @item more than 1,800 dependent packages
1086 @code{core-updates} branch (may include major and potentially disruptive
1087 changes). This branch is intended to be merged in @code{master} every
1091 All these branches are @uref{@value{SUBSTITUTE-URL},
1092 tracked by our build farm} and merged into @code{master} once
1093 everything has been successfully built. This allows us to fix issues
1094 before they hit users, and to reduce the window during which pre-built
1095 binaries are not available.
1097 When we decide to start building the @code{staging} or
1098 @code{core-updates} branches, they will be forked and renamed with the
1099 suffix @code{-frozen}, at which time only bug fixes may be pushed to the
1100 frozen branches. The @code{core-updates} and @code{staging} branches
1101 will remain open to accept patches for the next cycle. Please ask on
1102 the mailing list or IRC if unsure where to place a patch.
1103 @c TODO: It would be good with badges on the website that tracks these
1104 @c branches. Or maybe even a status page.
1107 @cindex determinism, of build processes
1108 @cindex reproducible builds, checking
1109 Check whether the package's build process is deterministic. This
1110 typically means checking whether an independent build of the package
1111 yields the exact same result that you obtained, bit for bit.
1113 A simple way to do that is by building the same package several times in
1114 a row on your machine (@pxref{Invoking guix build}):
1117 guix build --rounds=2 my-package
1120 This is enough to catch a class of common non-determinism issues, such
1121 as timestamps or randomly-generated output in the build result.
1123 Another option is to use @command{guix challenge} (@pxref{Invoking guix
1124 challenge}). You may run it once the package has been committed and
1125 built by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
1126 result as you did. Better yet: Find another machine that can build it
1127 and run @command{guix publish}. Since the remote build machine is
1128 likely different from yours, this can catch non-determinism issues
1129 related to the hardware---e.g., use of different instruction set
1130 extensions---or to the operating system kernel---e.g., reliance on
1131 @code{uname} or @file{/proc} files.
1134 When writing documentation, please use gender-neutral wording when
1135 referring to people, such as
1136 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
1137 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
1140 Verify that your patch contains only one set of related changes.
1141 Bundling unrelated changes together makes reviewing harder and slower.
1143 Examples of unrelated changes include the addition of several packages,
1144 or a package update along with fixes to that package.
1147 Please follow our code formatting rules, possibly running the
1148 @command{etc/indent-code.el} script to do that automatically for you
1149 (@pxref{Formatting Code}).
1152 When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
1153 Use reliable URLs, not generated ones. For instance, GitHub archives are not
1154 necessarily identical from one generation to the next, so in this case it's
1155 often better to clone the repository. Don't use the @command{name} field in
1156 the URL: it is not very useful and if the name changes, the URL will probably
1160 Check if Guix builds (@pxref{Building from Git}) and address the
1161 warnings, especially those about use of undefined symbols.
1164 Make sure your changes do not break Guix and simulate a @code{guix pull} with:
1166 guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
1171 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
1172 a subject, if your patch is to be applied on a branch other than
1173 @code{master}, say @code{core-updates}, specify it in the subject like
1174 @samp{[PATCH core-updates] @dots{}}. You may use your email client or
1175 the @command{git send-email} command (@pxref{Sending a Patch Series}).
1176 We prefer to get patches in plain text messages, either inline or as
1177 MIME attachments. You are advised to pay attention if your email client
1178 changes anything like line breaks or indentation which could potentially
1181 When a bug is resolved, please close the thread by sending an email to
1182 @email{@var{NNN}-done@@debbugs.gnu.org}.
1184 @unnumberedsubsec Sending a Patch Series
1185 @anchor{Sending a Patch Series}
1186 @cindex patch series
1187 @cindex @code{git send-email}
1188 @cindex @code{git-send-email}
1190 When sending a patch series (e.g., using @code{git send-email}), please
1191 first send one message to @email{guix-patches@@gnu.org}, and then send
1192 subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
1193 they are kept together. See
1194 @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
1195 for more information. You can install @command{git send-email} with
1196 @command{guix install git:send-email}.
1197 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
1199 @node Tracking Bugs and Patches
1200 @section Tracking Bugs and Patches
1202 @cindex bug reports, tracking
1203 @cindex patch submissions, tracking
1204 @cindex issue tracking
1205 @cindex Debbugs, issue tracking system
1206 Bug reports and patch submissions are currently tracked using the
1207 Debbugs instance at @uref{https://bugs.gnu.org}. Bug reports are filed
1208 against the @code{guix} ``package'' (in Debbugs parlance), by sending
1209 email to @email{bug-guix@@gnu.org}, while patch submissions are filed
1210 against the @code{guix-patches} package by sending email to
1211 @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
1213 A web interface (actually @emph{two} web interfaces!) are available to
1218 @url{https://issues.guix.gnu.org} provides a pleasant
1219 interface@footnote{The web interface at
1220 @url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
1221 software written in Guile, and you can help! See
1222 @url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} to browse
1223 bug reports and patches, and to participate in discussions;
1225 @url{https://bugs.gnu.org/guix} lists bug reports;
1227 @url{https://bugs.gnu.org/guix-patches} lists patch submissions.
1230 To view discussions related to issue number @var{n}, go to
1231 @indicateurl{https://issues.guix.gnu.org/@var{n}} or
1232 @indicateurl{https://bugs.gnu.org/@var{n}}.
1234 If you use Emacs, you may find it more convenient to interact with
1235 issues using @file{debbugs.el}, which you can install with:
1238 guix install emacs-debbugs
1241 For example, to list all open issues on @code{guix-patches}, hit:
1244 @kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
1247 @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
1251 @section Commit Access
1253 @cindex commit access, for developers
1254 For frequent contributors, having write access to the repository is
1255 convenient. When you deem it necessary, consider applying for commit
1256 access by following these steps:
1260 Find three committers who would vouch for you. You can view the list of
1262 @url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Each
1263 of them should email a statement to @email{guix-maintainers@@gnu.org} (a
1264 private alias for the collective of maintainers), signed with their
1267 Committers are expected to have had some interactions with you as a
1268 contributor and to be able to judge whether you are sufficiently
1269 familiar with the project's practices. It is @emph{not} a judgment on
1270 the value of your work, so a refusal should rather be interpreted as
1271 ``let's try again later''.
1274 Send @email{guix-maintainers@@gnu.org} a message stating your intent,
1275 listing the three committers who support your application, signed with
1276 the OpenPGP key you will use to sign commits, and giving its fingerprint
1277 (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
1278 introduction to public-key cryptography with GnuPG.
1280 @c See <https://sha-mbles.github.io/>.
1281 Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
1282 signatures, which is known to be unsafe since 2019, for instance by
1283 adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG
1284 Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):
1291 Maintainers ultimately decide whether to grant you commit access,
1292 usually following your referrals' recommendation.
1295 @cindex OpenPGP, signed commits
1296 If and once you've been given access, please send a message to
1297 @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
1298 you will use to sign commits (do that before pushing your first commit).
1299 That way, everyone can notice and ensure you control that OpenPGP key.
1301 @quotation Important
1302 Before you can push for the first time, maintainers must:
1306 add your OpenPGP key to the @code{keyring} branch;
1308 add your OpenPGP fingerprint to the @file{.guix-authorizations} file of
1309 the branch(es) you will commit to.
1314 Make sure to read the rest of this section and... profit!
1318 Maintainers are happy to give commit access to people who have been
1319 contributing for some time and have a track record---don't be shy and
1320 don't underestimate your work!
1322 However, note that the project is working towards a more automated patch
1323 review and merging system, which, as a consequence, may lead us to have
1324 fewer people with commit access to the main repository. Stay tuned!
1327 If you get commit access, please make sure to follow
1328 the policy below (discussions of the policy can take place on
1329 @email{guix-devel@@gnu.org}).
1331 Non-trivial patches should always be posted to
1332 @email{guix-patches@@gnu.org} (trivial patches include fixing typos,
1333 etc.). This mailing list fills the patch-tracking database
1334 (@pxref{Tracking Bugs and Patches}).
1336 For patches that just add a new package, and a simple one, it's OK to
1337 commit, if you're confident (which means you successfully built it in a
1338 chroot setup, and have done a reasonable copyright and license
1339 auditing). Likewise for package upgrades, except upgrades that trigger
1340 a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a
1341 mailing list for commit notifications (@email{guix-commits@@gnu.org}),
1342 so people can notice. Before pushing your changes, make sure to run
1343 @code{git pull --rebase}.
1345 All commits that are pushed to the central repository on Savannah must
1346 be signed with an OpenPGP key, and the public key should be uploaded to
1347 your user account on Savannah and to public key servers, such as
1348 @code{keys.openpgp.org}. To configure Git to automatically sign
1352 git config commit.gpgsign true
1353 git config user.signingkey CABBA6EA1DC0FF33
1356 You can prevent yourself from accidentally pushing unsigned commits to
1357 Savannah by using the pre-push Git hook called located at
1358 @file{etc/git/pre-push}:
1361 cp etc/git/pre-push .git/hooks/pre-push
1364 When pushing a commit on behalf of somebody else, please add a
1365 @code{Signed-off-by} line at the end of the commit log message---e.g.,
1366 with @command{git am --signoff}. This improves tracking of who did
1369 When adding channel news entries (@pxref{Channels, Writing Channel
1370 News}), make sure they are well-formed by running the following command
1371 right before pushing:
1374 make check-channel-news
1377 For anything else, please post to @email{guix-patches@@gnu.org} and
1378 leave time for a review, without committing anything (@pxref{Submitting
1379 Patches}). If you didn’t receive any reply after two weeks, and if
1380 you're confident, it's OK to commit.
1382 That last part is subject to being adjusted, allowing individuals to commit
1383 directly on non-controversial changes on parts they’re familiar with.
1385 In order to reduce the possibility of mistakes, committers will have
1386 their Savannah account removed from the Guix Savannah project and their
1387 key removed from @file{.guix-authorizations} after 12 months of
1388 inactivity; they can ask to regain commit access by emailing the
1389 maintainers, without going through the vouching process.
1391 One last thing: the project keeps moving forward because committers not
1392 only push their own awesome changes, but also offer some of their time
1393 @emph{reviewing} and pushing other people's changes. As a committer,
1394 you're welcome to use your expertise and commit rights to help other
1397 @node Updating the Guix Package
1398 @section Updating the Guix Package
1400 @cindex update-guix-package, updating the guix package
1401 It is sometimes desirable to update the @code{guix} package itself (the
1402 package defined in @code{(gnu packages package-management)}), for
1403 example to make new daemon features available for use by the
1404 @code{guix-service-type} service type. In order to simplify this task,
1405 the following command can be used:
1408 make update-guix-package
1411 The @code{update-guix-package} make target will use the last known
1412 @emph{commit} corresponding to @code{HEAD} in your Guix checkout,
1413 compute the hash of the Guix sources corresponding to that commit and
1414 update the @code{commit}, @code{revision} and hash of the @code{guix}
1417 To validate that the updated @code{guix} package hashes are correct and
1418 that it can be built successfully, the following command can be run from
1419 the directory of your Guix checkout:
1422 ./pre-inst-env guix build guix
1425 To guard against accidentally updating the @code{guix} package to a
1426 commit that others can't refer to, a check is made that the commit used
1427 has already been pushed to the Savannah-hosted Guix git repository.
1429 This check can be disabled, @emph{at your own peril}, by setting the
1430 @code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When
1431 this variable is set, the updated package source is also added to the
1432 store. This is used as part of the release process of Guix.
1437 @cindex native language support
1438 @node Translating Guix
1439 @section Translating Guix
1441 Writing code and packages is not the only way to provide a meaningful
1442 contribution to Guix. Translating to a language you speak is another
1443 example of a valuable contribution you can make. This section is designed
1444 to describe the translation process. It gives you advice on how you can
1445 get involved, what can be translated, what mistakes you should avoid and
1446 what we can do to help you!
1448 Guix is a big project that has multiple components that can be translated.
1449 We coordinate the translation effort on a
1450 @uref{https://translate.fedoraproject.org/projects/guix/,Weblate instance}
1451 hosted by our friends at Fedora. You will need an account to submit
1454 Some of the software packaged in Guix also contain translations. We do not
1455 host a translation platform for them. If you want to translate a package
1456 provided by Guix, you should contact their developpers or find the information
1457 on their website. As an example, you can find the homepage of the
1458 @code{hello} package by typing @code{guix show hello}. On the ``homepage''
1459 line, you will see @url{https://www.gnu.org/software/hello/} as the homepage.
1461 Many GNU and non-GNU packages can be translated on the
1462 @uref{https://translationproject.org,Translation Project}. Some projects
1463 with multiple components have their own platform. For instance, GNOME has
1464 its own platform, @uref{https://l10n.gnome.org/,Damned Lies}.
1466 Guix has five components hosted on Weblate.
1469 @item @code{guix} contains all the strings from the Guix software (the
1470 guided system installer, the package manager, etc), excluding packages.
1471 @item @code{packages} contains the synopsis (single-sentence description
1472 of a package) and description (longer description) of packages in Guix.
1473 @item @code{website} contains the official Guix website, except for
1474 blog posts and multimedia content.
1475 @item @code{documentation-manual} corresponds to this manual.
1476 @item @code{documentation-cookbook} is the component for the cookbook.
1479 @subsubheading General Directions
1481 Once you get an account, you should be able to select a component from
1482 @uref{https://translate.fedoraproject.org/projects/guix/,the guix project},
1483 and select a language. If your language does not appear in the list, go
1484 to the bottom and click on the ``Start new translation'' button. Select
1485 the language you want to translate to from the list, to start your new
1488 Like lots of other free software packages, Guix uses
1489 @uref{https://www.gnu.org/software/gettext,GNU Gettext} for its translations,
1490 with which translatable strings are extracted from the source code to so-called
1493 Even though PO files are text files, changes should not be made with a text
1494 editor but with PO editing software. Weblate integrates PO editing
1495 functionality. Alternatively, translators can use any of various
1496 free-software tools for filling in translations, of which
1497 @uref{https://poedit.net/,Poedit} is one example, and (after logging in)
1498 @uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed
1499 file. There is also a special
1500 @uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of GNU
1501 Emacs. Over time translators find out what software they are happy with and
1502 what features they need.
1504 On Weblate, you will find various links to the editor, that will show various
1505 subsets (or all) of the strings. Have a look around and at the
1506 @uref{https://docs.weblate.org/en/latest/,documentation} to familiarize
1507 yourself with the platform.
1509 @subsubheading Translation Components
1511 In this section, we provide more detailed guidance on the translation
1512 process, as well as details on what you should or should not do. When in
1513 doubt, please contact us, we will be happy to help!
1517 Guix is written in the Guile programming language, and some strings contain
1518 special formating that is interpreted by Guile. These special formating
1519 should be highlighted by Weblate. They start with @code{~} followed by one
1522 When printing the string, Guile replaces the special formating symbols with
1523 actual values. For instance, the string @samp{ambiguous package specification
1524 `~a'} would be substituted to contain said package specification instead of
1525 @code{~a}. To properly translate this string, you must keep the formating
1526 code in your translation, although you can place it where it makes sense in
1527 your language. For instance, the French translation says @samp{spécification
1528 du paquet « ~a » ambiguë} because the adjective needs to be placed in the
1529 end of the sentence.
1531 If there are multiple formating symbols, make sure to respect the order.
1532 Guile does not know in which order you intended the string to be read, so it
1533 will substitute the symbols in the same order as the English sentence.
1535 As an example, you cannot translate @samp{package '~a' has been superseded by
1536 '~a'} by @samp{'~a' superseeds package '~a'}, because the meaning would be
1537 reversed. If foo is superseeded by bar, the translation would read
1538 @samp{'foo' superseeds package 'bar'}. To work around this problem, it
1539 is possible to use more advanced formating to select a given piece of data,
1540 instead of following the default English order. @xref{Formatted Output,,,
1541 guile, GNU Guile Reference Manual}, for more information on formating in Guile.
1545 Package descriptions occasionally contain Texinfo markup (@pxref{Synopses
1546 and Descriptions}). Texinfo markup looks like @samp{@@code@{rm -rf@}},
1547 @samp{@@emph@{important@}}, etc. When translating, please leave markup as is.
1549 The characters after ``@@'' form the name of the markup, and the text between
1550 ``@{'' and ``@}'' is its content. In general, you should not translate the
1551 content of markup like @code{@@code}, as it contains literal code that do not
1552 change with language. You can translate the content of formating markup such
1553 as @code{@@emph}, @code{@@i}, @code{@@itemize}, @code{@@item}. However, do
1554 not translate the name of the markup, or it will not be recognized. Do
1555 not translate the word after @code{@@end}, it is the name of the markup that
1556 is closed at this position (e.g.@: @code{@@itemize ... @@end itemize}).
1558 @item documentation-manual and documentation-cookbook
1560 The first step to ensure a successful translation of the manual is to find
1561 and translate the following strings @emph{first}:
1564 @item @code{version.texi}: Translate this string as @code{version-xx.texi},
1565 where @code{xx} is your language code (the one shown in the URL on
1567 @item @code{contributing.texi}: Translate this string as
1568 @code{contributing.xx.texi}, where @code{xx} is the same language code.
1569 @item @code{Top}: Do not translate this string, it is important for Texinfo.
1570 If you translate it, the document will be empty (missing a Top node).
1571 Please look for it, and register @code{Top} as its translation.
1574 Translating these strings first ensure we can include your translation in
1575 the guix repository without breaking the make process or the
1576 @command{guix pull} machinery.
1578 The manual and the cookbook both use Texinfo. As for @code{packages}, please
1579 keep Texinfo markup as is. There are more possible markup types in the manual
1580 than in the package descriptions. In general, do not translate the content
1581 of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value}, etc. You
1582 should translate the content of formating markup such as @code{@@emph},
1585 The manual contains sections that can be refered to by name by @code{@@ref},
1586 @code{@@xref} and @code{@@pxref}. We have a mechanism in place so you do
1587 not have to translate their content. If you keep the English title, we will
1588 automatically replace it with your translation of that title. This ensures
1589 that Texinfo will always be able to find the node. If you decide to change
1590 the translation of the title, the references will automatically be updated
1591 and you will not have to update them all yourself.
1593 When translating references from the cookbook to the manual, you need to
1594 replace the name of the manual and the name of the section. For instance,
1595 to translate @code{@@pxref@{Defining Packages,,, guix, GNU Guix Reference
1596 Manual@}}, you would replace @code{Defining Packages} with the title of that
1597 section in the translated manual @emph{only} if that title is translated.
1598 If the title is not translated in your language yet, do not translate it here,
1599 or the link will be broken. Replace @code{guix} with @code{guix.xx} where
1600 @code{xx} is your language code. @code{GNU Guix Reference Manual} is the
1601 text of the link. You can translate it however you wish.
1605 The website pages are written using SXML, an s-expression version of HTML,
1606 the basic language of the web. We have a process to extract translatable
1607 strings from the source, and replace complex s-expressions with a more familiar
1608 XML markup, where each markup is numbered. Translators can arbitrarily change
1609 the ordering, as in the following example.
1612 #. TRANSLATORS: Defining Packages is a section name
1613 #. in the English (en) manual.
1614 #: apps/base/templates/about.scm:64
1615 msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
1616 msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
1619 Note that you need to include the same markups. You cannot skip any.
1622 In case you make a mistake, the component might fail to build properly with your
1623 language, or even make guix pull fail. To prevent that, we have a process
1624 in place to check the content of the files before pushing to our repository.
1625 We will not be able to update the translation for your language in Guix, so
1626 we will notify you (through weblate and/or by email) so you get a chance to
1629 @subsubheading Outside of Weblate
1631 Currently, some parts of Guix cannot be translated on Weblate, help wanted!
1634 @item @command{guix pull} news can be translated in @file{news.scm}, but is not
1635 available from Weblate. If you want to provide a translation, you
1636 can prepare a patch as described above, or simply send us your
1637 translation with the name of the news entry you translated and your
1638 language. @xref{Writing Channel News}, for more information about
1640 @item Guix blog posts cannot currently be translated.
1641 @item The installer script (for foreign distributions) is entirely in English.
1642 @item Some of the libraries Guix uses cannot be translated or are translated
1643 outside of the Guix project. Guile itself is not internationalized.
1644 @item Other manuals linked from this manual or the cookbook might not be
1648 @subsubheading Translation Infrastructure
1650 Weblate is backed by a git repository from which it discovers new strings to
1651 translate and pushes new and updated translations. Normally, it would be
1652 enough to give it commit access to our repositories. However, we decided
1653 to use a separate repository for two reasons. First, we would have to give
1654 Weblate commit access and authorize its signing key, but we do not trust it
1655 in the same way we trust guix developpers, especially since we do not manage
1656 the instance ourselves. Second, if translators mess something up, it can
1657 break the generation of the website and/or guix pull for all our users,
1658 independently of their language.
1660 For these reasons, we use a dedicated repository to host translations, and we
1661 synchronize it with our guix and artworks repositories after checking no issue
1662 was introduced in the translation.
1664 Developpers can download the latest PO files from weblate in the Guix
1665 repository by runnig the @command{make download-po} target. It will
1666 automatically download the latest files from weblate, reformat them to a
1667 canonical form, and check they do not contain issues. The manual needs to be
1668 built again to check for additional issues that might crash Texinfo.
1670 Before pushing new translation files, developpers should add them to the
1671 make machinery so the translations are actually available. The process
1672 differs for the various components.
1675 @item New po files for the @code{guix} and @code{packages} components must
1676 be registered by adding the new language to @file{po/guix/LINGUAS} or
1677 @file{po/packages/LINGUAS}.
1678 @item New po files for the @code{documentation-manual} component must be
1679 registered by adding the file name to @code{DOC_PO_FILES} in
1680 @file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
1681 @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
1682 @file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
1683 @code{TRANSLATED_INFO} also in @file{doc/local.mk}.
1684 @item New po files for the @code{documentation-cookbook} component must be
1685 registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
1686 @file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
1687 manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
1688 @file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also
1689 in @file{doc/local.mk}.
1690 @item New po files for the @code{website} component must be added to the
1691 @code{guix-artwork} repository, in @file{website/po/}.
1692 @file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must
1693 be updated accordingly (see @file{website/i18n-howto.txt} for more
1694 information on the process).