ryan77627/guix
1
0
Fork 0
mirror of https://git.in.rschanz.org/ryan77627/guix.git synced 2024-11-07 07:26:13 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: Add a "Porting" section.

Browse source 
* 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
Show stats Download patch file Download diff file Expand all files Collapse all files

91
HACKING
View file

@ -127,94 +127,3 @@ after two weeks, and if you’re confident, it’s OK to commit.
That last part is subject to being adjusted, allowing individuals to commit
directly on non-controversial changes on parts they’re 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
binaries–usually 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.

30
doc/guix.texi
View file

@ -1434,6 +1434,7 @@ tools that help users exert that freedom.
@menu
* Package Modules:: Packages from the programmer's viewpoint.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
@end menu
Building this distribution is a cooperative effort, and you are invited
@ -1588,6 +1589,35 @@ unknown, but if you would like to investigate further (and have
significant computational and storage resources to do so), then let us
know.
@node Porting
@section Porting to a New Platform
As discussed above, the GNU distribution is self-contained, and
self-containment is achieved by relying on pre-built ``bootstrap
binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
operating system kernel, CPU architecture, and application binary
interface (ABI). Thus, to port the distribution to a platform that is
not yet supported, one must build those bootstrap binaries, and update
the @code{(gnu packages bootstrap)} module to use them on that platform.
Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
When everything goes well, and assuming the GNU tool chain supports the
target platform, this can be as simple as running a command like this
one:
@example
guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
@end example
In practice, there may be some complications. First, it may be that the
extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
above) is not recognized by all the GNU tools. Typically, glibc
recognizes some of these, whereas GCC uses an extra @code{--with-abi}
configure flag (see @code{gcc.scm} for examples of how to handle this.)
Second, some of the required packages could fail to build for that
platform. Lastly, the generated binaries could be broken for some
reason.
@c *********************************************************************
@node Contributing