Funtoo:Evolved Bootstrap/CLFS Bootstrap Process

The purpose of this page is to document the bootstrap process used by CLFS. It's interesting and deserves some explanation as if you are coming from the Gentoo or Funtoo world may seem a bit unusual.

Host System

First, of course, for CLFS you must start with a host Linux or Linux-like system that you can use as a starting point. The host system need not be the same architecture as the final target system.

The Various Components of a Cross Build

Next, CLFS wants you to locate where you will install your 'final' system to, and set the $CLFS environment variable to point to this location. The CLFS book instructs you to create a new partition for this location, which is not strictly necessary and really any directory will do -- up until the point where you might want to actually boot into the new system, at which point of course you will want to copy its contents to a real root filesystem.

Within $CLFS, the build process has two separate directory trees, housed at $CLFS/tools and $CLFS/cross-tools. We'll explain the purpose of these directories in the following paragraph, but before we do, it's worth noting that the CLFS book instructs you to create two symbolic links at the root of your host file system -- /tools and /clfs-tools -- which point to these directories. This is kind of unfortunate as it means that the CLFS instructions won't work as-is on a system where you may not have root access, as to create these symlinks you will need superuser permissions on the host. Later on this page, we will explore ways to work around this.

OK, now on to those two directories. The cross-tools directory (living at $CLFS/cross-tools, and with the /cross-tools symlink pointing to it) is designed to contain programs that run on the native architecture of your host system, but contain the cross-compiler and associated tooling to build the non-native target binaries, libraries, and kernel.

The tools directory (living at $CLFS/tools, and with the /tools symlink pointing to it) is an interesting one and is somewhat counter-intuitive -- it will contain binaries and libraries that are built for the instruction set of the target architecture, so they will not directly run on the host system. You may think that, therefore, $CLFS/tools contains the final binaries and libraries for your target system -- ie. the target root filesystem -- but you would be incorrect. $CLFS instead contains the target rootfs, which is what you will eventually boot into or fchroot into. So what, then, is this tools directory? Well, when you chroot, it will exist at /tools, and it's meant to contain a primitive environment that will allow you to install your final things to / and /usr. Think of it sort of like an /opt directory containing your temporary toolchain that works on your target architecture until you get all your perfect, final packages built and installed to their official locations.

So when you chroot, you'll chroot into $CLFS -- but you will set your path as follows (this is a snippet from the actual CLFS chroot invocation):

PATH=/bin:/usr/bin:/sbin:/usr/sbin:/tools/bin

What this does above is look first for binaries in /bin, /usr/bin, /sbin and /usr/sbin -- which after first chroot are totally empty -- but will fall back to the temporary set of tools in /tools/bin. This means you can gradually build your "final" system within the chroot, with your final binaries and libraries gradually superseding those temporary more minimal initial builds of the tools.

I hope that helps people to understand the CLFS build process and how it all fits together. This larger context is important to make sense of how it all works but I found that these various components and their inter-relationships are not explained sufficiently in the main CLFS book.

Gentoo and Funtoo Equivalence

So, how does this all map to Gentoo and Funtoo stages?

The cross-tools don't really have an equivalent in regular stages as the stage1/2/3 build process is not a cross-build., The tools loosely equate to a Gentoo stage1, although they are different. In Gentoo and Funtoo, we chroot into a stage1 and build a stage2 and stage3 on top of the stage1 which is the root filesystem, whereas in the CLFS build approach, the 'final' system is installed into the rootfs but the stage1-equivalent exists in its own separate directory tree at /tools. So in Gentoo and Funtoo, stage1 is overwritten but in CLFS, /tools gradually becomes superseded via PATH with final tools and libraries in their official locations until nothing in /tools is used and it can simply be removed.

Why the Root Symlinks?

Here, we explore the reasons why the CLFS book has you create the /tools and /cross-tools symlinks on your host's root filesystem. It would be nice to eliminate this requirement but before we can change this, we must clearly understand the purpose behind it in the first place so that we make the proper adjustments. Note that I am documenting this to the best of my understanding at the moment, and that I may have to add additional details to this section as I learn more.

From what I can tell, the /cross-tools symlink is simply a convenience feature to save typing, so that --prefix=/cross-tools, for example, can be passed to configure scripts. So I don't think there is any technical reason why references to /cross-tools couldn't be replaced 1:1 with references to $CLFS/cross-tools.

The /tools path, on the other hand, may be a bit trickier. I need to confirm this, but I believe that since the path of /tools is used on the host, the tools are aware that they are located at this path at build time, but then when chrooted into $CLFS, the tools are also located at /tools within the chroot. Thus, the cross-compile tools haven't 'moved' from their perspective between build time and run time. I believe that this likely eliminates the need to perform some path magic in various places -- at the very least mess with pkgconfig files, likely a few other things -- that would otherwise complicate the build steps for these tools.

If this is correct, and I believe it is -- then it may at first seem quite complicated to get rid of the requirement for the creation of the /tools symlink on the host system, since it provides a clean way for "path equivalence" between outside the chroot on the host, and within the chroot on the target architecture. However, it should also be possible, with a simple workaround, to use a path in the user's home directory on the host directly, such as /home/drobbins/clfs/tools as what gets passed to configure scripts -- as long as we ensure that this path structure also exists within the chroot. We can do this by simply creating a symlink within the target rootfs as follows:

user $ cd /home/drobbins/clfs
user $ install -d home/drobbins/clfs
user $ cd home/drobbins/clfs 
user $ ln -sf /tools tools

Basically, what this does is create a symlink inside the chroot at /home/drobbins/clfs/tools which points to the actual location of /tools within the chroot, which should achieve the same result. Of course, if you use a directory in /var/tmp on the host to do your work, this may translate better into the chroot without having to create a fake home directory to accomplish this.

So based on my understanding of this right now, it should be possible to eliminate both symlinks on the host's root filesystem which require superuser privileges and are thus not optimal for performing a CLFS build starting out under a regular user account. With some tweaks, it should be possible to complete all pre-chroot CLFS steps within a regular user home directory.