MacPorts Guide

To launch X11 applications 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 the ~/.profile file that will be created after you install MacPorts. Do this by editing the file /etc/X11/xinit/xinitrc and adding this line near the top.

source ~/.profile

Now finish the process by making subsequent X11 sessions opened using the menu bar respect your .profile file.

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.

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

%% 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 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.

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

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.

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.

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

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

The selfupdate option should be used regularly to sync the local ports tree with the global MacPorts ports repository so you will have the latest port versions. It also checks for new revisions of the MacPorts infrastructure, called MacPorts base, and upgrades it when necessary.

%% sudo port selfupdate

Use the debug flag for verbose output.

%% sudo port -d selfupdate

DEBUG: Rebuilding the MacPorts base system if needed.
DEBUG: Synchronizing ports tree(s)
Synchronizing from rsync://rsync.macports.org/release/ports/
DEBUG: /usr/bin/rsync -rtzv --delete-after rsync://rsync.macports.org/release/ports/
receiving file list ... done

[ ... trimmed ... ]


The MacPorts installation is not outdated and so was not updated
DEBUG: Setting ownership to root
selfupdate done!

If selfupdate detects that a newer version of MacPorts base is available, it automatically updates the installed copy of MacPorts base to the latest released version. In that case, you will see the upgrade Makefile execute, and when it finishes you will see this message:

DEBUG: Updating using rsync
receiving file list ... done

Congratulations, you have successfully installed the MacPorts system.

The sync option performs a subset of selfupdate actions. It synchronizes the ports tree, as does selfupdate, but it does not check for upgrades to MacPorts base. On Mac OS X, unless there is a special reason not to do so, you should run selfupdate.

The list option is used to get a list of all available ports. The list of available ports is very long, so use search if you know a port's name or part of it.

%% port list

The search option is very useful to find port names by partial matches.

%% port search rrd

rrdtool          net/rrdtool       1.2.23    Round Robin Database
php5-rrdtool     www/php5-rrdtool  1.0       PHP 5 glue for RRDtool

The info option is used to get information about a port: description, maintainer, etc.

%% port info flowd

flowd 0.9, net/flowd (Variants: universal, darwin_8)
http://www.mindrot.org/flowd.html

flowd is a small, fast and secure NetFlow collector.

Platforms: darwin
Maintainers: nomaintainer@macports.org

The deps option shows you the dependencies of a port; dependencies are explicitly declared in Portfiles.

%% port deps apache2

apache2 has library dependencies on:
        apr
        apr-util
        expat
        openssl
        pcre

The variants option allows you to check what variations of a port are available before you install it. Variants are a way for port authors to provide options that may be invoked at install time. See Invoking Port Variants below to install ports that have variants.

%% port variants nmap

nmap has the variants:
        universal
        gtk2
        no_ssl
        no_pcre

The option install is used to install a port. See Invoking Port Variants below to install ports that have variants.

%% sudo port install nmap

The option clean deletes all intermediate files that MacPorts creates while building a port. A port clean is also often necessary to remove corrupted tarballs after a failed fetch phase.

%% port clean --all vile

The uninstall option will uninstall an installed port.

%% port uninstall vile

%% port -f uninstall vile

The contents option displays the files that have been installed by a given port. Uninstalled ports will always show no contents.

%% port contents render

Port render contains:
  /opt/local/include/X11/extensions/render.h
  /opt/local/include/X11/extensions/renderproto.h
  /opt/local/lib/pkgconfig/render.pc
  /opt/local/share/doc/render/library
  /opt/local/share/doc/render/protocol

The installed option displays all installed ports.

%% port installed

The following ports are currently installed:
  aalib @1.4rc5_2 (active)
  apr @1.2.8_0 (active)
  apr-util @1.2.8_2 (active)
  atk @1.18.0_0 (active)

[ ... trimmed ...]

  wxWidgets @2.8.4_2+darwin_8 (active)
  Xft2 @2.1.7_0 (active)
  xrender @0.9.0_0+darwin_8 (active)
  zlib @1.2.3_1 (active)

