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.

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)

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:

$ mkdir -p ~/cd/usr/include
$ cp -a /usr/include/asm* /usr/include/linux ~/cd/usr/include

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).

$ cd ~/cd/src/binutils-*
$ ./configure --prefix=/usr --target=<target> --with-sysroot=~/cd
$ make all && make install

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:

$ cd ~/cd/src/glibc*
$ ./configure --prefix=/usr --build=<build> --host=<target> \
  --with-headers=~/cd/usr/include --without-cvs --disable-profile \
  --disable-debug --without-gd --enable-add-ons=nptl --with-tls \
  --without-__thread --enable-kernel=2.6
$ make cross-compiling=yes install-headers install_root=~/cd
$ cp -r include/* ~/cd/usr/include

Our next step is to build the cross-compiler:

$ cd ~/cd/src/gcc*
$ ./configure --prefix=/usr --target=<target> --with-sysroot=~/cd \
  --with-headers=~/cd/usr/include --disable-threads --disable-shared \
  --enable-language=c
$ make && make install

Our almost-final step is to build the glibc package (previously, we just used the header files):

$ cd ~/cd/src/glibc*
$ ./configure --prefix=/usr --libdir=/usr/lib --build=<build> \
  --host=<target> --with-headers=/usr/include --without-cvs \
  --disable-profile --disable-debug --without-gd \
  --enable-add-ons=nptl --with-tls --without-__thread --enable-kernel=2.6
$ make && make install install_root=~/cd

In our final step, we build the gcc package again, but now we enable support for C++ and shared libraries (which wasn't possible at first):

$ cd ~/cd/src/gcc*
$ ./configure --prefix=/usr --target=<target> --with-sysroot=~/cd \
  --with-headers=/usr/include --enable-threads=posix --enable-languages=c,++
$ make && make install

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.

Our first task is to build a Linux kernel.

$ cd ~/cd/src/linux-*
$ make menuconfig
$ make dep boot CROSS_COMPILE=<target>

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

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

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

# emerge --emptytree system

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.

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.

# emerge --oneshot --emptytree glibc binutils glibc
# emerge --emptytree world

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

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.