HACKING

   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 <ludo@gnu.org>
   6 Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
   7 Copyright © 2014 Pierre-Antoine Rault <par@rigelk.eu>
   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 <guix-devel@gnu.org>.
  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 guix-devel@gnu.org.  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 guix-devel@gnu.org.)
 162
 163 Non-trivial patches should always be posted to guix-devel@gnu.org (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 (guix-commits@gnu.org), so people can notice.  Before pushing your changes,
 172 make sure to run ‘git pull --rebase’.
 173
 174 For anything else, please post to guix-devel@gnu.org 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.