The outdated option checks your installed ports against the MacPorts repository to see if updated Portfiles have been released since your ports were installed.

%% port outdated

apr                            1.2.8_0 < 1.2.9_0
autoconf                       2.61_0 < 2.61_1
gimp                           2.2.14_0 < 2.2.16_0
libtool                        1.5.22_0 < 1.5.24_0
pkgconfig                      0.21_0 < 0.22_0

The upgrade option upgrades installed ports and their dependencies when a Portfile in the repository has been updated after a port was installed.

%% port upgrade gnome

If you wish not to upgrade a port's dependencies, use the -n switch.

%% port -n upgrade gnome

If you'd like to upgrade all outdated ports, use this command.

%% port upgrade outdated

%% port -u upgrade vile

The dependents option reports what ports depend upon a given port, if any. MacPorts learns about dependents during port installation, so uninstalled ports will always report that there are no dependents.

%% port dependents openssl

neon depends on openssl
gnome-vfs depends on openssl
libdap depends on openssl

The livecheck option checks to see if the application corresponding to a given port has been updated at the developer's download site. It's especially useful for port maintainers, but others may also wish to see if a port has the latest available distribution source. See section Livecheck for more information.

%% port livecheck rrdtool

rrdtool seems to have been updated (port version: 1.2.23, new version: 1.3beta1)

The lint option checks if the Portfile conforms to the MacPorts standards specified in Portfile Development.

If a Portfile validates fine the following message is shown.

%% port lint chemtool

--->  Verifying Portfile for chemtool
--->  0 errors and 0 warnings found.

Otherwise the warnings and errors are listed.

%% port lint KeyArcher

--->  Verifying Portfile for KeyArcher
Warning: Line 2 should be a newline (after RCS tag)
Warning: Line 5 has trailing whitespace before newline
Error: Missing required variable: platforms
--->  1 errors and 2 warnings found.

A variant can only be invoked when a port is installed. After you have determined what variants a given port has, if any, you may install a port using the variant as shown.

%% port install fetchmail +ssl

Port variant execution may be verified using the port command with the verbose switch.

%% port -v install fetchmail +ssl

When a port is installed using a valid variant and specified correctly, the verbose output will contain:

DEBUG: Executing variant ssl provides ssl

For an explanation of default variants see Port Variants. Default variants are optional, and not all ports using variants have them. For ports with default variants, you may install a port without them by negating default variants using "-" as shown.

%% port install fetchmail -ssl

To verify that you have properly negated a default variant, you may want to use verbose mode. But negated variants are simply not reported in any way by the port command, as if they did not exist. You will know you have successfully negated the default variant in the example above if you do not see this line in the verbose output.

DEBUG: Executing variant ssl provides ssl

Binary archives can only be used on a target system running MacPorts. Binary archives allow MacPorts utilities to begin installation after the destroot phase and install and activate a port on the target system. Binary archives are created using the port command as shown.

%% port -d archive logrotate

Debug output is shown below.

--->  Creating logrotate-3.7_0.i386.tgz

[ ... trimmed ... ]

DEBUG:
./
./+COMMENT
./+CONTENTS
./+DESC
./+PORTFILE
./+STATE
./opt/
./opt/local/
./opt/local/etc/
./opt/local/etc/logrotate.conf
./opt/local/man/
./opt/local/man/man8/
./opt/local/man/man8/logrotate.8
./opt/local/sbin/
./opt/local/sbin/logrotate
--->  Archive logrotate-3.7_0.i386.tgz packaged
DEBUG: Executing archive_finish
--->  Archive for logrotate 3.7_0 packaged

Binary archive files are placed in ${prefix}/var/macports/packages/. The archive file type is set in the macports.conf file. The default format is .tgz; other options are: tar, tbz, tbz2, tlz, xar, zip, cpgz, cpio.

