Gentoo Logo
Gentoo Logo Side

Gentoo For Mac OS X Installation and Usage Guide


1. Installation

System Requirements 

In order to install Gentoo for Mac OS X, you must have the following software already installed:

  • Mac OS 10.2 or later
  • XCode Tools 1.2 or later

Note: The XCode Tools can be downloaded at no cost from the Apple Developer Connection member site (free membership required).

Important: We strongly recommend that XCode be installed with the X11 SDK.

The Installer 

First, you'll need to download the Gentoo for Mac OS X installer disk image (dmg). When you mount the dmg image (by double clicking on it), its contents should be displayed on the screen in a finder window; the installer icon should be visible at this point. Run the installer, and follow the directions on screen. 

After the installer has finished and exited, you will need to open (or another terminal emulator). If you already have open, you'll need to open a new shell/window for the software insalled by the installer to be recognized by the terminal session.

Warning: Using any shell besides bash is currenly unsupported and most likely won't work. You should change your default shell in by clicking on Terminal->Preferences (in the menu bar), chosing the "Execute this command" option, and entering /bin/bash.

Updating Portage 

It's crucial to keep portage's package information database (commonly called the 'portage tree') up-to-date; it lives in /usr/portage . The portage tree holds information oabout every package that portage knows how to install, including directions that portage follows to install the package for you. It is important that we update this information to the latest available tree before we continue so that we know we have all the latest information on the latest packages.

Once in a console, you will need to keep root privileges in order to continue. If you are a computer administrator, this is as easy as using sudo.

Code Listing 1.1: Getting root privileges

$ sudo su

To make sure that you have the latest fixes and package information available, you'll now need to synchronize your portage tree with the latest from the gentoo servers.

Code Listing 1.2: Updating your portage tree

# emerge --sync


We now need to tell portage a little about your version of OSX. Portage uses the files in /etc/make.profile to determine which packages are already installed by Mac OS X, which packages are masked for your version of Mac OS X, and default configuration options. You should use one of the provided profiles, and simply provide the system with an alias from /etc make.profile to a pre-written profile. Enter the command from one of the code blocks below, choosing the one appropriate for your system.

Code Listing 1.3: Aliasing your default profile for Jaguar/Panther

# ln -s /usr/portage/profiles/default-macos-10.3 /etc/make.profile

Code Listing 1.4: Aliasing your default profile for Tiger

# ln -s /usr/portage/profiles/default-macos-10.4 /etc/make.profile

Note: Advanced users can also venture to further configure portage by specifying configuration options in /etc/make.conf. This is not recommended for the average user.

Installing System Packages 

Next, you need to 'emerge' the system. This installs other packages that portage needs to operate correctly.

Code Listing 1.5: Emerging System

# emerge system

Congratulations! Your new Gentoo for Mac OS X installation should be ready to go.

2. Installing Software Using Portage

Install Software 

To install a package in portage, all that needs to be done is to 'emerge' it. Portage will take care of all the dependencies of the package. Installing a package is easy once you know what the name of the package is.

Code Listing 2.1: Emerging Lynx

# emerge lynx

Masked Packages 

You should be able to emerge any combination of packages that have already been tested and updated to work with macos. Currently, only a very small number of packages are not masked. If an ebuild hasn't had the macos keyword added to it, you will get a message similar to the following.

Code Listing 2.2: Example of a masked package

# emerge -p cowsay

 These are the packages that I would merge, in order:
 Calculating dependencies
 !! all ebuilds that could satisfy "cowsay" have been masked.
 !! possible candidates are:
 - games-misc/cowsay-3.03 (masked by: missing keyword)

Testing Packages 

You might want to test a package yourself to see if it works, regardless of it's masked state. While we do not suggest that the average user do this, people that wish to help the developers in testing packages are free to unmask and test packages on their system. This is done by adding the 'macos' keyword to an package information file, or 'ebuild'. To add the macos keyword to an ebuild, you use the 'ekeyword' command, which is part of the the gentoolkit-dev package.

Code Listing 2.3: Installing gentoolkit-dev

# emerge gentoolkit-dev

Code Listing 2.4: Keywording a package

# cd /usr/portage/games-misc/cowsay
# ekeyword macos cowsay-3.03.ebuild

If the package successfully compiles and runs properly, please submit a bug to Gentoo Bugzilla (free membership required) notifying us that the package works (feel free to assign the bug to the Gentoo for Mac OS X developer team, [email protected]). If it doesn't work, submit a bug that shows us the error(s) you received (usually there are a great deal of errors; copy and paste from the first message that looks like an error until the end of the output).

For most packages that require X11 to run, you will need to install the X11 development package. If you did not opt to install this during the XCode install, you can install it easily afterwards from the X11SDK.pkg file, found in the Packages directory of your Xcode 1.2 CD (simply double-click to install). You should not yet try to emerge portage from the ebuilds. There is a workaround for packages that depend on portage (such as gentoolkit).

Already Installed Packages 

If you find a package that is already installed by Mac OS X, you should file a bug on Gentoo Bugzilla (free membership required). On your own system, you can add a package to /etc/portage package.provided so that portage realizes that the package is installed.

Code Listing 2.5: Adding a package to package.provided

# echo cat-name/package-x.y.z >> /etc/portage/package.provided

