1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. MacPorts Upgrade
2.4. Uninstall
2.5. MacPorts and the Shell
3. Using MacPorts
3.1. The port Command
3.2. Port Variants
3.3. Common Tasks
3.4. Port Binaries
4. Portfile Development
4.1. Portfile Introduction
4.2. Creating a Portfile
4.3. Example Portfiles
4.4. Port Variants
4.5. Patch Files
4.6. Local Portfile Repositories
4.7. Portfile Best Practices
4.8. MacPorts' buildbot
5. Portfile Reference
5.1. Global Keywords
5.2. Global Variables
5.3. Port Phases
5.4. Dependencies
5.5. Variants
5.6. Tcl Extensions & Useful Tcl Commands
5.7. StartupItems
5.8. Livecheck / Distcheck
5.9. PortGroups
6. MacPorts Internals
6.1. File Hierarchy
6.2. Configuration Files
6.3. Port Images
6.4. APIs and Libs
6.5. The MacPorts Registry
7. MacPorts Project
7.1. Using Trac for Tickets
7.2. Contributing to MacPorts
7.3. Port Update Policies
7.4. Updating Documentation
7.5. MacPorts Membership
7.6. The PortMgr Team
8. MacPorts Guide Terms
Glossary

This chapter serves as a reference for the major elements of a Portfile: port phases, dependencies, StartupItems, variables, keywords, and Tcl extensions.

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.

The global keywords listed below specify information for ports as a whole, whereas the keywords listed under a port phase specify information to be used during a particular installation phase.

PortSystem

The first non-comment line of every Portfile; it should be followed by PortGroup inclusions (if any) and then a blank line. It defines which version of the Portfile interpreter will be used. (There is currently only one version.)

PortSystem          1.0

name

The name of the port. To avoid special interpretation by shells and the like, names should contain only alphanumeric characters, underscores, dashes or dots. For projects whose proper names contain + characters, change these to x (e.g., libstdc++ becomes libstdcxx).

name                foo
version

The version of the ported software.

version             1.23.45
revision

Optional keyword (default is 0) that is used to track port revisions. It should not be incremented for port revisions unless it would benefit users to upgrade an installed port, and cleared when the port is updated to a newer version.

It should be used if a bug in the Portfile was found and all installations of this port have to be updated. If the change only affects new installations, there is no need to increase it.

revision            1
epoch

An optional keyword (default value is 0) that must be used when a port is updated to a version that is numerically less than the previous version, for example 1.10 -> 1.2 or 20070928 -> 1.0. Some Portfile authors have used large epoch values that look like a date, but there is no reason to do so. The epoch is simply an unsigned integer, and the only requirement is that it never be decreased.

epoch               1

Note

An epoch is not needed for most ports. If a port's version numbers advance in normal dotted-decimal sequence, there is no reason to add an epoch.

categories

The category under which the ported software falls. The first category should be the same as the directory within which the Portfile is stored; secondary and tertiary categories may be selected.

categories          net security
maintainers

A port's maintainers are the people who have agreed to take responsibility for keeping the port up-to-date. Most ports have only a single maintainer, but some ports have two or more co-maintainers. The maintainers keyword lists the maintainers' email addresses, preferably in the obfuscated form which hides them from spambots:

  • For addresses in domain @macports.org, simply omit the domain name.

  • For addresses in other domains, e.g., , use the convention example.org:account to specify the address.

In the example below, the maintainer email addresses and are hidden using these conventions.

maintainers         jdoe \
                    example.org:julesverne

Note

The address nomaintainer designates a port that is not maintained by anybody and may be modified by any committer. Feel free to claim maintainership of a nomaintainer port if desired. The address openmaintainer designates a port that has a maintainer who allows minor changes to be committed without his or her prior approval. Port maintainers who are not committers are encouraged to add openmaintainer to their ports.

description

A one-sentence description of the ported software.

description         A classic shooter arcade game.
long_description

A long description of the ported software. Break long lines with escaped newlines.

long_description    A classic shooter arcade game derived from \
                    the game alien-munchers.  Not suitable for \
                    children under two years old.
homepage

Port application's homepage.

homepage            http://www.example.org/apps
platforms

A list of the platforms on which the port has been tested. Required, but not interpreted in any way by the software at this time; it is purely informational for users. Possible values: darwin (= macosx or puredarwin), macosx, puredarwin, freebsd, linux, sunos, netbsd. In general, it can just be set to darwin. (puredarwin is an OS based on Apple's open-source Darwin releases without any of Apple's proprietary bits.) See also os.platform.

platforms           darwin
supported_archs

The CPU architectures for which this port can be built. Archs currently supported by OS X are: i386, ppc, ppc64, x86_64. If this option is not set, it is assumed that the port can build for all archs. If a port does not install any architecture-specific files, use the special value noarch.

If the building architecture isn't among supported_archs, port fails with an error message, except when building on x86_64 and supported_archs contains i386 or when building on ppc64 and supported_archs contains ppc, in which case the port will be built in 32-bit mode.

supported_archs           i386 ppc
supported_archs           noarch
license

The proper format for license consists of the license name, followed by a hyphen and number if indicating a specific version. A space should be placed between licenses if there is more than one that applies. If an element in the license list is itself a list, it is interpreted as offering a choice of any one of the licenses in the sub-list.

If the version number is a .0 version, the .0 should be omitted to make the version an integer. If the author gives the choice of using a given license or any later version of it, append a plus sign (+) to the version number. If the version specified in this case is also the earliest version, just leave out the version number entirely since it implies all versions.

license           GPL-3
license           {freetype GPL}