Binary packages are standalone binary installers that are precompiled; they do not require MacPorts on the target system. Binary files created with MacPorts may be either .pkg (Mac OS X Installer Packages), or RPM (RPM Package Manager) format. MacPorts may also process a .pkg package into a Mac OS X .dmg disk image file. You may create binary packages with the port command as shown in these examples.

%% port pkg pstree

You may create a Mac OS X .dmg disk image file as shown.

%% port dmg pstree

You may compile a port into an RPM file as shown, in order to install it onto a target that has RPM utilities or a full package management system that can install RPMs.

%% port rpm pstree

All packages are placed in a port's work directory.

Source packages are bundles consisting of a Portfile, patches if needed, and any other files required to install the port. Port source packages are mainly used by developers of package management and port submission frameworks. Port source packages may be in either .portpkg (XAR) or .nosrc.rpm (SRPM) format.

# $Id$

PortSystem          1.0

name                rrdtool
version             1.2.23
categories          net
maintainers         julesverne
description         Round Robin Database
long_description    RRDtool is a system to store and display time-series data
homepage            http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/
platforms           darwin
master_sites        http://oss.oetiker.ch/rrdtool/pub/ \
                    ftp://ftp.pucpr.br/rrdtool/

checksums           md5 dafa161bc9c61e57636a6085c87c1fe8 \
                    sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
                    rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23

depends_lib         port:perl5.8 \
                    port:tcl \
                    port:zlib

configure.args      --enable-perl-site-install \
                    --mandir=${prefix}/share/man

To augment a port's installation phase, and not override it, you may use pre- and post- installation phases as shown in this example.

post-destroot {
    # Install example files not installed by the Makefile
    file mkdir ${destroot}${prefix}/share/doc/${name}/examples
    file copy ${worksrcpath}/examples/ \
        ${destroot}${prefix}/share/doc/${name}/examples
}

To override the automatic MacPorts installation phase processing, define your own installation phases as shown in this example.

destroot {
    xinstall -m 755 -d ${destroot}${prefix}/bin
    xinstall -m 755 ${worksrcpath}/cdpr ${destroot}${prefix}/bin
}

To eliminate a default phase, simply define a phase with no contents as shown.

build {}

Startupitems may be placed in the global section of a Portfile.

startupitem.create      yes
startupitem.name        nmicmpd
startupitem.executable  "${prefix}/bin/nmicmpd"

Startupitems keywords may also be used within a variant definition to make their installation conditional.

variant server {
    startupitem.create  yes
    startupitem.start   "${prefix}/share/${name}/vm-pop3d.init start"
    startupitem.stop    "${prefix}/share/${name}/vm-pop3d.init stop"
}

The most common actions for user-selected variants is to add or remove dependencies, configure arguments, and build arguments according to various options a port author wishes to provide. Here is an example of several variants that modify depends_lib and configure arguments for a port.

variant fastcgi description {Add fastcgi binary} {
    configure.args-append \
            --enable-fastcgi \
            --enable-force-cgi-redirect \
            --enable-memory-limit
}

variant gmp description {Add GNU MP functions} {
    depends_lib-append port:gmp
    configure.args-append --with-gmp=${prefix}

}

variant sqlite description {Build sqlite support} {
    depends_lib-append \
        port:sqlite3
    configure.args-delete \
        --without-sqlite \
        --without-pdo-sqlite
    configure.args-append \
        --with-sqlite \
        --with-pdo-sqlite=${prefix} \
        --enable-sqlite-utf8
}

In the example variant declaration below, the configure argument --without-x is removed and a number of others are appended.

variant x11 description {Builds port as an X11 program with Lucid widgets} {
    configure.args-delete   --without-x
    configure.args-append   --with-x-toolkit=lucid \
                            --without-carbon \
                            --with-xpm \
                            --with-jpeg \
                            --with-tiff \
                            --with-gif \
                            --with-png
    depends_lib-append      lib:libX11:XFree86 \
                            lib:libXpm:XFree86 \
                            port:jpeg \
                            port:tiff \
                            port:libungif \
                            port:libpng
}

