# Installing MacPorts

This chapter shows you how to install MacPorts and its prerequisites step-by-step. Note that section 1 and section 2 (installing X11 and Xcode Tools) are Mac OS X specific. If you wish to install MacPorts on another platform, first make sure you have X11 and gcc installed, and then begin at section 3.2 by performing MacPorts install from source and proceed to the end of the chapter.

## Install X11

It is recommended that you install the X Window System (X11) even if you don't plan to run X11 applications immediately. Apple's X11 is preferred over either of the X11 ports, XFree86 and Xorg, therefore Apple's X11 is normally used to satisfy ports that depend upon X11 (see non-port dependencies). If Apple's X11 wasn't installed when Mac OS X was installed, follow these steps.

1. Insert the Mac OS X Install Disk and run the package named Optional Installs.

2. At the software selection window expand the Applications category and click the check box beside X11 (and nothing else).

3. Click Install to install X11.

Before launching an X11 application, you must open a terminal window and start an xterm session.

    %% xterm

After the X11 session window opens, you may launch X11 apps from another terminal window. See Optional X11 Settings if you wish to launch X11 applications from an X11 session window.

X11 and the X11SDK (from Xcode Tools) are both required for X11 apps. To verify the presence of both, check for files `com.apple.pkg.X11User.bom` & `com.apple.pkg.X11SDKLeo.bom` in `/Library/Receipts/boms/`. On Mac OS X 10.4, look for files `X11User.pkg` & `X11SDK.pkg` in `/Library/Receipts/`.

### Optional X11 Settings

To launch X11 applications directly from an X11 window (instead of a regular terminal window), you need to make it so X11 sessions opened using the menu bar respect your `.~profile` file.

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.

## Install Xcode Tools

To install Xcode Tools and the X11 SDK, follow these steps.

1. Always make sure to install the latest version of Xcode Tools for your Mac OS X release. Apple's Developer Connection site has a link for the latest version of Xcode Tools for the currently shipping release of Mac OS X, because earlier versions of Xcode Tools may cause port install failures. To download the latest Xcode Tools version for Mac OS X 10.4 (2.5) or 10.3 (1.5), see the Developer Connection links here and here respectively.

2. Run the Xcode Tools package installer.

3. Click the button Customize, expand the Applications category and click the check box beside X11 SDK to add it to the default items.

4. Click Install to install Xcode Tools and the X11 SDK.

Xcode Tools are not updated via Mac OS X's Software Update utility.

## Install MacPorts

If you are using Mac OS X, you should install MacPorts using the Mac OS X package installer unless you do not wish to install it to `/opt/local/`, the default MacPorts location, or if you wish to install a pre-release version of MacPorts base. However, if you wish to install multiple copies of MacPorts or install MacPorts on another OS platform, you must install MacPorts from the source code.

Though a distinction is made between pre-release and release versions of MacPorts base, the ports collection supports no such distinction or versioning. The selfupdate command installs the latest port revisions from subversion (at a slight delay), and updates MacPorts base to the latest released version.

### Mac OS X Package Install

The Mac OS X package installer automatically installs MacPorts, sets the shell environment, and runs a selfupdate operation to update the ports tree and MacPorts base with the latest release.

1. Download the latest `MacPorts-1.x.x.dmg` disk image from the MacPorts download directory.

2. Double-click the `MacPorts-1.x.x.pkg` package installer on the disk image.

3. Perform the default easy install.

### Source Install

If you installed MacPorts using the package installer, skip this section. To install MacPorts from the source code, follow the steps below.

1. Download and unzip the latest MacPorts tarball from the MacPorts download directory.

2. Perform the commands shown in a terminal window. If you wish to use a path other than `/opt/local`, use the option `--prefix` and substitute a path for NEW_PREFIX.

       %% cd ~/MacPorts-1.x.x/
       %% ./configure --prefix=NEW_PREFIX  (setting prefix is optional)
       %% make
       %% sudo make install

#### Install Multiple MacPorts Copies

Occasionally a MacPorts developer may wish to install more than one MacPorts instance on the same host. Only one copy of MacPorts may use the default Tcl library path `/Library/Tcl/`, so for additional installations use the option `--with-tclpackage` as shown below and substitute NEW_TCL_PACKAGE with any empty directory, for example `/Library/Tcl/macports-new/`.

The first command temporarily removes the standard MacPorts binary paths because they must not be present while installing a second instance.

    %% export PATH=/bin:/sbin:/usr/bin:/usr/sbin
    %% cd ~/MacPorts-1.x.x/
    %% ./configure --prefix=NEW_PREFIX --with-tclpackage=NEW_TCLPACKAGE
    %% make
    %% sudo make install

