aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2012-10-25 23:44:27 +0200
committerLudovic Courtès <ludo@gnu.org>2012-10-25 23:44:27 +0200
commit450ccdc3aae6d1a0f1685de3bef4d962e18c3855 (patch)
tree8f4eb256631f37d5a257cfd903a14b8604038279
parentfbc93bedff2a419305038564232837aff52513d2 (diff)
downloadguix-450ccdc3aae6d1a0f1685de3bef4d962e18c3855.tar
guix-450ccdc3aae6d1a0f1685de3bef4d962e18c3855.tar.gz
doc: Add `HACKING'.
* HACKING: New file. * Makefile.am (EXTRA_DIST): Add it.
-rw-r--r--HACKING119
-rw-r--r--Makefile.am1
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 \