Note: To see a list of packages that the developers have deemed as pre-installed by Apple on your version of Mac OS X, you may consult /etc/make.profile package.provided.

Warning: Modifying /etc/make.profile/package.provided is not recommended, as it will be overwritten every time the portage tree is updated (using 'emerge --sync')

3. Using CVS

Problems with case sensitivity 

The scripts in CVS have problems with case-insensitive file systems like HFS(+), so you will need to create a case-sensitive file system image (we recommend at least 750MB in size) onto which you may check out the CVS portage tree. Either of the following commands can be used to create such a file system image:

Code Listing 3.1: Creating a case-sensitive UFS image

(Replace 'gentoo-cvs.dmg' with the desired filename,
and 'Gentoo-CVS' with the desired volume name.)
$ hdiutil create -size 750m gentoo-cvs.dmg -volname Gentoo-CVS -fs UFS

Code Listing 3.2: Creating a case-sensitive HFS+ image

Replace 'gentoo-cvs.dmg' with the desired filename,
and 'Gentoo-CVS' with the desired volume name.
$ hdiutil create -size 750m gentoo-cvs.dmg -volname Gentoo-CVS -fs HFSX

Warning: Developers: repoman will not work with spaces in the path to the portage tree root; you should not use spaces in the volume name for your CVS image.

4. Uninstallation

Uninstall Script 

To uninstall Gentoo for Mac OS X, you can use the uninstall script, which allows you to choose whether or not you would like to unmerge the packages you installed with Gentoo for MacOS.

Code Listing 4.1: Uninstalling Gentoo for Mac OS X

# sudo perl

Note: To uninstall, you should run the script with root privileges.

5. Available Packages


There are several ways to view a list of packages that have been marked with the 'macos' keyword, and are therefore marked as stable on Mac OS X. Since there is so much current development on marking packages as stable on Gentoo for Mac OS X, users are encouraged to check the list of available packages frequently.

Gentoo Fresh Mac OS X Ebuilds 

The Gentoo Linux Fresh Mac OS X Ebuilds site is part of the official Fresh Gentoo Ebuilds site. It not only lists current ebuild information, but also allows searching, and offers an even more popular feature, RSS feeds (even on a per-keyword basis). There is an RSS feed for the latest ebuilds keyworded 'macos' available on the Fresh Gentoo Ebuilds Feeds List. is an unoffical source for portage tree information, much like Fresh Gentoo Ebuilds, but offers more features on a per-ebuild information basis, such as reverse dependencies per package, etc.

6. Advanced Features, & Troubleshooting

Collision Protection 

Gentoo for MacOS features automatic collision protection that prevents portage from overwriting files that it did not previously put there itself. This can be turned off with FEATURES="-collision-protect".

Code Listing 6.1: Allowing portage to overwrite Mac OS X files

# FEATURES="-collision-protect" emerge autoconf

Warning: Disabling collision protection is very dangerous and can yield a nonworking system.

emerge: command not found 

The Gentoo for Mac OSX installer updates the /etc/profile file by adding /usr/lib/portage/bin to your PATH environment variable. In order to simply run emerge ..., you may need to type source /etc/profile or log out and log back in in order to avoid having to type the full path /usr/lib/portage/bin/<toolname>) to run Portage tools.

Errors with <library>.a 

When installing <library>.a files, ranlib is run to ensure that the library references appropriate paths. When make install is executed in an ebuild, things are actually installed to /var/tmp/portage <package>/image rather than the actual live filesystem (livefs). This means that libraries installed by the ebuild reference incorrect paths. This problem only exists on the darwin kernel with it's <library>.a files, and is being worked on by the Gentoo for Mac OS X team.

According to Gentoo for Mac OS X policy, ebuilds that install libraries must be checked to be in working order before they are keyworded as 'macos'. Most of the time, the reason that the libraries are nonworking is that the libary simply references incorrect paths. For the adventurers out there, there's a simple workaround for this. The ranlib command fixes, amongst other things, references to incorrect paths in libraries.

Code Listing 6.2: Using ranlib to fix broken libraries

(Replace '/usr/lib/libjpeg.a' with the broken library)
# ranlib /usr/lib/libjpeg.a

The portage dependency 

Some packages depend on portage being installed. There is currently a problem with portage not knowing that it is installed. While the Gentoo for OS X team works on this bug, there is a simple workaround. It is possible to attempt to emerge any package without emerging its dependencies. This can be used to get around the portage dependency, but should never be used for any other dependency.

Code Listing 6.3: Disregarding dependencies during an emerge

# emerge --nodeps gentoolkit

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.
Updated October 2, 2004
Alexander Plank
Author, Editor

Hasan Khalil
Author, Editor

Patrick Tescher

Clément Varaldi

Summary:  This guide walks the average user through the installation and usage of portage on Mac OS X.
$99/mo dedicated servers

No BS Dedicated Gentoo Linux Servers from

Tek Alchemy

Tek Alchemy offers dedicated servers and other hosting solutions running Gentoo Linux.


php|architect is the monthly magazine for PHP professionals, available worldwide in print and electronic format. A percentage of all the sales will be donated back into the Gentoo project.


Seven L Networks provides customizable Dedicated Servers for your customized Gentoo install. Colocation and other hosting services are also provided.

The Gentoo Linux Store
Copyright 2001-2004 Gentoo Foundation, Inc. Questions, Comments, Corrections? Email [email protected].