This document will attempt to describe how to bootstrap a Gentoo Prefix environment for many operating systems. Since it is nearly impossible to document every flavor of every OS, some creativity may be needed. This includes but is not limited to using the native package manager to install pre-requisites or compiling a few things by hand. It is generally recommended to not use Prefix as the root user. Especially, your first time using Gentoo Prefix.

Pre-requisite packages in your PATH should be:

• gcc
• bash (Greater than 2.01)
• wget or curl (or the ability to accquire files another way - browser, nfs, scp, etc)

Don't despair if things go wrong, it is not impossible. Feel free to ask in the gentoo-prefix IRC channel, or mailing list.

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 $HOME/gentoo or /opt/prefix. Whatever you chose, make sure you set it in your environment:

$ export EPREFIX="$HOME/gentoo"
        

Next, modify your PATH variable to include non-existant PATHs. This allows the process to build itself as you add more tools. Add the following, in order, to the beginning of your $PATH:

• $EPREFIX/bin
• $EPREFIX/usr/bin
• $EPREFIX/tmp/bin
• $EPREFIX/tmp/usr/bin

$ export PATH="$EPREFIX/usr/bin:$EPREFIX/bin:$EPREFIX/tmp/usr/bin:$EPREFIX/tmp/bin:/usr/bin:/bin:$PATH"
        

Now the path is set, start with downloading the bootstrap script from http://overlays.gentoo.org/proj/alt/browser/trunk/prefix-overlay/scripts/bootstrap-prefix.sh?format=txt. From the directory where the bootstrap script was stored execute the following commands:

$ chmod 755 bootstrap-prefix.sh
$ ./bootstrap-prefix.sh $EPREFIX tree
$ ./bootstrap-prefix.sh $EPREFIX/tmp make
$ ./bootstrap-prefix.sh $EPREFIX/tmp wget
$ ./bootstrap-prefix.sh $EPREFIX/tmp sed
$ ./bootstrap-prefix.sh $EPREFIX/tmp python
$ ./bootstrap-prefix.sh $EPREFIX/tmp coreutils
$ ./bootstrap-prefix.sh $EPREFIX/tmp findutils3
$ ./bootstrap-prefix.sh $EPREFIX/tmp tar
$ ./bootstrap-prefix.sh $EPREFIX/tmp patch
$ ./bootstrap-prefix.sh $EPREFIX/tmp grep
$ ./bootstrap-prefix.sh $EPREFIX/tmp gawk
$ ./bootstrap-prefix.sh $EPREFIX/tmp bash
$ ./bootstrap-prefix.sh $EPREFIX portage
        

The above will setup the $EPREFIX directory, download a portage tree snapshot, unpack it and download and install portage. Afterwards it will try to setup some sane defaults. We continue with a little hack necessary for a successful bootstrap:

$ export LDFLAGS="-L${EPREFIX}/usr/lib -R${EPREFIX}/usr/lib -L${EPREFIX}/lib -R${EPREFIX}/lib"
$ export CPPFLAGS="-I${EPREFIX}/usr/include"
        

Because we installed some new applications, we will instruct bash to reconsider all paths we have (this can safely be done more often and is a good idea):

$ hash -r
        

On Linux profiles, the following USE flags will create circular dependancies, so we disable them until later. (This is safe to do for all archs - but won't have any effect)

$ export USE="-nls -berkdb -gdbm -fortran -pcre"
        

We continue adding some necessary tools which will deal with many errors and warnings you might see during emerging.

$ emerge --oneshot sed
        

Next, we emerge the bash shell Portage heavily relies on. The same holds for wget, the download manager. Since its dependencies cannot be compiled at this stage, we ignore those for the moment.

$ emerge --oneshot --nodeps wget
$ emerge --oneshot =bash-3.2_p17-r1 (avoid autotools)
        

Now, we will emerge a compiler which will use the gnu linker. This is a requirement for many packages that follow in the bootstrap process, in particular Perl. This requires quite a few build time tools/deps.

$ emerge --oneshot --nodeps baselayout-prefix
$ emerge --oneshot --nodeps lzma-utils
$ emerge --oneshot --nodeps m4
$ emerge --oneshot --nodeps flex
$ emerge --oneshot --nodeps bison
$ emerge --oneshot --nodeps binutils-config
$ emerge --oneshot --nodeps binutils
$ emerge --oneshot --nodeps gcc-config
$ emerge --oneshot --nodeps gcc
        

Since the tools for building are now installed in your Prefix, the little helpers we used before are no longer necessary. They may even cause trouble, so we unset them.

$ unset LDFLAGS CPPFLAGS CHOST CC CXX HOSTCC
        

We continue getting more tools in our Prefix. We no longer ignore dependencies, so a lot of packages will be emerged at this stage. Slowly our Prefix gets more robust as we progress here.

$ emerge --oneshot coreutils
$ emerge --oneshot findutils
$ emerge --oneshot tar
$ emerge --oneshot grep
$ emerge --oneshot patch
$ emerge --oneshot gawk
$ emerge --oneshot make
        

Now we have a good bunch of programs that Portage needs, we can replace the bootstrapped Portage by a properly installed one, using Portage itself. Also here a few dependencies are first emerged, such as the language Portage is written in: python. We need to temporarily tell Portage that the bootstrapped Portage can be overwritten.

$ rm $EPREFIX/usr/share/man/man1/{env-update,quickpkg,dispatch-conf,repoman,emerge,emaint,ebuild,etc-update}.1
$ env FEATURES="-collision-protect" emerge --oneshot portage
        

Now we have emerged everything we bootstrapped in the first few steps, we remove the temporary directory and its contents because it is no longer necessary.

$ rm -Rf $EPREFIX/tmp/*
$ hash -r
        

Before we do any further merges, we are going to update our tree. Updating the tree is done using:

$ emerge --sync
        

Next, we let Portage emerge all packages that complete a system install that we eventually need to finish this Prefix installation.

$ emerge -u system
        

Now is a good time to set the preferences for our soon to be Prefix. This includes customisations such as general USE-flags, CFLAGS and MAKEOPTS in $EPREFIX/etc/make.conf. Be conservative with CFLAGS! Note that the code below is an example, and is meant for inspiration only.

$ echo 'USE="unicode nls"' >> $EPREFIX/etc/make.conf
$ echo 'CFLAGS="-O2 -pipe"' >> $EPREFIX/etc/make.conf
$ echo 'CXXFLAGS="${CFLAGS}"' >> $EPREFIX/etc/make.conf
        

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.

$ unset USE
$ 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.

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.

$ 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!