4 This project is a cooperative effort, and we need your help to make it
5 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
6 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
7 reports, patches, and anything that may be helpful to the project. We
8 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
10 @cindex code of conduct, of contributors
11 @cindex contributor covenant
12 We want to provide a warm, friendly, and harassment-free environment, so
13 that anyone can contribute to the best of their abilities. To this end
14 our project uses a ``Contributor Covenant'', which was adapted from
15 @url{http://contributor-covenant.org/}. You can find a local version in
16 the @file{CODE-OF-CONDUCT} file in the source tree.
18 Contributors are not required to use their legal name in patches and
19 on-line communication; they can use any name or pseudonym of their
23 * Building from Git:: The latest and greatest.
24 * Running Guix Before It Is Installed:: Hacker tricks.
25 * The Perfect Setup:: The right tools.
26 * Coding Style:: Hygiene of the contributor.
27 * Submitting Patches:: Share your work.
30 @node Building from Git
31 @section Building from Git
33 If you want to hack Guix itself, it is recommended to use the latest
34 version from the Git repository:
37 git clone https://git.savannah.gnu.org/git/guix.git
40 When building Guix from a checkout,
41 the following packages are required in addition to those mentioned in
42 the installation instructions (@pxref{Requirements}).
45 @item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
46 @item @url{http://gnu.org/software/automake/, GNU Automake};
47 @item @url{http://gnu.org/software/gettext/, GNU Gettext};
48 @item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
49 @item @url{http://www.graphviz.org/, Graphviz};
50 @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
53 The easiest way to set up a development environment for Guix is, of
54 course, by using Guix! The following command starts a new shell where
55 all the dependencies and appropriate environment variables are set up to
62 @xref{Invoking guix environment}, for more information on that command.
63 Extra dependencies can be added with @option{--ad-hoc}:
66 guix environment guix --ad-hoc help2man git strace
69 Run @command{./bootstrap} to generate the build system infrastructure
70 using Autoconf and Automake. If you get an error like this one:
73 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
77 it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
78 provided by pkg-config. Make sure that @file{pkg.m4} is available. The
79 same holds for the @file{guile.m4} set of macros provided by Guile. For
80 instance, if you installed Automake in @file{/usr/local}, it wouldn’t
81 look for @file{.m4} files in @file{/usr/share}. In that case, you have
82 to invoke the following command:
85 export ACLOCAL_PATH=/usr/share/aclocal
88 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
91 Then, run @command{./configure} as usual. Make sure to pass
92 @code{--localstatedir=@var{directory}} where @var{directory} is the
93 @code{localstatedir} value used by your current installation (@pxref{The
94 Store}, for information about this).
96 Finally, you have to invoke @code{make check} to run tests
97 (@pxref{Running the Test Suite}). If anything
98 fails, take a look at installation instructions (@pxref{Installation})
99 or send a message to the @email{guix-devel@@gnu.org, mailing list}.
102 @node Running Guix Before It Is Installed
103 @section Running Guix Before It Is Installed
105 In order to keep a sane working environment, you will find it useful to
106 test the changes made in your local source tree checkout without
107 actually installing them. So that you can distinguish between your
108 ``end-user'' hat and your ``motley'' costume.
110 To that end, all the command-line tools can be used even if you have not
111 run @code{make install}. To do that, you first need to have an environment
112 with all the dependencies available (@pxref{Building from Git}), and then
113 simply prefix each command with
114 @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
115 top build tree of Guix; it is generated by @command{./configure}),
116 as in@footnote{The @option{-E} flag to
117 @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
118 such that @command{guix-daemon} and the tools it uses can find the Guile
122 $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
123 $ ./pre-inst-env guix build hello
127 Similarly, for a Guile session using the Guix modules:
130 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
137 @cindex read-eval-print loop
138 @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
142 $ ./pre-inst-env guile
143 scheme@@(guile-user)> ,use(guix)
144 scheme@@(guile-user)> ,use(gnu)
145 scheme@@(guile-user)> (define snakes
147 (lambda (package lst)
148 (if (string-prefix? "python"
149 (package-name package))
153 scheme@@(guile-user)> (length snakes)
157 The @command{pre-inst-env} script sets up all the environment variables
158 necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
160 Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
161 local source tree; it simply updates the @file{~/.config/guix/current}
162 symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
163 you want to upgrade your local source tree.
166 @node The Perfect Setup
167 @section The Perfect Setup
169 The Perfect Setup to hack on Guix is basically the perfect setup used
170 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
171 Manual}). First, you need more than an editor, you need
172 @url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
173 wonderful @url{http://nongnu.org/geiser/, Geiser}.
175 Geiser allows for interactive and incremental development from within
176 Emacs: code compilation and evaluation from within buffers, access to
177 on-line documentation (docstrings), context-sensitive completion,
178 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
179 and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
180 convenient Guix development, make sure to augment Guile’s load path so
181 that it finds source files from your checkout:
184 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
185 (with-eval-after-load 'geiser-guile
186 (add-to-list 'geiser-guile-load-path "~/src/guix"))
189 To actually edit the code, Emacs already has a neat Scheme mode. But in
190 addition to that, you must not miss
191 @url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
192 facilities to directly operate on the syntax tree, such as raising an
193 s-expression or wrapping it, swallowing or rejecting the following
196 @cindex code snippets
198 @cindex reducing boilerplate
199 We also provide templates for common git commit messages and package
200 definitions in the @file{etc/snippets} directory. These templates can
201 be used with @url{http://joaotavora.github.io/yasnippet/, YASnippet} to
202 expand short trigger strings to interactive text snippets. You may want
203 to add the snippets directory to the @var{yas-snippet-dirs} variable in
207 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
208 (with-eval-after-load 'yasnippet
209 (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
212 The commit message snippets depend on @url{https://magit.vc/, Magit} to
213 display staged files. When editing a commit message type @code{add}
214 followed by @kbd{TAB} to insert a commit message template for adding a
215 package; type @code{update} followed by @kbd{TAB} to insert a template
216 for updating a package; type @code{https} followed by @kbd{TAB} to
217 insert a template for changing the home page URI of a package to HTTPS.
219 The main snippet for @code{scheme-mode} is triggered by typing
220 @code{package...} followed by @kbd{TAB}. This snippet also inserts the
221 trigger string @code{origin...}, which can be expanded further. The
222 @code{origin} snippet in turn may insert other trigger strings ending on
223 @code{...}, which also can be expanded further.
227 @section Coding Style
229 In general our code follows the GNU Coding Standards (@pxref{Top,,,
230 standards, GNU Coding Standards}). However, they do not say much about
231 Scheme, so here are some additional rules.
234 * Programming Paradigm:: How to compose your elements.
235 * Modules:: Where to store your code?
236 * Data Types and Pattern Matching:: Implementing data structures.
237 * Formatting Code:: Writing conventions.
240 @node Programming Paradigm
241 @subsection Programming Paradigm
243 Scheme code in Guix is written in a purely functional style. One
244 exception is code that involves input/output, and procedures that
245 implement low-level concepts, such as the @code{memoize} procedure.
250 Guile modules that are meant to be used on the builder side must live in
251 the @code{(guix build @dots{})} name space. They must not refer to
252 other Guix or GNU modules. However, it is OK for a ``host-side'' module
253 to use a build-side module.
255 Modules that deal with the broader GNU system should be in the
256 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
258 @node Data Types and Pattern Matching
259 @subsection Data Types and Pattern Matching
261 The tendency in classical Lisp is to use lists to represent everything,
262 and then to browse them ``by hand'' using @code{car}, @code{cdr},
263 @code{cadr}, and co. There are several problems with that style,
264 notably the fact that it is hard to read, error-prone, and a hindrance
265 to proper type error reports.
267 Guix code should define appropriate data types (for instance, using
268 @code{define-record-type*}) rather than abuse lists. In addition, it
269 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
270 especially when matching lists.
272 @node Formatting Code
273 @subsection Formatting Code
275 @cindex formatting code
277 When writing Scheme code, we follow common wisdom among Scheme
278 programmers. In general, we follow the
279 @url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
280 Style Rules}. This document happens to describe the conventions mostly
281 used in Guile’s code too. It is very thoughtful and well written, so
284 Some special forms introduced in Guix, such as the @code{substitute*}
285 macro, have special indentation rules. These are defined in the
286 @file{.dir-locals.el} file, which Emacs automatically uses. Also note
287 that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
288 highlights Guix code properly (@pxref{Development,,, emacs-guix, The
289 Emacs-Guix Reference Manual}).
291 @cindex indentation, of code
292 @cindex formatting, of code
293 If you do not use Emacs, please make sure to let your editor knows these
294 rules. To automatically indent a package definition, you can also run:
297 ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
301 This automatically indents the definition of @var{package} in
302 @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
303 indent a whole file, omit the second argument:
306 ./etc/indent-code.el gnu/services/@var{file}.scm
309 @cindex Vim, Scheme code editing
310 If you are editing code with Vim, we recommend that you run @code{:set
311 autoindent} so that your code is automatically indented as you type.
313 @uref{https://www.vim.org/scripts/script.php?script_id=3998,
314 @code{paredit.vim}} may help you deal with all these parentheses.
316 We require all top-level procedures to carry a docstring. This
317 requirement can be relaxed for simple private procedures in the
318 @code{(guix build @dots{})} name space, though.
320 Procedures should not have more than four positional parameters. Use
321 keyword parameters for procedures that take more than four parameters.
324 @node Submitting Patches
325 @section Submitting Patches
327 Development is done using the Git distributed version control system.
328 Thus, access to the repository is not strictly necessary. We welcome
329 contributions in the form of patches as produced by @code{git
330 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
332 This mailing list is backed by a Debbugs instance accessible at
333 @uref{https://bugs.gnu.org/guix-patches}, which allows us to keep track
334 of submissions. Each message sent to that mailing list gets a new
335 tracking number assigned; people can then follow up on the submission by
336 sending email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is
337 the tracking number (@pxref{Sending a Patch Series}).
339 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
340 standards, GNU Coding Standards}); you can check the commit history for
343 Before submitting a patch that adds or modifies a package definition,
344 please run through this check list:
348 If the authors of the packaged software provide a cryptographic
349 signature for the release tarball, make an effort to verify the
350 authenticity of the archive. For a detached GPG signature file this
351 would be done with the @code{gpg --verify} command.
354 Take some time to provide an adequate synopsis and description for the
355 package. @xref{Synopses and Descriptions}, for some guidelines.
358 Run @code{guix lint @var{package}}, where @var{package} is the
359 name of the new or modified package, and fix any errors it reports
360 (@pxref{Invoking guix lint}).
363 Make sure the package builds on your platform, using @code{guix build
368 Make sure the package does not use bundled copies of software already
369 available as separate packages.
371 Sometimes, packages include copies of the source code of their
372 dependencies as a convenience for users. However, as a distribution, we
373 want to make sure that such packages end up using the copy we already
374 have in the distribution, if there is one. This improves resource usage
375 (the dependency is built and stored only once), and allows the
376 distribution to make transverse changes such as applying security
377 updates for a given software package in a single place and have them
378 affect the whole system---something that bundled copies prevent.
381 Take a look at the profile reported by @command{guix size}
382 (@pxref{Invoking guix size}). This will allow you to notice references
383 to other packages unwillingly retained. It may also help determine
384 whether to split the package (@pxref{Packages with Multiple Outputs}),
385 and which optional dependencies should be used.
388 For important changes, check that dependent package (if applicable) are
389 not affected by the change; @code{guix refresh --list-dependent
390 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
392 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
393 @cindex branching strategy
394 @cindex rebuild scheduling strategy
395 Depending on the number of dependent packages and thus the amount of
396 rebuilding induced, commits go to different branches, along these lines:
399 @item 300 dependent packages or less
400 @code{master} branch (non-disruptive changes).
402 @item between 300 and 1,200 dependent packages
403 @code{staging} branch (non-disruptive changes). This branch is intended
404 to be merged in @code{master} every 3 weeks or so. Topical changes
405 (e.g., an update of the GNOME stack) can instead go to a specific branch
406 (say, @code{gnome-updates}).
408 @item more than 1,200 dependent packages
409 @code{core-updates} branch (may include major and potentially disruptive
410 changes). This branch is intended to be merged in @code{master} every
414 All these branches are @uref{https://hydra.gnu.org/project/gnu,
415 tracked by our build farm} and merged into @code{master} once
416 everything has been successfully built. This allows us to fix issues
417 before they hit users, and to reduce the window during which pre-built
418 binaries are not available.
420 Generally, branches other than @code{master} are considered
421 @emph{frozen} if there has been a recent evaluation, or there is a
422 corresponding @code{-next} branch. Please ask on the mailing list or
423 IRC if unsure where to place a patch.
424 @c TODO: It would be good with badges on the website that tracks these
425 @c branches. Or maybe even a status page.
428 @cindex determinism, of build processes
429 @cindex reproducible builds, checking
430 Check whether the package's build process is deterministic. This
431 typically means checking whether an independent build of the package
432 yields the exact same result that you obtained, bit for bit.
434 A simple way to do that is by building the same package several times in
435 a row on your machine (@pxref{Invoking guix build}):
438 guix build --rounds=2 my-package
441 This is enough to catch a class of common non-determinism issues, such
442 as timestamps or randomly-generated output in the build result.
444 Another option is to use @command{guix challenge} (@pxref{Invoking guix
445 challenge}). You may run it once the package has been committed and
446 built by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
447 result as you did. Better yet: Find another machine that can build it
448 and run @command{guix publish}. Since the remote build machine is
449 likely different from yours, this can catch non-determinism issues
450 related to the hardware---e.g., use of different instruction set
451 extensions---or to the operating system kernel---e.g., reliance on
452 @code{uname} or @file{/proc} files.
455 When writing documentation, please use gender-neutral wording when
456 referring to people, such as
457 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
458 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
461 Verify that your patch contains only one set of related changes.
462 Bundling unrelated changes together makes reviewing harder and slower.
464 Examples of unrelated changes include the addition of several packages,
465 or a package update along with fixes to that package.
468 Please follow our code formatting rules, possibly running the
469 @command{etc/indent-code.el} script to do that automatically for you
470 (@pxref{Formatting Code}).
473 When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
474 Use reliable URLs, not generated ones. For instance, GitHub archives are not
475 necessarily identical from one generation to the next, so in this case it's
476 often better to clone the repository. Don't use the @command{name} field in
477 the URL: it is not very useful and if the name changes, the URL will probably
481 Try to minimize the weight of the inputs to make the transitive closure as
482 small as possible (@pxref{Invoking guix size}). Use @command{native-inputs}
483 and @command{inputs} appropriately. It's sometimes sufficient to use the
484 @command{-minimal} version of a package as input, e.g. @command{bash-minimal}
485 instead of @command{bash}. In particular, avoid adding @command{texlive} as a
486 dependency: because of its extreme size, it's both heavy on the build farms
487 and on the users who would like to build or hack the package from source. Use
488 @command{texlive-tiny} or @command{texlive-union} instead.
492 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
493 a subject. You may use your email client or the @command{git
494 send-email} command (@pxref{Sending a Patch Series}). We prefer to get
495 patches in plain text messages, either inline or as MIME attachments.
496 You are advised to pay attention if your email client changes anything
497 like line breaks or indentation which could potentially break the
500 When a bug is resolved, please close the thread by sending an email to
501 @email{@var{NNN}-done@@debbugs.gnu.org}.
503 @unnumberedsubsec Sending a Patch Series
504 @anchor{Sending a Patch Series}
506 @cindex @code{git send-email}
507 @cindex @code{git-send-email}
509 When sending a patch series (e.g., using @code{git send-email}), please
510 first send one message to @email{guix-patches@@gnu.org}, and then send
511 subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
512 they are kept together. See
513 @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
514 for more information.
515 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html