If a variant requires options in addition to those provided by keywords using -append and/or -delete, in other words, any actions that would normally take place within a port installation phase, do not try to do this within the variant declaration. Rather, modify the behavior of any affected phases when the variant is invoked using the variant_isset keyword.

post-destroot {
    xinstall -m 755 -d ${destroot}${prefix}/etc/
    xinstall ${worksrcpath}/examples/foo.conf \
        ${destroot}${prefix}/etc/

    if {[variant_isset carbon]} {
        delete ${destroot}${prefix}/bin/emacs
        delete ${destroot}${prefix}/bin/emacs-${version}
    }
}

Variants are used to specify actions that lie outside the core functions of an application or port, but there may be some cases where you wish to specify these non-core functions by default. For this purpose you may use the keyword default_variants.

default_variants    +foo +bar

If you wish to contribute modifications or fixes to a Portfile, you should do so in the form of a patch. Follow the steps below to create Portfile patch files

Now you may attach the patch file to a MacPorts Trac ticket for the port author to evaluate.

Necessary or useful patches to application source code should generally be sent to the application developer rather than the port author so the modifications may be included in the next version of the application.

You should create one patch file for each file to be patched, though it is permissible to use existing patches you find that patch multiple files. Patchfile filenames should uniquely distinguish the file and generally be of the form patch-<directory>-<filename>.diff, as shown in this example: patch-src-Makefile.in.diff. Patch files should apply with "patch -p0'' from the working source directory of the port.

Though MacPorts applies patch files automatically, you may want to know how to apply patch files manually if you want to test patch files you have created or you wish to apply uncommitted Portfile patches.

Portfiles may be thought of as a table of keys and values in two columns separated by spaces (not tabs), so you should set your editor to use soft tabs, which are tabs emulated by spaces. By default, the top line of all Portfiles should use a modeline that defines soft tabs for the vim and emacs editors as shown.

# -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:ft=tcl:et:sw=4:ts=4:sts=4

The left column should consist of single words, and will be separated from the more complex right side by spaces in multiples of four. Variable assignments and variant declarations are exceptions, and may be considered a single word on the left side, with a single space between words.

set libver "8.5"


variant mysql5 { ... }

Frequently multiple items are necessary in the second column. For example, to set multiple source download locations, multiple "master_sites" must be defined. Unless the second column items are few and short you should place each additional item on a new line and separate lines with a backslash. Indent the lines after the first line to make it clear the items are second column values and also to emphasize the unity of the block.

destroot.keepdirs    ${destroot}${prefix}/var/run \
                     ${destroot}${prefix}/var/log \
                     ${destroot}${prefix}/var/cache/mrtg

TODO:

TODO:

TODO:

TODO: Set variables so changing paths may be done in one place; use them anytime it makes updates simpler: distname ${name}-src-${version}

The MacPorts port installation process has a number of distinct phases that are described in detail in this section. The default scripts coded into MacPorts base performs the standard configure, make, and make install steps. For applications that do not conform to this standard, installation phases may be declared in a Portfile to augment or override the default behavior as described in the Portfile Development chapter.

MacPorts keywords are used to specify required or optional items within a Portfile, or to override default options used by MacPorts base for individual ports. Keywords are to be used within the "global" and "variant" sections of Portfiles, and not within optional port phase declarations.

In other words, port phase keywords are not located within port phase declarations, but rather they refer to port phases and set options for those phases, and they take affect whether or not phase declarations have been explicitly defined in a Portfile.

The list of keywords related to the fetch phase.

The list of keywords related to the checksum phase.

The list of keywords related to the extract phase.

The list of keywords related to the patch phase.

The list of keywords related to the configure phase.

MacPorts base sets some important default configure options, so should use the -append version of most configure keywords so you don't overwrite them. For example, MacPorts base sets default configure.cflags so you should always use configure.cflags-append to set additional CFLAGS in Portfiles.