HACKING

   1 -*- mode: org; coding: utf-8; -*-
   2
   3 #+TITLE: Hacking GNU Guix and Its Incredible Distro
   4
   5 Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
   6
   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.
  10
  11
  12 * Running Guix before it is installed
  13
  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:
  16
  17   ./pre-inst-env guix build --help
  18
  19 Similarly, for a Guile session using the Guix modules:
  20
  21   ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
  22
  23 The ‘pre-inst-env’ script sets up all the environment variables
  24 necessary to support this.
  25
  26 * The Perfect Setup
  27
  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]].
  32
  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.
  37
  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.
  42
  43 * Packaging Guidelines
  44
  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 .
  48
  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.
  52
  53 * Adding new packages
  54
  55 Package recipes in Guix look like this:
  56
  57 #+BEGIN_SRC scheme
  58   (package
  59     (name "nettle")
  60     (version "2.5")
  61     (source
  62       (origin
  63         (method url-fetch)
  64         (uri (string-append "mirror://gnu/nettle/nettle-"
  65                             version ".tar.gz"))
  66         (sha256
  67           (base32
  68             "0wicr7amx01l03rm0pzgr1qvw3f9blaw17vjsy1301dh13ll58aa"))))
  69     (build-system gnu-build-system)
  70     (inputs `(("m4" ,m4)))
  71     (propagated-inputs `(("gmp" ,gmp)))
  72     (home-page
  73       "http://www.lysator.liu.se/~nisse/nettle/")
  74     (synopsis "GNU Nettle, a cryptographic library")
  75     (description
  76       "Nettle is a cryptographic library...")
  77     (license gpl2+))
  78 #+END_SRC
  79
  80 Such a recipe can be written by hand, and then tested by running
  81 ‘./pre-inst-env guix build nettle’.
  82
  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
  85 running:
  86
  87   guix download http://ftp.gnu.org/gnu/nettle/nettle-2.5.tar.gz
  88
  89 Alternatively, it is possible to semi-automatically import recipes from
  90 the [[http://nixos.org/nixpkgs/][Nixpkgs]] software distribution using this command:
  91
  92   guix import /path/to/nixpkgs/checkout nettle
  93
  94 The command automatically fetches and converts to Guix the “Nix
  95 expression” of Nettle.
  96
  97 * Submitting Patches
  98
  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]].
 103
 104 As you become a regular contributor, you may find it convenient to have write
 105 access to the repository (see below.)
 106
 107 * Commit Access
 108
 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.)
 113
 114 Non-trivial patches should always be posted to bug-guix@gnu.org (trivial
 115 patches include fixing typos, etc.)
 116
 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 Likewise for package upgrades.  We have a mailing list for commit
 120 notifications (guix-commits@gnu.org), so people can notice.  Before pushing
 121 your changes, make sure to run ‘git pull --rebase’.
 122
 123 For anything else, please post to bug-guix@gnu.org and leave time for a
 124 review, without committing anything.  If you didn’t receive any reply
 125 after two weeks, and if you’re confident, it’s OK to commit.
 126
 127 That last part is subject to being adjusted, allowing individuals to commit
 128 directly on non-controversial changes on parts they’re familiar with.
 129
 130 * Porting the Guix distro on a new platform
 131
 132 ** Introduction
 133
 134 Unlike Make or similar build tools, Guix requires absolutely /all/ the
 135 dependencies of a build process to be specified.
 136
 137 For a user-land software distribution, that means that the process that
 138 builds GCC (then used to build all other programs) must itself be
 139 specified; and the process to build the C library to build that GCC; and
 140 the process to build the GCC to build that library; and...  See the
 141 problem?  Chicken-and-egg.
 142
 143 To break that cycle, the distro starts from a set of pre-built
 144 binaries–usually referred to as “bootstrap binaries.”  These include
 145 statically-linked versions of Guile, GCC, Coreutils, Make, Grep, sed,
 146 etc., and the GNU C Library.
 147
 148 This section describes how to build those bootstrap binaries when
 149 porting to a new platform.
 150
 151 ** When the platform is supported by Nixpkgs
 152
 153 In that case, the easiest thing is to bootstrap the distro using
 154 binaries from Nixpkgs.
 155
 156 To do that, you need to comment out the definitions of
 157 ‘%bootstrap-guile’ and ‘%bootstrap-inputs’ in distro/packages/bootstrap.scm
 158 to force the use of Nixpkgs derivations.  For instance, when porting to
 159 ‘i686-linux’, you should redefine these variables along these lines:
 160
 161 #+BEGIN_SRC scheme
 162   (define %bootstrap-guile
 163     (nixpkgs-derivation "guile" "i686-linux"))
 164
 165   (define %bootstrap-inputs
 166     (compile-time-value
 167      `(("libc" ,(nixpkgs-derivation "glibc" "i686-linux"))
 168        ,@(map (lambda (name)
 169                 (list name (nixpkgs-derivation name "i686-linux")))
 170               '("gnutar" "gzip" "bzip2" "xz" "patch"
 171                 "coreutils" "gnused" "gnugrep" "bash"
 172                 "gawk"                                ; used by `config.status'
 173                 "gcc" "binutils")))))
 174 #+END_SRC
 175
 176 That should allow the distro to be bootstrapped.
 177
 178 Then, the tarballs containing the initial binaries of Guile, Coreutils,
 179 GCC, libc, etc. need to be built.  To that end, run the following
 180 commands:
 181
 182 #+BEGIN_SRC sh
 183   ./pre-inst-env guix build -K                                    \
 184       -e '(@ (gnu packages make-bootstrap) %bootstrap-tarballs)'  \
 185       --system=i686-linux
 186
 187 #+END_SRC
 188
 189 These should build tarballs containing statically-linked tools usable on
 190 that system.
 191
 192 In the source tree, you need to install binaries for ‘mkdir’, ‘bash’,
 193 ‘tar’, and ‘xz’ under ‘distro/packages/bootstrap/i686-linux’.  These
 194 binaries can be extracted from the static-binaries tarball built above.
 195
 196 A rule for ‘distro/packages/bootstrap/i686-linux/guile-2.0.7.tar.xz’
 197 needs to be added in ‘Makefile.am’, with the appropriate hexadecimal
 198 vrepresentation of its SHA256 hash.
 199
 200 You may then revert your changes to ‘bootstrap.scm’.  For the variables
 201 ‘%bootstrap-coreutils&co’, ‘%bootstrap-binutils’, ‘%bootstrap-glibc’,
 202 and ‘%bootstrap-gcc’, the expected SHA256 of the corresponding tarballs
 203 for ‘i686-linux’ (built above) must be added.
 204
 205 This should be enough to bootstrap the distro without resorting to
 206 Nixpkgs.
 207
 208 ** When the platform is *not* supported by Nixpkgs
 209
 210 In that case, the bootstrap binaries should be built using whatever
 211 tools are available on the target platform.  That is, the tarballs and
 212 binaries show above must first be built manually, using the available
 213 tools.
 214
 215 They should have the same properties as those built by the Guix recipes
 216 shown above.  For example, all the binaries (except for glibc) must be
 217 statically-linked; the bootstrap Guile must be relocatable (see patch in
 218 the Guix distro); the static-binaries tarball must contain the same
 219 programs (Coreutils, Grep, sed, Awk, etc.); and so on.