| 1 | -*- mode: org; coding: utf-8; -*- |
| 2 | |
| 3 | #+TITLE: Hacking GNU Guix and Its Incredible Distro |
| 4 | |
| 5 | Copyright © 2012, 2013, 2014 Ludovic Courtès <[email protected]> |
| 6 | Copyright © 2013 Nikita Karetnikov <[email protected]> |
| 7 | Copyright © 2014 Pierre-Antoine Rault <[email protected]> |
| 8 | |
| 9 | Copying and distribution of this file, with or without modification, |
| 10 | are permitted in any medium without royalty provided the copyright |
| 11 | notice and this notice are preserved. |
| 12 | |
| 13 | |
| 14 | * Building from Git |
| 15 | |
| 16 | When building Guix from a checkout, the following packages are required in |
| 17 | addition to those mentioned in the installation instructions: |
| 18 | |
| 19 | - [[http://www.gnu.org/software/autoconf/][GNU Autoconf]] |
| 20 | - [[http://www.gnu.org/software/automake/][GNU Automake]] |
| 21 | - [[http://www.gnu.org/software/gettext/][GNU Gettext]] |
| 22 | - [[http://www.graphviz.org/][Graphviz]] |
| 23 | |
| 24 | Run ‘./bootstrap’ to download the Nix daemon source code and to generate the |
| 25 | build system infrastructure using autoconf. It reports an error if an |
| 26 | inappropriate version of the above packages is being used. |
| 27 | |
| 28 | The ‘bootstrap’ script, among other things, invokes ‘git submodule update’; if |
| 29 | you didn’t run it, you may get the following error: |
| 30 | |
| 31 | make: *** No rule to make target `nix/libstore/schema.sql', needed by |
| 32 | `nix/libstore/schema.sql.hh' |
| 33 | |
| 34 | If you get an error like this one: |
| 35 | |
| 36 | configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES |
| 37 | |
| 38 | it probably means that Autoconf couldn’t find ‘pkg.m4’, which is provided by |
| 39 | pkg-config. Make sure that ‘pkg.m4’ is available. For instance, if you |
| 40 | installed Automake in ‘/usr/local’, it wouldn’t look for ‘.m4’ files in |
| 41 | ‘/usr/share’. So you have to invoke the following command in that case |
| 42 | |
| 43 | $ export ACLOCAL_PATH=/usr/share/aclocal |
| 44 | |
| 45 | See “info '(automake) Macro Search Path'” for more information. |
| 46 | |
| 47 | Then, run ‘./configure’ as usual. |
| 48 | |
| 49 | Finally, you have to invoke ‘make check’ to run tests. If anything fails, |
| 50 | take a look at “info '(guix) Installation'” or send a message to |
| 51 | <[email protected]>. |
| 52 | |
| 53 | * Running Guix before it is installed |
| 54 | |
| 55 | Command-line tools can be used even if you have not run "make install". |
| 56 | To do that, prefix each command with ‘./pre-inst-env’, as in: |
| 57 | |
| 58 | ./pre-inst-env guix build --help |
| 59 | |
| 60 | Similarly, for a Guile session using the Guix modules: |
| 61 | |
| 62 | ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' |
| 63 | |
| 64 | The ‘pre-inst-env’ script sets up all the environment variables |
| 65 | necessary to support this. |
| 66 | |
| 67 | * The Perfect Setup |
| 68 | |
| 69 | The Perfect Setup to hack on Guix is basically the perfect setup used |
| 70 | for Guile hacking (info "(guile) Using Guile in Emacs"). First, you |
| 71 | need more than an editor, you need [[http://www.gnu.org/software/emacs][Emacs]], empowered by the wonderful |
| 72 | [[http://nongnu.org/geiser/][Geiser]]. |
| 73 | |
| 74 | Geiser allows for interactive and incremental development from within |
| 75 | Emacs: code compilation and evaluation from within buffers, access to |
| 76 | on-line documentation (docstrings), context-sensitive completion, M-. to |
| 77 | jump to an object definition, a REPL to try out your code, and more. |
| 78 | |
| 79 | To actually edit the code, Emacs already has a neat Scheme mode. But in |
| 80 | addition to that, you must not miss [[http://www.emacswiki.org/emacs/ParEdit][Paredit]]. It provides facilities to |
| 81 | directly operate on the syntax tree, such as raising an s-expression or |
| 82 | wrapping it, swallowing or rejecting the following s-expression, etc. |
| 83 | |
| 84 | * Submitting Patches |
| 85 | |
| 86 | Development is done using the Git distributed version control system. Thus, |
| 87 | access to the repository is not strictly necessary. We welcome contributions |
| 88 | in the form of patches as produced by ‘git format-patch’ sent to |
| 89 | [email protected]. Please write commit logs in the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog |
| 90 | format]]; you can check the commit history for examples. |
| 91 | |
| 92 | Before submitting a patch that adds or modifies a package definition, please |
| 93 | run ‘guix lint PACKAGE’, where PACKAGE is the name of the new or modified |
| 94 | package, and fix any errors it reports. In addition, please make sure the |
| 95 | package builds on your platform, using ‘guix build’. You may also want to |
| 96 | check that dependent package (if applicable) are not affected by the change; |
| 97 | ‘guix refresh --list-dependent PACKAGE’ will help you do that. |
| 98 | |
| 99 | When posting a patch to the mailing list, use "[PATCH] ..." as a subject. You |
| 100 | may use your email client or the ‘git send-mail’ command. |
| 101 | |
| 102 | As you become a regular contributor, you may find it convenient to have write |
| 103 | access to the repository (see below.) |
| 104 | |
| 105 | * Coding Style |
| 106 | |
| 107 | In general our code follows the [[info:standards][GNU Coding Standards]] (GCS). However, the GCS |
| 108 | do not say much about Scheme, so here are some additional rules. |
| 109 | |
| 110 | ** Programming Paradigm |
| 111 | |
| 112 | Scheme code in Guix is written in a purely functional style. One exception is |
| 113 | code that involves input/output, and procedures that implement low-level |
| 114 | concepts, such as the ‘memoize’ procedure. |
| 115 | |
| 116 | ** Modules |
| 117 | |
| 118 | Guile modules that are meant to be used on the builder side must live in the |
| 119 | (guix build …) name space. They must not refer to other Guix or GNU modules. |
| 120 | However, it is OK for a “host-side” module to use a build-side module. |
| 121 | |
| 122 | Modules that deal with the broader GNU system should be in the (gnu …) name |
| 123 | space rather than (guix …). |
| 124 | |
| 125 | ** Data Types and Pattern Matching |
| 126 | |
| 127 | The tendency in classical Lisp is to use lists to represent everything, and |
| 128 | then to browse them “by hand” using ‘car’, ‘cdr’, ‘cadr’, and co. There are |
| 129 | several problems with that style, notably the fact that it is hard to read, |
| 130 | error-prone, and a hindrance to proper type error reports. |
| 131 | |
| 132 | Guix code should define appropriate data types (for instance, using |
| 133 | ‘define-record-type*’) rather than abuse lists. In addition, it should use |
| 134 | pattern matching, via Guile’s (ice-9 match) module, especially when matching |
| 135 | lists. |
| 136 | |
| 137 | ** Formatting Code |
| 138 | |
| 139 | When writing Scheme code, we follow common wisdom among Scheme programmers. |
| 140 | In general, we follow the [[http://mumble.net/~campbell/scheme/style.txt][Riastradh's Lisp Style Rules]]. This document happens |
| 141 | to describe the conventions mostly used in Guile’s code too. It is very |
| 142 | thoughtful and well written, so please do read it. |
| 143 | |
| 144 | Some special forms introduced in Guix, such as the ‘substitute*’ macro, have |
| 145 | special indentation rules. These are defined in the .dir-locals.el file, |
| 146 | which Emacs automatically uses. If you do not use Emacs, please make sure to |
| 147 | let your editor know the rules. |
| 148 | |
| 149 | We require all top-level procedures to carry a docstring. This requirement |
| 150 | can be relaxed for simple private procedures in the (guix build …) name space, |
| 151 | though. |
| 152 | |
| 153 | Procedures should not have more than four positional parameters. Use keyword |
| 154 | parameters for procedures that take more than four parameters. |
| 155 | |
| 156 | * Commit Access |
| 157 | |
| 158 | For frequent contributors, having write access to the repository is |
| 159 | convenient. When you deem it necessary, feel free to ask for it on the |
| 160 | mailing list. When you get commit access, please make sure to follow the |
| 161 | policy below (discussions of the policy can take place on [email protected].) |
| 162 | |
| 163 | Non-trivial patches should always be posted to [email protected] (trivial |
| 164 | patches include fixing typos, etc.) |
| 165 | |
| 166 | For patches that just add a new package, and a simple one, it’s OK to commit, |
| 167 | if you’re confident (which means you successfully built it in a chroot setup, |
| 168 | and have done a reasonable copyright and license auditing.) Likewise for |
| 169 | package upgrades, except upgrades that trigger a lot of rebuilds (for example, |
| 170 | upgrading GnuTLS or GLib.) We have a mailing list for commit notifications |
| 171 | ([email protected]), so people can notice. Before pushing your changes, |
| 172 | make sure to run ‘git pull --rebase’. |
| 173 | |
| 174 | For anything else, please post to [email protected] and leave time for a |
| 175 | review, without committing anything. If you didn’t receive any reply |
| 176 | after two weeks, and if you’re confident, it’s OK to commit. |
| 177 | |
| 178 | That last part is subject to being adjusted, allowing individuals to commit |
| 179 | directly on non-controversial changes on parts they’re familiar with. |