HACKING

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