Gentoo For Mac OS X Installation and Usage Guide
In order to install Gentoo for Mac OS X, you must have the following software
- Mac OS 10.2 or later
- XCode Tools 1.2 or later
The XCode Tools can be downloaded at no cost from the
Apple Developer Connection member
site (free membership required).
We strongly recommend that XCode be installed with the X11 SDK.
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 Terminal.app
(or another terminal emulator). If you already have Terminal.app open, you'll
need to open a new shell/window for the software insalled by the installer to be
recognized by the terminal session.
Using any shell besides bash is currenly unsupported and most likely won't work.
You should change your default shell in Terminal.app by clicking on
Terminal->Preferences (in the menu bar), chosing the "Execute this command"
option, and entering /bin/bash.
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
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
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
2. Installing Software Using Portage
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
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:
!! all ebuilds that could satisfy "cowsay" have been masked.
!! possible candidates are:
- games-misc/cowsay-3.03 (masked by: missing keyword)
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
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
Modifying /etc/make.profile/package.provided is not recommended, as
it will be overwritten every time the portage tree is updated (using 'emerge
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
$ hdiutil create -size 750m gentoo-cvs.dmg -volname Gentoo-CVS -fs UFS
Code Listing 3.2: Creating a case-sensitive HFS+ image
$ hdiutil create -size 750m gentoo-cvs.dmg -volname Gentoo-CVS -fs HFSX
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.
To uninstall Gentoo for Mac OS X, you can use the
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 uninstall.pl
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.
Gentoo-Portage.com 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
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
Disabling collision protection is very dangerous and can yield a
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
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
# 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
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.