### MacPorts Upgrade

MacPorts base upgrades are performed automatically (when a newer release is available) during a selfupdate operation. To upgrade a copy of MacPorts that was installed from source to the newer release of the source code, simply repeat the source install with the newer version of the MacPorts source code.

### Uninstall

To uninstall MacPorts from the default location `/opt/local/`, perform this command from a terminal window.

    %% sudo rm -rf \
        /opt/local \
        /etc/manpaths.d/macports \
        /etc/paths.d/macports \
        /Applications/DarwinPorts \
        /Applications/MacPorts \
        /Library/LaunchDaemons/org.macports.* \
        /Library/Receipts/DarwinPorts*.pkg \
        /Library/Receipts/MacPorts*.pkg \
        /Library/StartupItems/DarwinPortsStartup \
        /Library/Tcl/darwinports1.0 \
        /Library/Tcl/macports1.0

## MacPorts and the Shell

MacPorts requires that some environmental variables be set in the shell. When MacPorts is installed using the Mac OS X package installer, a postflight script is run after installation that automatically copies a `.profile` containing variables according to the rules described in the following section. Those installing MacPorts from source code must modify their environment manually using the rules as a guide.

If you have either a `.bash_login` or a `.bash_profile` file in your home directory, they may take precedence over `.profile`. You may either remove the previously used file, or add the contents of `.profile` to it.

### The Postflight Script

The postflight script automatically copies a `.profile` containing the `PATH` variable, and optionally the `MANPATH` and `DISPLAY` variables according to the rules described below. If a current `.profile` file exists at installation time it is renamed to mpsaved_$timestamp. Those installing MacPorts from source code must modify their environment manually using the rules as a guide.

- Required: `PATH` variable

  This variable is set by the postflight script to append the MacPorts executable paths to the default path as shown. The MacPorts paths are appended at the front of `PATH` so the MacPorts libraries will take precedence over vendor-supplied libraries for ported software at runtime.

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

  The user environment's $PATH is not in effect while ports are being installed, because the $PATH is scrubbed before ports are installed, and restored afterwards. To change the search path for locating system executables (rsync, tar, etc.) during port installation, see the macports.conf file variable `binpath`. But changing this variable is for advanced users only, and is not generally needed or recomended.

- Optional: `MANPATH` variable

  Condition: If prior to MacPorts installation a `MANPATH` variable exists in a current `.profile` that contains neither the value `${prefix}/share/man,` nor any empty values, the postflight script sets the `MANPATH` variable as shown below. Otherwise, the `MANPATH` variable is omitted.

      export MANPATH=/opt/local/share/man:$MANPATH

  Here are some examples of paths that contain empty values:

  - /usr/share/man:
  - :/usr/share/man
  - /usr/share/man::/usr/X11R6/man

- Optional: `DISPLAY` variable

  Condition: If installing on a Mac OS X version earlier than 10.5 (Leopard), and if a`.profile` file exists at time of MacPorts installation without a `DISPLAY` variable, the postflight script sets a `DISPLAY` variable as shown below. The `DISPLAY` variable is always omitted on Mac OS X 10.5 or higher.

      export DISPLAY=:0.0

### Verify the .profile

To verify that the `.profile` containing the MacPorts variables is in effect, type `env` in the terminal to verify the current environment settings after the `.profile` has been created. Example output for the `env` command is shown below.

Changes to `~/.profile` do not take effect until a new terminal session is opened.

    MANPATH=
    TERM_PROGRAM=Apple_Terminal
    TERM=xterm-color
    SHELL=/bin/bash
    TERM_PROGRAM_VERSION=237
    USER=joebob
    __CF_USER_TEXT_ENCODING=0x1FC:0:0
    PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
    PWD=/Users/joebob
    EDITOR=/usr/bin/pico
    SHLVL=1
    HOME=/Users/joebob
    LOGNAME=joebob
    DISPLAY=:0.0
    SECURITYSESSIONID=b0cea0
    _=/usr/bin/env

### Optional EDITOR Variable

A useful environment variable to set in `.profile` is the `EDITOR` variable. Setting this variable allows you to use the edit option to the port command to edit Portfiles quickly and easily. Set the `EDITOR` variable to point to your favorite text editor.

For example, to use the nano editor, add this line to your `~/.profile`:

    export EDITOR=/usr/bin/nano

To use the user-friendly GUI editor TextWrangler (installation required), add this line to your `~/.profile`:

    export EDITOR=/usr/bin/edit