Gentoo Prefix Bootstrap Process for Mac OS X

1. Bootstrapping on OS X

Apple Mac OS X was initially supported in the main Gentoo portage tree with the ppc-macos keyword. The approach taken then, however, resulted in too many problems, which was the drive behind creating Prefixed Portage.

Bootstrapping on OS X is relatively simple, as the system itself provides most of the tools get up to speed quickly. Prefixed Portage is tested and supported on Mac OS X Tiger and Leopard on PPC and x86 architectures. Tests on PPC Panther were successful, but the platform itself isn't fully supported any more.

Bootstrapping

As prerequisite, you have to have latest Xcode installed. Xcode provides the compiler collection. Bootstrapping is not (yet) supported without it. If you don't have the latest Xcode installed and run into trouble, you can try gcc_select 3.3 as root.

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 suggestions for your Prefix path are $HOME/Gentoo or $HOME/Library/Gentoo. Whatever you chose, make sure you set it in your environment:

Code Listing 1.1: Export EPREFIX variable

$ export EPREFIX="$HOME/Gentoo"

Note: tcsh users can use setenv EPREFIX "$HOME/Gentoo" instead.

Next, add the following paths in your soon to be Prefix to your PATH environment. $EPREFIX/bin, $EPREFIX/usr/bin, $EPREFIX/tmp/bin and $EPREFIX/tmp/usr/bin. Adding these paths makes sure that they will be available later on in the process.

Code Listing 1.2: Add Prefix paths to your PATH

$ export PATH="$EPREFIX/usr/bin:$EPREFIX/bin:$EPREFIX/tmp/usr/bin:$EPREFIX/tmp/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:

Code Listing 1.3: Use the bootstrap script

$ chmod 755 bootstrap-prefix.sh
$ ./bootstrap-prefix.sh $EPREFIX tree
$ ./bootstrap-prefix.sh $EPREFIX/tmp wget
$ ./bootstrap-prefix.sh $EPREFIX/tmp sed
$ ./bootstrap-prefix.sh $EPREFIX/tmp python
$ ./bootstrap-prefix.sh $EPREFIX/tmp coreutils6
$ ./bootstrap-prefix.sh $EPREFIX/tmp findutils
$ ./bootstrap-prefix.sh $EPREFIX/tmp tar15
$ ./bootstrap-prefix.sh $EPREFIX/tmp patch9
$ ./bootstrap-prefix.sh $EPREFIX/tmp grep
$ ./bootstrap-prefix.sh $EPREFIX/tmp gawk
$ ./bootstrap-prefix.sh $EPREFIX/tmp bash
$ ./bootstrap-prefix.sh $EPREFIX portage

Note: Please note that wget, sed, python, etc. are installed in $EPREFIX/tmp!

The script 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:

Code Listing 1.4: Setup ld directions

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

Note: The -search_paths_first flag is OSX/odcctools only. It instructs the linker to look first in the provided paths, then if that fails in the system (default) paths. This is the default behaviour for many other linkers, including GNU binutils' one as used on Linux.

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

Code Listing 1.5: rehash in bash

$ hash -r

Note: tcsh users can use the rehash command.

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

Code Listing 1.6: emerge sed

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

Code Listing 1.7: emerge bash and wget

$ emerge --oneshot --nodeps wget
$ emerge --oneshot bash

Note: It is safe to ignore the "1 config files in XXX need updating" message that appears till the end of the bootstrap process.

Now, we will emerge a compiler and linker, setup to make use of the Gentoo Prefix environment. The packages to emerge include the baselayout package. Some, if not many, scripts and tools within a Gentoo system assume the availability of the baselayout package for all communication using the Gentoo colour scheme.

Code Listing 1.8: emerge linker and compiler

$ emerge --oneshot --nodeps baselayout-prefix
$ emerge --oneshot --nodeps flex
$ emerge --oneshot --nodeps binutils-config
$ emerge --oneshot --nodeps odcctools
$ emerge --oneshot --nodeps gcc-config
$ emerge --oneshot --nodeps gcc-apple

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.

Code Listing 1.9: unset no longer needed environment variables

$ unset LDFLAGS CPPFLAGS CHOST CC CXX HOSTCC

Note: tcsh users can use unsetenv LDFLAGS, etc.

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.

Code Listing 1.10: emerge several tools

$ emerge --oneshot coreutils
$ emerge --oneshot findutils
$ emerge --oneshot tar
$ emerge --oneshot grep
$ emerge --oneshot gawk
$ emerge --oneshot patch
$ 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.

Code Listing 1.11: emerge portage

$ env FEATURES="-collision-protect" emerge --oneshot portage

Now we have emerged everything we bootstrapped before, we remove the temporary directory and its use as it is no longer necessary.

Code Listing 1.12: remove tmp directory

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

Code Listing 1.13: Updating the tree

$ emerge --sync

Note: The Prefix Portage tree assumes a case-sensitive filesystem. Mac OS X doesn't use this by default. If you experience weird errors while updating or checking out the Prefix tree with subversion, check if your filesystem is case-sensitive.

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

Code Listing 1.14: emerge system

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

Code Listing 1.15: Customising the Prefix installation - example

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

Note: You have to replace <my-cpu-flags> with something that matches your CPU. Intel-based Mac 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=nocona. PPC users can use their CPU's alias to enable CPU specific tuning, e.g. -mcpu=G5 -mtune=G5.

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.16: 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 script.

Code Listing 1.17: 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 are licensed under the Creative Commons - Attribution / Share Alike license.