Project:Prefix/Manual Bootstrap

How to bootstrap Gentoo Prefix on your UNIX-like system

Introduction
Bootstrapping on a UNIX-like system can range from being fairly simple to just a downright disaster. Systems that typically belong to the "simple" group, are Mac OS X, FreeBSD and recent distributions of Linux not being SuSE or Ubuntu. The "disaster" systems are NetBSD, OpenBSD and Ubuntu: they are NOT supported. Somewhere in the middle is Solaris 10, with OpenIndiana being a shift towards the "simple" group.

Don't let yourself be scared away immediately by this. For instance, a bootstrap on Solaris 10 may be quite flawless, because many went ahead of you, and ironed out a smooth path.

In general, when bootstrapping, make sure you have a clean and lean environment. Exclude any software providing repositories such as Blastwave, Fink, MacPorts, Homebrew, ports, etc. by default, e.g. make sure your shell doesn't automatically load any environment variables that setup those repositories. Think of,  ,  ,  ,   and the always harmful. This is important, because Prefix tends to be very sensitive about this. Afterall, it's whole purpose is to provide all of those tools by itself without external help!

If you happen to run into trouble, don't despair (immediately). Feel free to ask in the  IRC channel, or the gentoo-alt mailing list.

Bootstrapping
As prerequisite, you have to have a working compiler, e.g.  and   installed. Without a compiler, linker and all that is required by those to compile a program such as system headers and libraries, any Prefix bootstrap will fail almost immediately.

The first step is to choose a path to install into. We refer to this path as "Prefix path", stored in the variable. Some suggestion for your Prefix path is. Whatever you chose, make sure you set it in your environment:

Next, add the following paths in your soon to be Prefix to your  environment. ,, and. Adding these paths makes sure that they will be available later on in the process.

Now the  is set, start with downloading the bootstrap script from. This script needs bash. If you don't have bash on your system (typically BSD users don't), you'll have to bootstrap bash first, using. You can use ,   or   if they are available. Downloading them with a web-browser is also fine.

From the directory where the bootstrap script was stored execute the following commands:

The stage1 should have installed some basic packages necessary to run Portage, without Portage's help. When stage1 finished successfully, a Portage can be installed.

The Portage tree installed by default is a known to be good snapshot. This can, however, for various reasons not be good enough, in which case the lastest snapshot available can be used instead. Only use this when you have problems with the known to be good snapshot. If you want to use the lastest snapshot when bootstrapping, export LATEST_TREE_YES=1 in your environment before running the following:

We continue with emerging some of the core toolchain packages that make sure we compile and link everything taking the Prefix into account. Next to that this step emerges the full set of applications and that Portage needs and removes the tools installed by stage1. It finishes things by getting an up-to-date tree (removing any hacks stage2 applied to the activated profile) and emerging everything in the  set.

Because we installed some new applications, most notably Portage, we will instruct bash to reconsider all paths we have:

Now is a good time to set the preferences for your Prefix. This includes customisations such as general  -flags,   and   in. Be conservative with ! The stage3 function already set some moderate defaults.

Since we have everything in place for a self-catered rebuild, we can start the final stage to install the Prefix system. This final stage recompiles everything in the system, but now all packages can be compiled with tools from the Prefix, instead of those from the host system.

After  has emerged successfully, your Prefix will be set up properly, and you can emerge the whichever tools you choose from the Prefix tree.

Using the Prefix
To use your bootstrapped Prefix environment, you best start a shell from the Prefix, such that your path and other environment variables are set correctly. To facilitate in this, a small helper script can be created by the bootstrap script.

After running this, a script  will be present in. You can freely move the script to e.g. your homedir for convenience. Running the script will drop you into a Prefix shell, where for example  is directly at your disposal. Enjoy your Prefix!

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:
 * Fabian Groffen