doc: Add a "Porting" section.

* HACKING (Porting the Guix distro on a new platform): Remove.
* doc/guix.texi (Porting): New node.  Describe cross-compilation as the
  only approach.
This commit is contained in:
Ludovic Courtès 2013-07-07 01:02:48 +02:00
parent 401c53c469
commit 8b315a6dd5
2 changed files with 30 additions and 91 deletions

91
HACKING
View file

@ -127,94 +127,3 @@ after two weeks, and if youre confident, its OK to commit.
That last part is subject to being adjusted, allowing individuals to commit
directly on non-controversial changes on parts theyre familiar with.
* 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
binariesusually referred to as “bootstrap binaries.” These include
statically-linked versions of Guile, GCC, Coreutils, 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 gnu/packages/bootstrap.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 -K \
-e '(@ (gnu packages make-bootstrap) %bootstrap-tarballs)' \
--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 gnu/packages/bootstrap/i686-linux. These
binaries can be extracted from the static-binaries tarball built above.
A rule for gnu/packages/bootstrap/i686-linux/guile-2.0.7.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 bootstrap.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.