Table of Contents
- 1. Install Xcode Tools
- 2. Install XWindows (X11)
- 3. Set the shell environment
- 4. Install MacPorts
- 5. Update MacPorts via selfupdate
1. Install Xcode Tools
- Download and install the latest version of Xcode Tools for your Mac OS X version. It is best not to install an older version from the Mac OS X install disk, since it may have bugs that cause some ports to fail to install. Latest versions are 2.5 for Mac OS X 10.4, 3.1.4 for Mac OS X 10.5, 3.2.6 or 4.0.2 for Mac OS X 10.6, 4.5 for Mac OS X 10.7 and 4.5 for Mac OS X 10.8.
- Run the binary installer, or in the case of Xcode 4.3 drag the program to /Applications and then follow the migration instructions.
- Click Customize, expand the Applications category and click the checkbox beside X11 SDK to add it to the default items.
- Click Install to install Xcode Tools and the X11 SDK.
Notes: Xcode Tools is not updated via the Software Update utility on OS versions prior to 10.6.
2. Install XWindows (X11)
On Mac OS X 10.4, Apple's X11 is an optional install. If the application X11 is not present in /Applications/Utilities:
- Insert the "Mac OS X Install Disk 1" and run the package named "Optional Installs".
- At the software selection window expand the Applications categoty and click the checkbox beside X11 (and nothing else).
- Click Install to install X11.
- Drag the /Applications/Utilities/X11 icon to your dock —you must open X11 before launching an X11 application. (This is not necessary on Leopard, as X11 will be launched automatically when needed.)
- XWindows (X11) is required for many MacPorts apps and it is highly recommended that you install it even if you don't plan to run X11 apps immediately.
- The X11SDK is also required to run X11 software, but it is installed by default during the Xcode Tools install above. If you wish to check to see if X11 (X11User) and X11SDK are installed, look in /Library/Receipts for the files X11User.pkg and X11SDK.pkg.
3. Set the shell environment
Setting the Unix shell environment is critical for MacPorts to function.
Requirements for the MacPorts' shell environment
The MacPorts binary installer places a .profile file in your home directory (view files preceded by a dot with 'ls -a'). The contents of this ~/.profile file adds the MacPorts paths in front of the standard Unix paths for the default BASH shell. This is done so that if you have utilities or libraries from both MacPorts and Mac OS X's standard install, the MacPorts libraries will be run instead of the ones provided by Apple.
On Mac OS X versions 10.4 and earlier, you'll need to add this variable to your ~/.profile to run X11 applications:
Do not set DISPLAY on Mac OS X 10.5 (Leopard) or later, as it is set automatically and needs to be a different value.
So a basic ~/.profile file will look something like this:
export PATH=/opt/local/bin:/opt/local/sbin:$PATH export DISPLAY=:0.0
- To understand why MacPorts libraries are often installed when Apple has provided one, see FAQ.
- Changes to ~/.profile do not take effect on the current shell session — they take effect on new sessions so open a new shell session and type 'env' to see the path and variable changes.
- Other profile files may take precedence over ~/.profile. If you are using one of the following profile files in your home directory, you will need to merge the contents of it into ~./profile, or vice versa because the shell will ignore one of them:
Verify the shell environment
To verify that your ~/.profile has set your shell environment:
- Open a new terminal window
- Type the command: env
Check to make sure the reported path begins with the MacPorts' paths as show above.
Sample output of command env:
TERM_PROGRAM=Apple_Terminal TERM=xterm-color SHELL=/bin/bash TERM_PROGRAM_VERSION=133 USER=mduling __CF_USER_TEXT_ENCODING=0x1F6:0:0 PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
Options for the MacPorts' shell and X11 environment
To set a default editor for use with the port command (e. g. 'port ed mysql5'), add a variable EDITOR with the path of your favorite editor to the ~/.profile file.
A sample ~/.profile with optional EDITOR variable set:
export PATH=/opt/local/bin:/opt/local/sbin:$PATH export DISPLAY=:0.0 export EDITOR=/usr/bin/pico
To launch X11 apps directly from an X11 window (instead of a terminal window), you need to have the MacPorts paths imported into X11 sessions when they are opened. This is a two step process.
First, tell X11 about your .profile file by editing the file /etc/X11/xinit/xinitrc and add this line near the top.
Now finish by making any subsequent X11 sessions opened using the menubar respect your .profile.
- Open X11 and select "Customize Menu ..." from the Applications menu.
- Double-click the menu item "Terminal" and change: xterm to xterm -ls
- Click "Done" to save the change.
4. Install MacPorts
Install MacPorts using the binary installer (to /opt/local/ only)
- Download the latest MacPorts .dmg disk image.
- Run the binary installer.
- Perform the default “easy” install.
- A MacPorts' selfupdate (see below) will automatically update to the latest release if the binary .dmg image is behind the latest released tarball.
Install MacPorts from source (to any path except /usr/local/)
- Download and unzip the latest MacPorts tarball from the MacPorts download area.
- Perform these commands in a terminal window.
cd ~/MacPorts-2.0.4/ ./configure --enable-readline make sudo make install
- To see why /usr/local is not a viable install location for MacPorts, see FAQ
Install MacPorts from source as an unprivileged (non-root) user
If you don't have root on your machine, or if you just prefer to install packages without becoming root, the following steps will install MacPorts into ~/macports (tested on Leopard and Tiger).
- Download the source as bzip2 tarball from MacPorts download area
- Run the following
tar -jxf MacPorts-2.0.4.tar.bz2 && cd MacPorts-2.0.4
PATH=/usr/bin:/usr/sbin:/bin:/sbin ./configure \ --prefix=$HOME/macports \ --enable-readline \ --with-install-user=`id -un` \ --with-install-group=`id -gn` \ --x-includes=/usr/X11R6/include \ --x-libraries=/usr/X11R6/lib \ --with-tclpackage=$HOME/macports/share/macports/Tcl make make install
- Add something like the following to your Mac's ".bashrc":
export PATH=$HOME/macports/bin:$HOME/macports/sbin:$PATH export MANPATH=$HOME/macports/share/man:$MANPATH export PERL5LIB=$HOME/macports/lib/perl5/5.8.8:$HOME/macports/lib/perl5/vendor_perl/5.8.8:$PERL5LIB
Note: do not set MANPATH here unless you have already set it elsewhere (or are running Leopard, which does so). If you have not set MANPATH in another place, and are running Tiger or earlier, omit the MANPATH line. For more information about setting up the shell environment variables correctly, please see the Guide.
Most ports install just fine unless they try to add themselves to the LaunchD (e.g. most services, but you'd need root for most of them anyhow). If you do run into a required port that tries to add itself as a startup item, you can edit the Portfile (e.g. port edit <portname>) and change startupitem.create yes to startupitem.create no
Install MacPorts from a developer release
Note: Developer releases contain untested code and may have bugs. Use at your own risk.
5. Update MacPorts via selfupdate
The 'port selfupdate' command must be run after a new MacPorts install, and frequently thereafter. The command updates MacPorts with the latest port revisions, and, if necessary, updates MacPorts to the latest release.
- Open a terminal window.
- Execute the MacPorts selfupdate command.
sudo port selfupdate
or for verbose output:
sudo port -d selfupdate