New Ticket     Tickets     Wiki     Browse Source     Timeline     Roadmap     Ticket Reports     Search

Version 44 (modified by jmr@…, 4 years ago) (diff)

Xcode advice update

Table of Contents

  1. 1. Install Xcode Tools
  2. 2. Install XWindows (X11)
  3. 3. Set the shell environment
    1. Requirements for the MacPorts' shell environment
    2. Verify the shell environment
    3. Options for the MacPorts' shell and X11 environment
  4. 4. Install MacPorts
    1. Install MacPorts using the binary installer (to /opt/local/ only)
    2. Install MacPorts from source (to any path except /usr/local/)
    3. Install MacPorts from source as an unprivileged (non-root) user
    4. Install MacPorts from a developer release
  5. 5. Update MacPorts via selfupdate

1. Install Xcode Tools

  1. Download and install the latest version of Xcode Tools for your OS version. It is best not to install an older version from the OS X install disk, since it may have bugs that cause some ports to fail to install. Latest versions are 2.5 for 10.4, 3.1.4 for 10.5, and 3.2.1 for 10.6.
  2. Run the binary installer.
  3. Click Customize, expand the Applications category and click the checkbox beside X11 SDK to add it to the default items.
  4. Click Install to install Xcode Tools and the X11 SDK.

Notes: Xcode Tools is neither installed nor updated via the Software Update utility.

2. Install XWindows (X11)

On OS X 10.4, Apple's X11 is an optional install. If the application X11 is not present in /Applications/Utilities:

  1. Insert the "Mac OS X Install Disk 1" and run the package named "Optional Installs".
  2. At the software selection window expand the Applications categoty and click the checkbox beside X11 (and nothing else).
  3. Click Install to install X11.
  4. 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.
  • OS X 10.3 users can optionally get the X11 software from the Apple download site.

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 OS X's standard install, the MacPorts libraries will be run instead of the ones provided by Apple.

export PATH=/opt/local/bin:/opt/local/sbin:$PATH

On Mac OS X versions 10.4 and earlier, you'll need to add this variable to your ~/.profile to run X11 applications:

export DISPLAY=:0.0

Do not set DISPLAY on 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

Important Notes:

  • To understand why MacPorts libraries are often installed when Apple has provided one, see section "Why is MacPorts using its own libraries?" in the 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:
    • ~/.bash_login
    • ~/.bash_profile

Verify the shell environment

To verify that your ~/.profile has set your shell environment:

  1. Open a new terminal window
  2. Type the command: env

Check to make sure the reported path begins with the MacPorts' paths as show above.

Sample output of command env:


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.

export EDITOR=/usr/bin/pico

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.

source ~/.profile

Now finish by making any subsequent X11 sessions opened using the menubar respect your .profile.

  1. Open X11 and select "Customize Menu ..." from the Applications menu.
  2. Double-click the menu item "Terminal" and change: xterm to xterm -ls
  3. Click "Done" to save the change.

4. Install MacPorts

Install MacPorts using the binary installer (to /opt/local/ only)

  1. Download the latest MacPorts .dmg disk image, currently version 1.8.1.
  2. Run the binary installer.
  3. 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/)

  1. Download and unzip the latest MacPorts tarball from the MacPorts download area.
  2. Perform these commands in a terminal window.
    cd ~/MacPorts-1.8.1/
    ./configure --enable-readline
    sudo make install


  • To see why /usr/local is not a viable install location for MacPorts, see the MacPorts 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).

  tar -jxf MacPorts-1.8.1.tar.bz2 && cd MacPorts-1.8.1
  • Then:
  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 \

  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

Under construction.

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.

  1. Open a terminal window.
  2. Execute the MacPorts selfupdate command.
sudo port selfupdate

or for verbose output:

sudo port -d selfupdate