doc: Add `HACKING'.

* HACKING: New file.
* Makefile.am (EXTRA_DIST): Add it.

2 files changed, 120 insertions, 0 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000000..500d2e3bf0
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,119 @@
+-*- mode: org; coding: utf-8; -*-
+
+#+TITLE: Hacking Guix and its incredible distro
+
+Copyright © 2012 Ludovic Courtès <ludo@gnu.org>
+
+  Copying and distribution of this file, with or without modification,
+  are permitted in any medium without royalty provided the copyright
+  notice and this notice are preserved.
+
+
+* Porting the Guix distro on a new platform
+
+** Introduction
+
+Unlike Make or similar build tools, Guix requires absolutely /all/ the
+dependencies of a build process to be specified.
+
+For a user-land software distribution, that means that the process that
+builds GCC (then used to build all other programs) must itself be
+specified; and the process to build the C library to build that GCC; and
+the process to build the GCC to build that library; and...  See the
+problem?  Chicken-and-egg.
+
+To break that cycle, the distro starts from a set of pre-built
+binaries–usually referred to as “bootstrap binaries.”  These include
+statically-linked versions of Guile, GCC, Coreutils, Make, Grep, sed,
+etc., and the GNU C Library.
+
+This section describes how to build those bootstrap binaries when
+porting to a new platform.
+
+** When the platform is supported by Nixpkgs
+
+In that case, the easiest thing is to bootstrap the distro using
+binaries from Nixpkgs.
+
+To do that, you need to comment out the definitions of
+‘%bootstrap-guile’ and ‘%bootstrap-inputs’ in distro/packages/base.scm
+to force the use of Nixpkgs derivations.  For instance, when porting to
+‘i686-linux’, you should redefine these variables along these lines:
+
+#+BEGIN_SRC scheme
+  (define %bootstrap-guile
+    (nixpkgs-derivation "guile" "i686-linux"))
+  
+  (define %bootstrap-inputs
+    (compile-time-value
+     `(("libc" ,(nixpkgs-derivation "glibc" "i686-linux"))
+       ,@(map (lambda (name)
+                (list name (nixpkgs-derivation name "i686-linux")))
+              '("gnutar" "gzip" "bzip2" "xz" "patch"
+                "coreutils" "gnused" "gnugrep" "bash"
+                "gawk"                                ; used by `config.status'
+                "gcc" "binutils")))))
+#+END_SRC
+
+That should allow the distro to be bootstrapped.
+
+Then, the tarballs containing the initial binaries of Guile, Coreutils,
+GCC, libc, etc. need to be built.  To that end, run the following
+commands:
+
+#+BEGIN_SRC sh
+  ./pre-inst-env guix-build                                       \
+      -e '(@@ (distro packages base) %guile-bootstrap-tarball)'   \
+      --system=i686-linux
+  
+  ./pre-inst-env guix-build                                               \
+      -e '(@@ (distro packages base) %bootstrap-binaries-tarball)'        \
+      --system=i686-linux
+  
+  ./pre-inst-env guix-build                                               \
+      -e '(@@ (distro packages base) %binutils-bootstrap-tarball)'        \
+      --system=i686-linux
+  
+  ./pre-inst-env guix-build                                       \
+      -e '(@@ (distro packages base) %glibc-bootstrap-tarball)'   \
+      --system=i686-linux
+  
+  ./pre-inst-env guix-build                                       \
+      -e '(@@ (distro packages base) %gcc-bootstrap-tarball)'     \
+      --system=i686-linux
+  
+#+END_SRC
+
+These should build tarballs containing statically-linked tools usable on
+that system.
+
+In the source tree, you need to install binaries for ‘mkdir’, ‘bash’,
+‘tar’, and ‘xz’ under ‘distro/packages/bootstrap/i686-linux’.  These
+binaries can be extracted from the static-binaries tarball built above.
+
+A rule for
+‘distro/packages/bootstrap/i686-linux/guile-bootstrap-2.0.6.tar.xz’
+needs to be added in ‘Makefile.am’, with the appropriate hexadecimal
+vrepresentation of its SHA256 hash.
+
+You may then revert your changes to ‘base.scm’.  For the variables
+‘%bootstrap-coreutils&co’, ‘%bootstrap-binutils’, ‘%bootstrap-glibc’,
+and ‘%bootstrap-gcc’, the expected SHA256 of the corresponding tarballs
+for ‘i686-linux’ (built above) must be added.
+
+This should be enough to bootstrap the distro without resorting to
+Nixpkgs.
+
+** When the platform is *not* supported by Nixpkgs
+
+In that case, the bootstrap binaries should be built using whatever
+tools are available on the target platform.  That is, the tarballs and
+binaries show above must first be built manually, using the available
+tools.
+
+They should have the same properties as those built by the Guix recipes
+shown above.  For example, all the binaries (except for glibc) must be
+statically-linked; the bootstrap Guile must be relocatable (see patch in
+the Guix distro); the static-binaries tarball must contain the same
+programs (Coreutils, Grep, sed, Awk, etc.); and so on.
+
diff --git a/Makefile.am b/Makefile.am
index e2c1cfd218..623a07a7f1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -103,6 +103,7 @@ LOG_COMPILER =					\
   $(GUILE) --no-auto-compile -L "$(top_srcdir)"
 
 EXTRA_DIST =					\
+  HACKING					\
   .dir-locals.el				\
   build-aux/download.scm			\
   srfi/srfi-64.scm				\