1 -*- mode: org; coding: utf-8; -*-
3 #+TITLE: Hacking GNU Guix and Its Incredible Distro
5 Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
7 Copying and distribution of this file, with or without modification,
8 are permitted in any medium without royalty provided the copyright
9 notice and this notice are preserved.
12 * Running Guix before it is installed
14 Command-line tools can be used even if you have not run "make install".
15 To do that, prefix each command with ‘./pre-inst-env’, as in:
17 ./pre-inst-env guix build --help
19 Similarly, for a Guile session using the Guix modules:
21 ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
23 The ‘pre-inst-env’ script sets up all the environment variables
24 necessary to support this.
28 The Perfect Setup to hack on Guix is basically the perfect setup used
29 for Guile hacking (info "(guile) Using Guile in Emacs"). First, you
30 need more than an editor, you need [[http://www.gnu.org/software/emacs][Emacs]], empowered by the wonderful
31 [[http://nongnu.org/geiser/][Geiser]].
33 Geiser allows for interactive and incremental development from within
34 Emacs: code compilation and evaluation from within buffers, access to
35 on-line documentation (docstrings), context-sensitive completion, M-. to
36 jump to an object definition, a REPL to try out your code, and more.
38 To actually edit the code, Emacs already has a neat Scheme mode. But in
39 addition to that, you must not miss [[http://www.emacswiki.org/emacs/ParEdit][Paredit]]. It provides facilities to
40 directly operate on the syntax tree, such as raising an s-expression or
41 wrapping it, swallowing or rejecting the following s-expression, etc.
43 * Packaging Guidelines
45 The GNU distribution is about respecting the freedom of users. Consequently,
46 it contains only free software as defined at
47 http://www.gnu.org/philosophy/free-sw.html .
49 In addition, we follow the [[http://www.gnu.org/distros/free-system-distribution-guidelines.html][free software distribution guidelines]]. Among other
50 things, this means that the distribution tries hard not to steer users towards
51 obtaining information about non-free software.
55 Package recipes in Guix look like this:
64 (uri (string-append "mirror://gnu/nettle/nettle-"
68 "0wicr7amx01l03rm0pzgr1qvw3f9blaw17vjsy1301dh13ll58aa"))))
69 (build-system gnu-build-system)
70 (inputs `(("m4" ,m4)))
71 (propagated-inputs `(("gmp" ,gmp)))
73 "http://www.lysator.liu.se/~nisse/nettle/")
74 (synopsis "GNU Nettle, a cryptographic library")
76 "Nettle is a cryptographic library...")
80 Such a recipe can be written by hand, and then tested by running
81 ‘./pre-inst-env guix build nettle’.
83 When writing the recipe, the base32-encoded SHA256 hash of the source
84 code tarball, which can be seen in the example above, can be obtained by
87 guix download http://ftp.gnu.org/gnu/nettle/nettle-2.5.tar.gz
89 Alternatively, it is possible to semi-automatically import recipes from
90 the [[http://nixos.org/nixpkgs/][Nixpkgs]] software distribution using this command:
92 guix import /path/to/nixpkgs/checkout nettle
94 The command automatically fetches and converts to Guix the “Nix
95 expression” of Nettle.
99 Development is done using the Git distributed version control system. Thus,
100 access to the repository is not strictly necessary. We welcome contributions
101 in the form of patches as produced by ‘git format-patch’ sent to
102 bug-guix@gnu.org. Please write commit logs in the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog format]].
104 As you become a regular contributor, you may find it convenient to have write
105 access to the repository (see below.)
109 For frequent contributors, having write access to the repository is
110 convenient. When you deem it necessary, feel free to ask for it on the
111 mailing list. When you get commit access, please make sure to follow the
112 policy below (discussions of the policy can take place on bug-guix@gnu.org.)
114 Non-trivial patches should always be posted to bug-guix@gnu.org (trivial
115 patches include fixing typos, etc.)
117 For patches that just add a new package, and a simple one, it’s OK to commit,
118 if you’re confident (which means you successfully built it in a chroot setup,
119 and have done a reasonable copyright and license auditing.) Likewise for
120 package upgrades. We have a mailing list for commit notifications
121 (guix-commits@gnu.org), so people can notice. Before pushing your changes,
122 make sure to run ‘git pull --rebase’.
124 For anything else, please post to bug-guix@gnu.org and leave time for a
125 review, without committing anything. If you didn’t receive any reply
126 after two weeks, and if you’re confident, it’s OK to commit.
128 That last part is subject to being adjusted, allowing individuals to commit
129 directly on non-controversial changes on parts they’re familiar with.
131 * Porting the Guix distro on a new platform
135 Unlike Make or similar build tools, Guix requires absolutely /all/ the
136 dependencies of a build process to be specified.
138 For a user-land software distribution, that means that the process that
139 builds GCC (then used to build all other programs) must itself be
140 specified; and the process to build the C library to build that GCC; and
141 the process to build the GCC to build that library; and... See the
142 problem? Chicken-and-egg.
144 To break that cycle, the distro starts from a set of pre-built
145 binaries–usually referred to as “bootstrap binaries.” These include
146 statically-linked versions of Guile, GCC, Coreutils, Grep, sed,
147 etc., and the GNU C Library.
149 This section describes how to build those bootstrap binaries when
150 porting to a new platform.
152 ** When the platform is supported by Nixpkgs
154 In that case, the easiest thing is to bootstrap the distro using
155 binaries from Nixpkgs.
157 To do that, you need to comment out the definitions of
158 ‘%bootstrap-guile’ and ‘%bootstrap-inputs’ in gnu/packages/bootstrap.scm
159 to force the use of Nixpkgs derivations. For instance, when porting to
160 ‘i686-linux’, you should redefine these variables along these lines:
163 (define %bootstrap-guile
164 (nixpkgs-derivation "guile" "i686-linux"))
166 (define %bootstrap-inputs
168 `(("libc" ,(nixpkgs-derivation "glibc" "i686-linux"))
169 ,@(map (lambda (name)
170 (list name (nixpkgs-derivation name "i686-linux")))
171 '("gnutar" "gzip" "bzip2" "xz" "patch"
172 "coreutils" "gnused" "gnugrep" "bash"
173 "gawk" ; used by `config.status'
174 "gcc" "binutils")))))
177 That should allow the distro to be bootstrapped.
179 Then, the tarballs containing the initial binaries of Guile, Coreutils,
180 GCC, libc, etc. need to be built. To that end, run the following
184 ./pre-inst-env guix build -K \
185 -e '(@ (gnu packages make-bootstrap) %bootstrap-tarballs)' \
190 These should build tarballs containing statically-linked tools usable on
193 In the source tree, you need to install binaries for ‘mkdir’, ‘bash’,
194 ‘tar’, and ‘xz’ under ‘gnu/packages/bootstrap/i686-linux’. These
195 binaries can be extracted from the static-binaries tarball built above.
197 A rule for ‘gnu/packages/bootstrap/i686-linux/guile-2.0.7.tar.xz’
198 needs to be added in ‘Makefile.am’, with the appropriate hexadecimal
199 vrepresentation of its SHA256 hash.
201 You may then revert your changes to ‘bootstrap.scm’. For the variables
202 ‘%bootstrap-coreutils&co’, ‘%bootstrap-binutils’, ‘%bootstrap-glibc’,
203 and ‘%bootstrap-gcc’, the expected SHA256 of the corresponding tarballs
204 for ‘i686-linux’ (built above) must be added.
206 This should be enough to bootstrap the distro without resorting to
209 ** When the platform is *not* supported by Nixpkgs
211 In that case, the bootstrap binaries should be built using whatever
212 tools are available on the target platform. That is, the tarballs and
213 binaries show above must first be built manually, using the available
216 They should have the same properties as those built by the Guix recipes
217 shown above. For example, all the binaries (except for glibc) must be
218 statically-linked; the bootstrap Guile must be relocatable (see patch in
219 the Guix distro); the static-binaries tarball must contain the same
220 programs (Coreutils, Grep, sed, Awk, etc.); and so on.