Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



Using the Darwin/Mac OS X bootstrap script

This script will bootstrap Mac OS X and Darwin systems. If you already have portage installed, it can be found in /usr/portage/scripts, otherwise the current version can be downloaded here.

In its current state, its a fairly dumb script, so it should always be run from the directory containing it.

Once you are in the directory containing the file, make sure it is executable by using the chmod command.

chmod a+x

Bootstrapping Gentoo for Mac OS X Standard

Most users will want to use the 'Standard' Gentoo for Mac OS X install. It utilizes the feature 'collision-protect' that prevents portage from overwriting any files that itself does not own(i.e. apple provided files, user installed files)

You can bootstrap the Standard install like this:

./bootstrap-darwin standard

If an existing portage install is found, the script will simply check the OS X version, and set the correct profile symlink for /etc/make.profile.

If an existing portage install is NOT found, the script will check for the presence of Xcode, then install the current pkg available from the main site and prompt you to emerge sync then emerge the base system, if no errors occured, the result is a complete Gentoo for Mac OS X system ready to go.

Bootstrapping Gentoo for Mac OS X Progressive

The Gentoo for Mac OS X Progressive install utilizes a profile that allows portage to install packages which may overwrite files provided by Apple. Currently this is only recommended for developers and advanced users.

./bootstrap-darwin progressive

This will first install the current version of Python, followed by the current version of portage(this time from source, unlike from the pkg installer in a Standard bootstrap). If both of these are successful, it will then prompt you to emerge sync and system. VOILA!

Bootstrapping a Gentoo for Mac OS X Disk Image

This will create a Disk Image in the Apple .dmg format with a basic OS X/Xcode install, and optionally bootstrap a Gentoo Standard or Progressive install on the image, which can be used as a chroot jail for testing and development.

To begin, you will need a Mac OS X 10.3 install CD or DVD, and the Xcode 1.5 Developer Tools.

Create a folder anywhere on your harddrive and name it 'Packages'. Insert the OS X install disc, and either in the Finder or in go to /Volumes/[DISCNAME]/System/Installation/Packages and copy the following files to your local Packages directory:

NOTE: if you are using the terminal to copy the packages, you should use ditto(1) and not cp

Now, eject the OS X install disc and insert the Xcode disc(or just mount the downloaded dmg if you didn't bother burning it) and go to /Volumes/Xcode\ Tools/Packages and copy(ditto) the following packages to the same folder as the OS X system packages:

It is highly recommended, but not required, that you download the OS X 10.3.8 Combined Update, mount the dmg, and copy(ditto) the pkg to the folder with the other system packages that will be used to build the Disk Image.

The bootstrap dmg script requires the following options:

./bootstrap-darwin dmg [packagedir] [dmgfile] [size] [volumename]

So the following line:

./bootstrap-darwin dmg ~/Desktop/Packages ~/Desktop/gentoosx.dmg 4.2 Gentoo

will create a 4.2 Gigabyte disk image called gentoosx.dmg using the install packages in ~/Desktop/Packages, and when mounted, will show up as 'Gentoo' . Note that the size MUST be in gigabytes and the volume name should not contain spaces or special characters.

After the disk image is created and the OS X base system packages have been installed, you will be prompted whether you are creating a 'standard' or 'progressive' install. You will then be asked if you want to mount the image and chroot. If you answer yes, you will be greeted by the familiar bash prompt inside your new chroot.

We must now run again to get our portage tree and setup the appropriate profile.

For a Standard install:

cd /sbin
./ standard

For a Progressive install:

cd /sbin
./ progressive

When you want to leave your chroot, simply type 'exit' in the shell, and the installer will unmount the disk image for you. If you are lucky, the end result of all this is a 'pristine' environment suitable for building/testing packages, all contained in a nifty little dmg.

Using the chroot

Whenever you want to use your chroot, it is recommended you first mount a few special filesystems first. Begin by mounting your dmg like this:

hdiutil attach ~/Desktop/gentoosx.dmg -owners on

This will mount the disk image and use actual permissions, as opposed to the default OS X behavior of ignoring permissions on removable volumes.

Then mount devfs:

sudo mount -t devfs stdin /Volumes/Gentoo/dev
sudo mount -t fdesc -o union stdin /Volumes/Gentoo/dev

Now volfs:

sudo mount_volfs /Volumes/Gentoo/.vol

Once you have mounted all these, you can safely chroot:

sudo chroot /Volumes/Gentoo /bin/bash

Upon exiting, you will need to unmount the special filesystems before the disk image can be ejected. The next command will look odd, but we umount once for devfs, and once for the union mount, followed by volfs.

sudo umount /Volumes/Gentoo/dev
sudo umount /Volumes/Gentoo/dev
sudo umount /Volumes/Gentoo/.vol

If everything safely umounted, you can eject the image using either the Finder or hdiutil(1). I recommend writing a quick shell script to handle the mounting/unmounting of the filesystems for you.

Using this tutorial on a MacBook with Intel CPU

If you are using a MacBook with a Intel CPU you have to modify your /etc/make.conf this way:

File: /etc/make.conf
# Copyright 2004 Pieter Van den Abeele,
# Contains local system settings for Portage system on Mac OS X
# $Header$

# The Architecture 


# GCC flags

CFLAGS="-O2 -pipe"

# The next generation KEYWORD, including architecture, userland, kernel and libc


# Change to -j3 for dual processor machines.


# Feature collistion prevent portage from overwriting packages it didn't install itself


# The necessary code to make portage use curl instead of wget
# When these lines are removed, portage defaults to wget

FETCHCOMMAND="/usr/bin/curl --connect-timeout 15 -# -o \${DISTDIR}/\${FILE} \${URI}"
RESUMECOMMAND="/usr/bin/curl --connect-timeout 15 -# -C - -o \${DISTDIR}/\${FILE} \${URI}"
Retrieved from ""

Last modified: Fri, 05 Sep 2008 10:58:00 +0000 Hits: 18,188