Gentoo Bootstrapping GuideSven Vermeulen
Bootstrapping means to build a toolchain so that it is ready to build the rest
of your system. Gentoo is a perfect operating system to perform such
installation while retaining support from the software management system,
Portage.
0.12005-07-25What is Bootstrapping?Definition
Not only is this guide still in its early stage, it is also built on theoretical
information found on the Internet and not from experience. It should be taken
with a big grain of salt until the steps in it are verified and accepted by more
experienced people.

If we were to believe the stories, bootstrapping - the term - originates
from a German legend about Baron Münchhausen who was able to save himself from
drowning in a swamp by pulling himself up by his hairs.

In computer theory, bootstrapping has several meanings. All of them boil down to
building more complex systems from simple ones. This document will discuss
bootstrapping a toolchain: building a full cross-compilation environment able to
build software for the target system, followed by a rebuild of the system to the
native environment.

Sounds strange to you? Don't despair, we'll discuss all that in the rest of this
document...

Toolchain Bootstrapping

The process of bootstrapping a toolchain is three-fold.

At first, you use an existing toolchain to create a cross-compilation
environment, a toolchain capable of running on one system but building software
for a different one. The second step is to use the cross-compilation toolchain
to rebuild itself so that it builds code native to the system it is booted on.
The third step uses the native compiler to (re)build all packages (including
itself) so that every tool is built on the target system, for the target system.

There are three important terms we use in this definition:

the host system is the system on which the programs are ran,

the build system is the system on which a particular package is being
built, and

the target system is the system for which the software generates
output (like the compiler)

Each of those terms has a certain syntax used by the GNU compiler collection. It
is therefore adviseable to consult the online GCC documentation for more
information.

Installing Gentoo on an Unsupported PlatformCreating the Cross-Compilation Environment

We first reserve some space in the home directory to install the
cross-compilation environment in. We advise to perform the next steps as a
regular, unprivileged user, so that you can not harm the current system. After
all, we are going to rebuild core system packages on the system, ready for use
on a different system, and we don't want to overwrite the ones on the current
system ;)

$ mkdir ~/cd ~/cd/src

We'll store all source code and binaries inside ~/cd because
we will need to use those files to boot the new system when the first two phases
are complete.

At first, extract the source code for the following packages (or similar ones,
depending on your setup) inside the ~/cd/src directory:

gcc

The GNU Compiler Collection

glibc

The GNU C Library

binutils

The tools needed to build programs

vanilla-sources

The Linux kernel tree

These are just examples that are well known, but you can also try using the
Intel compiler with the ucLibc library, etc.

Copy over the header files from the kernel to the build root, allowing the other
tools to use the architecture-specific settings of the target architecture:

The next step is to build the binutils package suitable for
cross-compiling. It is recommended that you read the documentation of
binutils for precise instructions how to do this (just like you should
for the next packages, gcc, glibc and the Linux kernel).

Now that the binutils are available in the cross-compilation environment,
we install the glibc headers (the function & constant definitions of
the c library). Lucky for us, the fine folks at GNU have made this step easier
by adding a install-headers directive for make:

The ~/cd location now contains a minimal environment with the
cross-compiling toolchain. The next step is to build the core system packages so
that you are able to boot into the minimal environment later on.

Next, build the core packages required to succesfully boot the system. The set
of packages you'll need are:

coreutils

Standard set of (POSIX) commands

diffutils

Tools for displaying the differences between files

grep

Text pattern searcher

sed

Streaming text editor

make

Makefile parser

tar

Tape Archive tool

gzip

Compression tool

util-linux

Linux utilities

All these tools should be fairly easy to build. Generally, you can set the
following variables to declare your platform; the configure and
make steps will then use those variables to make their platform-dependant
decisions:

The last thing you'll need is a statically linked version of a shell, for
instance, bash:

$ TODO

Bootstrapping the Toolchain

Now that you have build a minimal environment inside ~/cd, we'll
rebuild the toolchain so that it not only builds for the target platform (which
it does already) but also builds on the target platform (it currently
only works on the current system).

