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 * Porting the Guix distro on a new platform
  13
  14 ** Introduction
  15
  16 Unlike Make or similar build tools, Guix requires absolutely /all/ the
  17 dependencies of a build process to be specified.
  18
  19 For a user-land software distribution, that means that the process that
  20 builds GCC (then used to build all other programs) must itself be
  21 specified; and the process to build the C library to build that GCC; and
  22 the process to build the GCC to build that library; and...  See the
  23 problem?  Chicken-and-egg.
  24
  25 To break that cycle, the distro starts from a set of pre-built
  26 binaries–usually referred to as “bootstrap binaries.”  These include
  27 statically-linked versions of Guile, GCC, Coreutils, Make, Grep, sed,
  28 etc., and the GNU C Library.
  29
  30 This section describes how to build those bootstrap binaries when
  31 porting to a new platform.
  32
  33 ** When the platform is supported by Nixpkgs
  34
  35 In that case, the easiest thing is to bootstrap the distro using
  36 binaries from Nixpkgs.
  37
  38 To do that, you need to comment out the definitions of
  39 ‘%bootstrap-guile’ and ‘%bootstrap-inputs’ in distro/packages/base.scm
  40 to force the use of Nixpkgs derivations.  For instance, when porting to
  41 ‘i686-linux’, you should redefine these variables along these lines:
  42
  43 #+BEGIN_SRC scheme
  44   (define %bootstrap-guile
  45     (nixpkgs-derivation "guile" "i686-linux"))
  46
  47   (define %bootstrap-inputs
  48     (compile-time-value
  49      `(("libc" ,(nixpkgs-derivation "glibc" "i686-linux"))
  50        ,@(map (lambda (name)
  51                 (list name (nixpkgs-derivation name "i686-linux")))
  52               '("gnutar" "gzip" "bzip2" "xz" "patch"
  53                 "coreutils" "gnused" "gnugrep" "bash"
  54                 "gawk"                                ; used by `config.status'
  55                 "gcc" "binutils")))))
  56 #+END_SRC
  57
  58 That should allow the distro to be bootstrapped.
  59
  60 Then, the tarballs containing the initial binaries of Guile, Coreutils,
  61 GCC, libc, etc. need to be built.  To that end, run the following
  62 commands:
  63
  64 #+BEGIN_SRC sh
  65   ./pre-inst-env guix-build                                       \
  66       -e '(@@ (distro packages base) %guile-bootstrap-tarball)'   \
  67       --system=i686-linux
  68
  69   ./pre-inst-env guix-build                                               \
  70       -e '(@@ (distro packages base) %bootstrap-binaries-tarball)'        \
  71       --system=i686-linux
  72
  73   ./pre-inst-env guix-build                                               \
  74       -e '(@@ (distro packages base) %binutils-bootstrap-tarball)'        \
  75       --system=i686-linux
  76
  77   ./pre-inst-env guix-build                                       \
  78       -e '(@@ (distro packages base) %glibc-bootstrap-tarball)'   \
  79       --system=i686-linux
  80
  81   ./pre-inst-env guix-build                                       \
  82       -e '(@@ (distro packages base) %gcc-bootstrap-tarball)'     \
  83       --system=i686-linux
  84
  85 #+END_SRC
  86
  87 These should build tarballs containing statically-linked tools usable on
  88 that system.
  89
  90 In the source tree, you need to install binaries for ‘mkdir’, ‘bash’,
  91 ‘tar’, and ‘xz’ under ‘distro/packages/bootstrap/i686-linux’.  These
  92 binaries can be extracted from the static-binaries tarball built above.
  93
  94 A rule for
  95 ‘distro/packages/bootstrap/i686-linux/guile-bootstrap-2.0.6.tar.xz’
  96 needs to be added in ‘Makefile.am’, with the appropriate hexadecimal
  97 vrepresentation of its SHA256 hash.
  98
  99 You may then revert your changes to ‘base.scm’.  For the variables
 100 ‘%bootstrap-coreutils&co’, ‘%bootstrap-binutils’, ‘%bootstrap-glibc’,
 101 and ‘%bootstrap-gcc’, the expected SHA256 of the corresponding tarballs
 102 for ‘i686-linux’ (built above) must be added.
 103
 104 This should be enough to bootstrap the distro without resorting to
 105 Nixpkgs.
 106
 107 ** When the platform is *not* supported by Nixpkgs
 108
 109 In that case, the bootstrap binaries should be built using whatever
 110 tools are available on the target platform.  That is, the tarballs and
 111 binaries show above must first be built manually, using the available
 112 tools.
 113
 114 They should have the same properties as those built by the Guix recipes
 115 shown above.  For example, all the binaries (except for glibc) must be
 116 statically-linked; the bootstrap Guile must be relocatable (see patch in
 117 the Guix distro); the static-binaries tarball must contain the same
 118 programs (Coreutils, Grep, sed, Awk, etc.); and so on.
 119