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 * Adding new packages
  44
  45 Package recipes in Guix look like this:
  46
  47 #+BEGIN_SRC scheme
  48   (package
  49     (name "nettle")
  50     (version "2.5")
  51     (source
  52       (origin
  53         (method url-fetch)
  54         (uri (string-append "mirror://gnu/nettle/nettle-"
  55                             version ".tar.gz"))
  56         (sha256
  57           (base32
  58             "0wicr7amx01l03rm0pzgr1qvw3f9blaw17vjsy1301dh13ll58aa"))))
  59     (build-system gnu-build-system)
  60     (inputs `(("m4" ,m4)))
  61     (propagated-inputs `(("gmp" ,gmp)))
  62     (home-page
  63       "http://www.lysator.liu.se/~nisse/nettle/")
  64     (synopsis "GNU Nettle, a cryptographic library")
  65     (description
  66       "Nettle is a cryptographic library...")
  67     (license gpl2+))
  68 #+END_SRC
  69
  70 Such a recipe can be written by hand, and then tested by running
  71 ‘./pre-inst-env guix-build nettle’.
  72
  73 When writing the recipe, the base32-encoded SHA256 hash of the source
  74 code tarball, which can be seen in the example above, can be obtained by
  75 running:
  76
  77   guix-download http://ftp.gnu.org/gnu/nettle/nettle-2.5.tar.gz
  78
  79 Alternatively, it is possible to semi-automatically import recipes from
  80 the [[http://nixos.org/nixpkgs/][Nixpkgs]] software distribution using this command:
  81
  82   guix-import /path/to/nixpkgs/checkout nettle
  83
  84 The command automatically fetches and converts to Guix the “Nix
  85 expression” of Nettle.
  86
  87 * Porting the Guix distro on a new platform
  88
  89 ** Introduction
  90
  91 Unlike Make or similar build tools, Guix requires absolutely /all/ the
  92 dependencies of a build process to be specified.
  93
  94 For a user-land software distribution, that means that the process that
  95 builds GCC (then used to build all other programs) must itself be
  96 specified; and the process to build the C library to build that GCC; and
  97 the process to build the GCC to build that library; and...  See the
  98 problem?  Chicken-and-egg.
  99
 100 To break that cycle, the distro starts from a set of pre-built
 101 binaries–usually referred to as “bootstrap binaries.”  These include
 102 statically-linked versions of Guile, GCC, Coreutils, Make, Grep, sed,
 103 etc., and the GNU C Library.
 104
 105 This section describes how to build those bootstrap binaries when
 106 porting to a new platform.
 107
 108 ** When the platform is supported by Nixpkgs
 109
 110 In that case, the easiest thing is to bootstrap the distro using
 111 binaries from Nixpkgs.
 112
 113 To do that, you need to comment out the definitions of
 114 ‘%bootstrap-guile’ and ‘%bootstrap-inputs’ in distro/packages/bootstrap.scm
 115 to force the use of Nixpkgs derivations.  For instance, when porting to
 116 ‘i686-linux’, you should redefine these variables along these lines:
 117
 118 #+BEGIN_SRC scheme
 119   (define %bootstrap-guile
 120     (nixpkgs-derivation "guile" "i686-linux"))
 121
 122   (define %bootstrap-inputs
 123     (compile-time-value
 124      `(("libc" ,(nixpkgs-derivation "glibc" "i686-linux"))
 125        ,@(map (lambda (name)
 126                 (list name (nixpkgs-derivation name "i686-linux")))
 127               '("gnutar" "gzip" "bzip2" "xz" "patch"
 128                 "coreutils" "gnused" "gnugrep" "bash"
 129                 "gawk"                                ; used by `config.status'
 130                 "gcc" "binutils")))))
 131 #+END_SRC
 132
 133 That should allow the distro to be bootstrapped.
 134
 135 Then, the tarballs containing the initial binaries of Guile, Coreutils,
 136 GCC, libc, etc. need to be built.  To that end, run the following
 137 commands:
 138
 139 #+BEGIN_SRC sh
 140   ./pre-inst-env guix-build -K                                    \
 141       -e '(@ (gnu packages make-bootstrap) %bootstrap-tarballs)'  \
 142       --system=i686-linux
 143
 144 #+END_SRC
 145
 146 These should build tarballs containing statically-linked tools usable on
 147 that system.
 148
 149 In the source tree, you need to install binaries for ‘mkdir’, ‘bash’,
 150 ‘tar’, and ‘xz’ under ‘distro/packages/bootstrap/i686-linux’.  These
 151 binaries can be extracted from the static-binaries tarball built above.
 152
 153 A rule for ‘distro/packages/bootstrap/i686-linux/guile-2.0.7.tar.xz’
 154 needs to be added in ‘Makefile.am’, with the appropriate hexadecimal
 155 vrepresentation of its SHA256 hash.
 156
 157 You may then revert your changes to ‘bootstrap.scm’.  For the variables
 158 ‘%bootstrap-coreutils&co’, ‘%bootstrap-binutils’, ‘%bootstrap-glibc’,
 159 and ‘%bootstrap-gcc’, the expected SHA256 of the corresponding tarballs
 160 for ‘i686-linux’ (built above) must be added.
 161
 162 This should be enough to bootstrap the distro without resorting to
 163 Nixpkgs.
 164
 165 ** When the platform is *not* supported by Nixpkgs
 166
 167 In that case, the bootstrap binaries should be built using whatever
 168 tools are available on the target platform.  That is, the tarballs and
 169 binaries show above must first be built manually, using the available
 170 tools.
 171
 172 They should have the same properties as those built by the Guix recipes
 173 shown above.  For example, all the binaries (except for glibc) must be
 174 statically-linked; the bootstrap Guile must be relocatable (see patch in
 175 the Guix distro); the static-binaries tarball must contain the same
 176 programs (Coreutils, Grep, sed, Awk, etc.); and so on.
 177