The next step is to try and boot the system. The easiest approach is to
NFS-mount ~/cd/final and boot the target platform using the kernel
built at the beginning. Don't forget to set init=/bin/sh since the entire
bootup sequence stuff (like init) isn't available yet.

TODO inform how to boot from the CD and use an NFS-mounted root
file system.

Porting Portage

To be able to use Portage, we need to be able to use Python. Download the
sources in ~/cd/final/tmp (so that it is available for the booted
platform) and build it:

TODO

Next, download a Portage rescue set and install it. As Portage is a set of
Python scripts with bash scripts, this should have no further requirements after
installation:

TODO

Once installed, try to run emerge and ebuild to find out if they
appear to work:

$ emerge --info

Creating a Stage1 Tarball

Booted in the platform and with a working Portage, you are now ready to create a
stage1 tarball. Create a snapshot of your environment using tar:

TODO
Don't forget to talk about unmasking all packages...

Creating a Bootable Environment

Next, to make sure that you'll always be able to boot the system (and help
others as well), we'll create a bootable environment for the platform. Assuming
that all platforms have a CD-ROM drive they can boot from, we'll focus on such
environment.

TODO talk about creating bootable CD.

Finishing Off

All set. Right? Nope, but almost :-)

The most important step now is to inform the Gentoo community about what you've
accomplished. Make sure you pay a visit at #gentoo-dev on
irc.freenode.net and use our Gentoo
Forums to tell about the up and downfalls of your expedition. The most
difficult steps are finished!

Bootstrapping the SystemInstalling Gentoo

With the bootable environment at your disposal, you can now boot the target
system into a small Linux environment. Once booted, follow the installation
instructions inside the Gentoo Handbook to
the point where you chroot into your Gentoo environment. Of course, since you
only have a stage1 tarball at your disposal, you should use that one instead of
the stage3 used in the installation instructions.

After chrooting the system, you should update the Portage tree.

# emerge --sync

Using the Bootstrap Script

Next, we'll rebuild the toolchain provided by the stage1 tarball natively.
Gentoo provides a script that does this for you.

# /usr/portage/scripts/bootstrap.sh

Building the Core System

With the toolchain rebuild and ready for general usage, we'll build the core
system packages for the system:

# emerge --emptytree system

Finishing the Installation

Now that the core system packages are built, you can continue using the
installation instructions in the Gentoo Handbook. You will probably get a few
complaints by Portage telling you certain packages are masked. This is because
your architecture isn't supported by Gentoo yet, in which case you need to
unmask the packages in /etc/portage/package.keywords like you did
previously.

Creating a Fully Working Installation CD

If your entire installation has succeeded it is best to try and create an
installation CD for your platform using catalyst. Not only will this
require an additional profile (to support the new platform) but also some help
from the Gentoo developers themselves. On the other hand, if you've succeeded in
following all I've written until this part, you're probably already on your way
to become a developer yourself :)

The major benefit of using catalyst is that Gentoo is then able to create
official support for the platform. Not only will there be a fully functional
profile and keyword setting, but the core packages will be accepted for your
platform, stages will be build and a working installation CD, just like those
for the other architectures, will be available.

TODO Talk about using catalyst to create all needed stuff.

Frequently Asked Questions
Should I bootstrap when I want my entire system to use changed CFLAGS,
CXXFLAGS, USE settings and profile changes?

No. After your changes, you should rebuild the toolchain first, after which you
can rebuild the entire system using the new toolchain. When your system suffers
from circular dependencies, you'll need to rebuild the participants in that
circle. For instance, if openssl depends on python which depends
on perl which depends on openssl again (yes, this is a fictuous
example), rebuild all those packages too.

You don't need to bootstrap here because your architecture still remains the
same, as is the target system.

Should I bootstrap when I want my entire system to use changed CHOST settings?

Not if the system itself supports the new CHOST setting too (for instance,
i386-pc-linux-gnu and i686-pc-linux-gnu on a Pentium IV system). Otherwise, yes,
but then we are really interested in hearing how you managed to install Gentoo
using the current - wrong - CHOST settings in the first place ;)

If your system supports both CHOST settings, you can follow the same
instructions as given in the previous FAQ.