Gentoo Prefix Bootstrap Process for UNIX-like systems
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 PATH, CFFLAGS, CFLAGS,
LDFLAGS, PKG_CONFIG_PATH 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 gentoo-prefix
IRC channel, or gentoo-alt
IMPORTANT: Gentoo Prefix does NOT require root-privileges.
You don't have to be root to bootstrap a Prefix installation.
In fact, we highly discourage people to bootstrap as
As prerequisite, you have to have a working compiler, e.g.
gcc and make 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.
On Mac OS X systems, the compiler, linker, system headers and
libraries are provided by Xcode, or the Xcode command line
tools, available through the AppStore and ADC respectively.
On OpenIndiana, you need the a compiler, system headers and
more installed using pkg. Perform the following two
commands as super user: pkg set-publisher -p
http://pkg.openindiana.org/sfe/ and pkg install
sfe/developer/gcc developer/library/lint system/header.
The compiler and many useful other utilities will be available
On Solaris systems many useful utilities such as wget
and gcc are located in /usr/sfw/bin.
The first step is to choose a path to install into. We refer
to this path as "Prefix path", stored in the variable
EPREFIX. Some suggestion for your Prefix path is
Whatever you chose, make sure you set it in your environment:
Code Listing 1.1: Export EPREFIX variable
$ export EPREFIX="$HOME/gentoo"
tcsh users can use setenv EPREFIX "$HOME/gentoo"
Next, add the following paths in your soon to be Prefix to
your PATH environment.
Adding these paths makes sure that they will be available
later on in the process.
Code Listing 1.2: Add Prefix and temp paths to your PATH
$ export PATH="$EPREFIX/usr/bin:$EPREFIX/bin:$EPREFIX/tmp/usr/bin:$EPREFIX/tmp/bin:/usr/bin:/bin"
On Solaris you need the add the following paths to find
the GNU compiler, linker, make and some other tools:
for x86-based Solaris 10. Similar for sparc-based Solaris 10,
use sparc-sun-solaris2.10 instead. Solaris 11 users
have to replace the 2.10 by 2.11.
Most notably on Mac OS X and Solaris systems, both 32-bits and
64-bits modes are possible. These are so-called multilib
systems. If you know what this means, and you don't like the
default chosen by the bootstrap script, you can set your
CHOST environment variable to your liking.
Solaris/OpenSolaris/OpenIndiana systems always default to
32-bits, so if you want to end up with a 64-bits native Prefix
installation, then set your CHOST variable accordingly
to either x86_64-pc-solaris2.10 or
sparcv9-sun-solaris2.10 for Solaris 10, use 2.11
for versions later, including OpenIndiana.
Mac OS X Intel-based systems before Lion (10.7) always default
to 32-bits. From Lion and on, the default is 64-bits. If you
want a 64-bits native Prefix on pre-Lion systems, set your
CHOST to x86_64-apple-darwin9 for Leopard, or
x86_64-apple-darwin10 for Snow Leopard. If you want to
end up with a 32-bits native Prefix installation on Lion, set
your CHOST to i686-apple-darwin11.
Now the PATH 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
You can use wget, curl or ftp if they are
available. Downloading them with a web-browser is also fine.
If your system lacks bash by default, bootstrap it, using:
chmod 755 bootstrap-bash.sh; ./bootstrap-bash.sh
$EPREFIX/tmp and rehash afterwards: hash -r (sh)
or rehash (csh).
From the directory where the bootstrap script was stored execute
the following commands:
Code Listing 1.3: Use the bootstrap script for stage1
$ chmod 755 bootstrap-prefix.sh
$ ./bootstrap-prefix.sh $EPREFIX/tmp stage1
Please note the usage of $EPREFIX/tmp!
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:
Code Listing 1.4: bootstrap Portage and its tree
$ ./bootstrap-prefix.sh $EPREFIX stage2
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
Code Listing 1.5: bootstrap a self-hosted Portage
$ ./bootstrap-prefix.sh $EPREFIX stage3
Because we installed some new applications, most notably
Portage, we will instruct bash to reconsider all paths we
Code Listing 1.6: rehash in bash
$ hash -r
tcsh users can use the rehash command.
Now is a good time to set the preferences for your Prefix.
This includes customisations such as general USE-flags,
CFLAGS and MAKEOPTS in
$EPREFIX/etc/portage/make.conf. Be conservative with
CFLAGS! The stage3 function already set some moderate
You can consider adding CPU-specific tuning flags to
CFLAGS. If you don't know what your CPU is, or what
this would be good for, just skip this note.
Intel-based Mac OS X users (e.g. MacBook, CoreDuo) should at
least have -march=prescott here to avoid compilation
errors due to SSE instructions not being enabled. Core2Duo
users can use -march=core2. Mac OS X PPC users can use
their CPU's alias to enable CPU specific tuning, e.g.
For other systems, you might simply want to use
-march=<your-cpu>. Google the right value, or
just forget about this setting. Note that setting a wrong
value breaks things.
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.
Code Listing 1.7: doing the final system installation
$ emerge -e system
After system 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
Code Listing 1.8: Creating a start-script
$ cd $EPREFIX/usr/portage/scripts
$ ./bootstrap-prefix.sh $EPREFIX startscript
After running this, a script startprefix will be
present in $EPREFIX. 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 emerge
is directly at your disposal. Enjoy your Prefix!
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.
Page updated September 7, 2012
How to bootstrap Gentoo Prefix on your UNIX-like system
Donate to support our development efforts.