1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. Upgrade MacPorts
2.4. Uninstall MacPorts
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
5.10. PortGroup Introduction
5.11. PortGroup github
5.12. PortGroup gnustep
5.13. PortGroup golang
5.14. PortGroup haskell
5.15. PortGroup java
5.16. PortGroup perl5
5.17. PortGroup python
5.18. PortGroup ruby
5.19. PortGroup xcode
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
6.6. Tests
7. MacPorts Project
7.1. Using Trac for Tickets
7.2. Using Git and GitHub
7.3. Contributing to MacPorts
7.4. Port Update Policies
7.5. Updating Documentation
7.6. MacPorts Membership
7.7. The PortMgr Team
8. MacPorts Guide Glossary
Glossary

Chapter 5. Portfile Reference

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

5.1. Global Keywords

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. Remember that once set, it can never be removed because it takes precedence over version and revision.
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' GitHub usernames or email addresses. GitHub usernames start with an @ symbol. Email addresses are preferably listed in the obfuscated form below to hide them from spambots:

  • For addresses in domain @macports.org, simply omit the domain name.
  • For addresses in other domains, e.g., account@example.org, use the convention example.org:account to specify the address.

In the example below, the port is maintained by a GitHub user named neverpanic, and the owners of the two email addresses jdoe@macports.org and julesverne@example.org

maintainers         @neverpanic \
                    jdoe \
                    example.org:julesverne

+ Braces can be used to express that these refer to the same person, for example the GitHub username and an email. In the following example, the port is maintained by a GitHub user named jverne, that can also be contacted directly at julesverne@example.org.

+

maintainers         {@jverne 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            https://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 macOS 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}
license_noconflict
By default, it is assumed that ports may use libraries or headers from their dependencies and thus form a derivative work. A dependency with an incompatible license thus prevents the port from being distributed in binary form. If a dependency with an incompatible license is not used in such a way that a derivative work is formed, or should not prevent binary distribution for any other reason, add its name to this list.
license_noconflict openssl

+

license_noconflict readline gdbm
use_xcode
Available in 2.6.0 and later. By default, it is assumed on macOS that ports will not need tools from Xcode.app unless (1) Command Line Tools aren’t installed, (2) you are on an old version of Mac OS X that does not support the xcode-select mechanism, or (3) the port uses build.type xcode or includes the xcode PortGroup. If a port needs to use Xcode (i.e., xcodebuild) in any way, use_xcode yes should be set or the port should include the xcode PortGroup. The environment variable DEVELOPER_DIR is now exported during all build phases, set to the value of ${configure.developer_dir} which may be the directory of Xcode or CLT depending on use_xcode. This means that libxcselect shims (i.e., /usr/bin/clang) will resolve to Xcode/CLT. Build systems that ignore the environment may accidentally use Xcode which will cause a failure in trace mode.
use_xcode no

+

use_xcode yes