(Optional) Download the latest version of Xcode from the Apple developer website or get it using the Mac App Store.

A few ports require a full Xcode installation to use, but most don’t (read the description of the use_xcode keyword for specifics). If you are OK with being unable to use these ports, you do not need to install Xcode.

Next, open a terminal, run xcode-select --install, and click the Install button to install the required command line developer tools. Don't worry if you see a message telling you the software cannot be installed because it is not currently available from the Software Update Server. This usually means you already have the latest version installed. You can also get the command line tools from the Apple developer website.

Download the latest version of Xcode from the Apple developer website or get it using the Mac App Store.

If you are using Mac OS X 10.6, there are two branches of Xcode which could be considered to be the latest, 3.2.x and 4.x. Xcode 4 costs money, but Xcode 3 is still available free of charge. There are two options for downloading it:

Both are available from the Apple developer website. You may also be able to install Xcode 3.2 from your Mac OS X 10.6 DVD and then run Software Update to get the latest version.

Ensure that those of the following options that are available in the installer for your version of Xcode are selected:

If you have an earlier release of Mac OS X, you may download the latest version of Xcode for Mac OS X 10.5 (Xcode 3.0 and Xcode 3.1 Developer Tools) or 10.4 (Xcode 2.4.1 and Xcode 2.5 Developer Tools) from the Apple developer website.

Ensure that those of the following options that are available in the installer for your version of Xcode are selected:

The macOS 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.

If you installed MacPorts using the package installer, skip this section.

There are times when some may want to run MacPorts from a version newer than the current stable release. Maybe there's a new feature that you'd like to use, or it fixes an issue you've encountered, or you just like to be on the cutting edge. These steps explain how to setup MacPorts for developers, using only Git to keep MacPorts up to date.

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 ports tree, and updates MacPorts base to the latest released version.

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 prefix /opt/local, so for additional installations use the option --prefix as shown below. It's also recommended to change the applications dir using --with-applications-dir to avoid conflicts in /Applications/MacPorts. Use --without-startupitems to automatically set startupitem_install no in the new macports.conf, which is required to avoid conflicts in /Library/LaunchAgents or /Library/LaunchDaemons.

$ export PATH=/bin:/sbin:/usr/bin:/usr/sbin
$ MP_PREFIX=/opt/macports-test
$ ./configure --prefix=$MP_PREFIX --with-applications-dir=$MP_PREFIX/Applications --without-startupitems
$ make
$ sudo make install

If you want to uninstall MacPorts and the port command is functioning, first uninstall all the installed ports by running this command in the Terminal:

$ sudo port -fp uninstall installed

All that will be left in your installation prefix now will be files that were not registered to any port. This includes configuration files, databases, any files which MacPorts renamed in order to allow a forced installation or upgrade, and the base MacPorts software itself. You may wish to save your configuration files (most are in $prefix/etc), databases, or any other unique data by moving it aside.

If the port command is not functioning, you can proceed on to the next steps, but if you had installed any ports that install files to nonstandard locations, those files might not be removed.

When MacPorts is installed, a macports macOS user and group are created for privilege separation. If you want to remove them, you can use these commands from an account that has admin privileges:

$ sudo dscl . -delete /Users/macports
$ sudo dscl . -delete /Groups/macports

If you configured MacPorts to use a different user or group name, then specify that instead of macports.

Individual ports may create users and groups as well; you can remove them with the same commands, but replacing macports with the user or group name you wish to delete.

If you want to remove all remaining traces of MacPorts, run the following command in the Terminal. If you have changed prefix, applications_dir or frameworks_dir from their default values, then replace /opt/local with your prefix, replace /Applications/MacPorts with your applications_dir, and/or add your frameworks_dir to the list, respectively.

If you are running macOS 10.15 Catalina or later and have not disabled System Integrity Protection (SIP), you will need to remove the macports user first.

$ sudo rm -rf \
    /opt/local \
    /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

If you use a shell other than bash (perhaps tcsh), you may need to adjust the above to fit your shell's syntax.

Depending on which version of MacPorts you have and which ports you have installed, not all of the above paths will exist on your system; this is OK.

The postflight script automatically sets the PATH variable, and optionally the MANPATH and DISPLAY variables according to the rules described below. If a current shell configuration 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 file containing the MacPorts variables is in effect, type env in the terminal to verify the current environment settings after the file has been created. Example output for env 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

You can set an environment variable in order to use your favorite text editor with the port edit command.

MacPorts will check MP_EDITOR, VISUAL and EDITOR in this order, allowing you to either use a default editor shared with other programs (VISUAL and EDITOR) or a MacPorts-specific one (MP_EDITOR).

For example, to use the nano editor, add this line to your bash config:

export EDITOR=/usr/bin/nano

To use the user-friendly GUI editor BBEdit (installation required), add this line:

export EDITOR=/Applications/BBEdit.app/Contents/Helpers/bbedit_tool

To keep a command-line text editor as default while using BBEdit with portfiles, add this:

export EDITOR=/usr/bin/vi
export MP_EDITOR=/Applications/BBEdit.app/Contents/Helpers/bbedit_tool

The help action shows some brief information about the specified action, or if no action is specified, shows basic usage information for port in general.

$ port help selfupdate

Usage: selfupdate --no-sync
Upgrade MacPorts itself and run the sync target
--no-sync   Do not run the sync target, i.e., do not update the ports tree.
           Only checks for (and installs, if available) new versions of
           MacPorts.

The selfupdate action should be used regularly to update the local ports tree with the global MacPorts ports repository so you will have the latest versions of software packages available. It also checks for new releases of MacPorts itself, and upgrades it when necessary.

$ sudo port selfupdate

---> Updating MacPorts base sources using rsync
MacPorts base version 2.11.6 installed,
MacPorts base version 2.11.6 downloaded.
---> Updating the ports tree
---> MacPorts base is already the latest version

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

---> Updating MacPorts base sources using rsync
MacPorts base version 2.11.5 installed,
MacPorts base version 2.11.6 downloaded.
---> Updating the ports tree
---> MacPorts base is outdated, installing new version 2.11.6
Installing new MacPorts release in /opt/local as root:admin; permissions 755

If the selfupdate procedure fails you'll see a message like this:

Error installing new MacPorts base: command execution failed

As always, you can use the debug flag -d to enable verbose output. If your selfupdate failed, re-run it with debug output enabled to see all output generated by the build system.

$ sudo port -d selfupdate

The output may give you an idea why the build failed. Look for the first occurrences of “error”. If you cannot figure out what's wrong yourself, feel free to ask on the <macports-users@lists.macports.org> mailing list and attach the output generated by sudo port -d selfupdate.

selfupdate accepts a single switch:

The sync action performs a subset of selfupdate. It synchronizes the ports tree, as does selfupdate, but it does not check for MacPorts upgrades. On macOS, unless there is a special reason not to do so, run selfupdate instead.

sync does not accept any switches.

The diagnose action checks for common issues in the user's environment and reports all issues it finds to the user, along with possible fixes for said problem.

diagnose accepts a single switch:

The reclaim action attempts to reclaim space by uninstalling inactive ports, and removing unnecessary files that were downloaded during the installation process.

reclaim accepts switches to configure automatic reminders. If passed, the reclaim process will not be run.

The list action lists the currently available version of the specified ports, or if no ports are specified, displays a list of all available ports. The list of available ports is very long, so use search if you are looking for a specific port.

$ port list

The search action allows finding ports by partial matches of the name or description. Other fields can be matched against, and matched in different ways, by using options. port search is the tool of choice if you are looking for a specific software in MacPorts. We recommend you read up on some of its flags to improve your efficiency when searching for ports. Run port help search for an exhaustive list of possible switches.

Suppose you are looking for PHP in MacPorts. You might start with port search php and notice your query produces a lot of output. In fact, at the time of writing this, this search produces 661 matches. By default, port search searches both name and description of a port. While we're looking for PHP, we can reduce the number of hits by using the --name flag. Furthermore, we only want ports whose name starts with “php”, so we add the --glob flag (actually, we could leave it out because it is the default) and modify the search term to php*:

$ port search --name --glob 'php*'

Furthermore, we can enable compact output by using the --line switch. This causes only a single line to be printed for each match:

$ port search --name --line --glob 'php*'

Among a large number of PHP modules you will find the main PHP ports, which are named php<version>. Choose one to install.

If you know regex and know about the format of the PHP versions, you can further reduce the output of port search:

$ port search --name --line --regex '^php\d*$'

php     5.5       lang www    PHP: Hypertext Preprocessor
php4    4.4.9     lang www    PHP: Hypertext Preprocessor
php5    5.3.28    lang www    PHP: Hypertext Preprocessor
php52   5.2.17    lang www    PHP: Hypertext Preprocessor
php53   5.3.28    lang www    PHP: Hypertext Preprocessor
php54   5.4.31    lang www    PHP: Hypertext Preprocessor
php55   5.5.15    lang www    PHP: Hypertext Preprocessor
php56   5.6.0RC2  lang www    PHP: Hypertext Preprocessor

Let us look at another example that is less complicated. Assuming you are looking for rrdtool, a popular system to store and graph time-series data, the simple search approach works well:

$ port search rrd

cacti @0.8.8b (net)
    Cacti is a complete RRDtool network graphing solution.
jrrd @1.0.4 (java)
    Java interface to RRDTool
netmrg @0.20 (net)
    An RRDtool frontend for network monitoring, reporting, and graphing that generates day/week/month
    MRTG style graphs.
network-weathermap @0.97c (net)
    Weathermap is a network visualisation tool, to take graphs you already have and display an
    overview of your network as a map. It supports RRD, MRTG (RRD and old log-format), and
    tab-delimited text files. Other sources are via plugins or external scripts.
php-rrd @1.1.3 (php, net, devel)
    PHP rrdtool extension
php5-rrd @1.1.3 (php, net, devel)
    PHP rrdtool extension
php5-rrdtool @1.0.5 (php, net, devel)
    this port is only a stub and has been made obsolete by php5-rrd
php53-rrd @1.1.3 (php, net, devel)
    PHP rrdtool extension
php54-rrd @1.1.3 (php, net, devel)
    PHP rrdtool extension
php55-rrd @1.1.3 (php, net, devel)
    PHP rrdtool extension
rrdtool @1.4.7_5 (net)
    Round Robin Database
Found 11 ports.

The possible switches to search and their meaning are:

The info action is used to get information about a port: name, version, description, variants, homepage, dependencies, license, and maintainers.

$ port info yubico-pam

yubico-pam @2.16 (security)
Variants:             universal
Description:          The Yubico PAM module provides an easy way to integrate the YubiKey into your
                      existing user authentication infrastructure. The module can be configured to
                      validate YubiKeys against Yubico's YubiCloud infrastructure, a custom YubiKey
                      validation server or it can be used for offline authentication with newer
                      YubiKeys supporting a challenge-response protocol.
Homepage:             https://github.com/Yubico/yubico-pam
Build Dependencies:   pkgconfig, autoconf, automake, libtool
Library Dependencies: ykpers, yubico-c-client
Platforms:            darwin
License:              BSD
Maintainers:          cal@macports.org

The deps action lists the dependencies of a port. Dependencies are the packages required by a port at runtime (library and runtime dependencies) or required to build it (build, fetch, extract, and patch dependencies), or required to run its test suite (test dependencies).

$ port deps apache2

Full Name: apache2 @2.2.27_0+preforkmpm
Library Dependencies: apr, apr-util, expat, openssl, pcre, perl5, zlib

Note that the list of dependencies might depend on the variants you chose. For example, choosing the +openldap variant of apache2 adds a dependency on openldap:

$ port deps apache2 +openldap

Full Name: apache2 @2.2.27_0+openldap+preforkmpm
Library Dependencies: apr, apr-util, expat, openssl, pcre, perl5, zlib, openldap

deps accepts three switches:

The rdeps action is like deps, but operates recursively. That is, each of the ports that the given port depends on is listed, and then for each of those ports, its dependencies are listed, and so on. Unlike deps, the output is also not split into sections for each dependency type, each port is simply listed on its own line with a level of indentation indicating how many levels deep the dependency occurs.

$ port rdeps gettext

The following ports are dependencies of gettext @0.22.5_0:
  ncurses
  gettext-tools-libs
    libiconv
      gperf
    libtextstyle
    gettext-runtime

rdeps accepts four switches:

The variants action 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 you can use to customize your build at install time. See Invoking Port Variants below to install ports that have variants.

$ port variants apache2 +universal

apache2 has the variants:
   eventmpm: Use event MPM (experimental)
     * conflicts with preforkmpm workermpm
   openldap: Enable LDAP support through OpenLDAP
[+]preforkmpm: Use prefork MPM
     * conflicts with eventmpm workermpm
  +universal: Build for multiple architectures
   workermpm: Use worker MPM
     * conflicts with eventmpm preforkmpm

This output lists all variants followed by their description. If a variant depends on or conflicts with other variants, a line detailing that follows. A variant name prefixed by + indicates that it has been enabled (on the command line), while a prefix - indicates that it has been disabled. When bracketed, a prefix + means that the variant is enabled by default. Any [] are derived from the Portfile. While () are derived from the variants.conf. See Section 6.2.3, “variants.conf” for more information on variants.conf.

The action install is used to install a port. Once you determined the name of a port you want (possibly using port search), you can install it using this command. See Section 3.2.1, “Invoking Variants” on how to choose variants when installing a new port. For example,

$ sudo port install apache2 -preforkmpm +workermpm

installs the apache2 port without the preforkmpm, but with the workermpm variant.

If the installation of a port fails, you can enable verbose or debug output by giving the -v or -d flag to port:

$ sudo port -v install apache2

All debug information is also kept in main.log for the port you installed. Its path will be printed automatically if the installation fails. You can manually get the path using port logfile portname. Note that logfiles will automatically be deleted on successful installation.

If the installation of a port fails, you should always clean and try again, i.e., run

$ sudo port clean portname

and re-execute the command you ran before.

You might also want to try enabling trace mode, which can prevent conflicts caused by files installed by other ports or in common system locations, such as /usr/local. To do that, re-run the installation with the -t flag, i.e.,

$ sudo port -t install portname

If the port still fails to install after you have followed these steps, please file a ticket and attach the main.log of a clean attempt.

$ sudo port destroot apache2

install takes the following switches:

The notes action is used to display any notes that a port's author included. These can contain anything, but by convention are brief, and typically contain quick start steps for configuring and using the port, pitfalls to watch out for, or other information that users should be aware of. These same notes are also displayed after installing a port. Many ports have no notes. More extensive documentation can often be found at a port's homepage, or in its installed files.

$ port notes xinit

--->  xinit has the following notes:
  To use MacPorts' X11 as the default server, install xorg-server, log out, and
  log back in.

The action clean deletes intermediate files created by MacPorts while installing a port. A port clean is often necessary when builds fail and should be the first thing to try after a failed installation attempt.

$ sudo port clean portname

port clean can also be used to remove corrupted downloads after a failed fetch phase, by specifying the --dist flag:

$ sudo port clean --dist portname

deletes all files that have been downloaded for the given port.

clean accepts the following options:

The uninstall action will remove an installed port. It is one of the actions you will use fairly often in MacPorts.

$ sudo port uninstall portname

MacPorts will refuse to uninstall ports that are still needed by other ports. For example:

$ sudo port uninstall libcomerr

--->  Unable to uninstall libcomerr @1.42.9_0, the following ports depend on it:
--->    kerberos5 @1.11.3_0
--->    subversion @1.8.9_0
--->    subversion-perlbindings-5.16 @1.8.9_0
Error: port uninstall failed: Please uninstall the ports that depend on libcomerr first.

You can recursively uninstall all ports that depend on the given port before uninstalling the port itself to work around this. To do that, use the --follow-dependents flag.

$ sudo port uninstall --follow-dependents libcomerr

You can also override this safety check using the -f (force) flag. Since this will obviously break the dependents you shouldn't do this unless you know what you are doing.

$ sudo port -f uninstall libcomerr

Uninstalling a port will not uninstall ports that have been automatically installed as dependencies of the uninstalled port and are otherwise unused. You can trigger this behavior by passing the --follow-dependencies flag. Ports that were manually installed (i.e., are marked as “requested”) or have other dependents will not be removed. You can manually uninstall the unneeded ports later using the leaves pseudo-port, e.g., using sudo port uninstall leaves.

uninstall supports the following switches:

The contents action displays a list of all files that have been installed by a given port. You can only use contents for ports you installed.

$ port contents xorg-renderproto

Port xorg-renderproto contains:
  /opt/local/include/X11/extensions/render.h
  /opt/local/include/X11/extensions/renderproto.h
  /opt/local/lib/pkgconfig/renderproto.pc
  /opt/local/share/doc/renderproto/renderproto.txt

Common uses for contents are finding the location of a port's executable after installing it. The following line is usually helpful in this case:

$ port -q contents portname | grep -E '/s?bin/'

The -q (quiet) flag suppresses the header line in this case, but is not strictly necessary.

contents accepts:

The installed action displays the installed versions and variants of the specified ports, or if no ports are specified, all installed ports. It also displays whether a port is “active”, i.e., whether the files belonging to this port are currently present on disk or inactive, i.e., stashed away in a compressed tarball.

$ port installed

The following ports are currently installed:
  a52dec @0.7.4_0 (active)
  adns @1.4_0 (active)
  apache2 @2.2.27_0+preforkmpm (active)
  apr @1.5.1_0 (active)
  apr-util @1.5.3_0 (active)
  aquaterm @1.1.1_0 (active)
  asciidoc @8.6.9_1+python27 (active)
  …
  XviD @1.3.3_0 (active)
  xz @5.0.5_0 (active)
  yasm @1.2.0_0 (active)
  ykpers @1.12.0_0 (active)
  youtube-dl @2014.07.25.1_0+python27 (active)
  yubico-c-client @2.12_0 (active)
  yubico-pam @2.16_0 (active)
  zlib @1.2.8_0 (active)

Use -v to also display the platform and CPU architecture(s) for which the ports were built, and any variants which were explicitly negated.

$ port -v installed libsdl

The following ports are currently installed:
  libsdl @1.2.15_3-x11 (active) platform='darwin 13' archs='x86_64'

The outdated action checks your installed ports against the current ports tree to see they have been updated since you installed them. Note that you will only get new versions by updating your ports tree using selfupdate (or sync).

$ port outdated

The following installed ports are outdated:
gnupg                          1.4.16_0 < 1.4.18_0
gnupg2                         2.0.22_2 < 2.0.25_0
gpg-agent                      2.0.22_1 < 2.0.25_0
gpgme                          1.5.0_0 < 1.5.1_0
HexFiend                       2.1.2_1 < 2.3.0_0
libksba                        1.0.8_0 < 1.3.0_0
p5.16-class-methodmaker        2.180.0_1 < 2.210.0_0
p5.16-gnupg-interface          0.330.0_3 < 0.500.0_1
p5.16-ipc-run                  0.910.0_1 < 0.920.0_0

port outdated lists the ports for which an upgrade is available and on the second column, why MacPorts thinks the port needs an upgrade. In most cases, this will be an increase in the version number. If it isn't, more details will be given.

The upgrade action upgrades installed ports and their dependencies to the latest version available in MacPorts. In most cases, you will run

$ sudo port upgrade outdated

to update all ports that have an upgrade available. You can, however, selectively upgrade ports if you want to delay other upgrades until later. This is not recommended unless you know what you are doing, since you might experience software errors for the ports that have not yet been upgraded. To upgrade individual ports, specify the name(s) of the port(s) to upgrade:

$ sudo port upgrade gnupg2

Note that MacPorts may decide to upgrade other dependent ports before upgrading the port you requested to be updated. Do not attempt to prevent this, since it will very likely lead to problems later.

$ port installed portname

$ sudo port activate portname @old-version

$ sudo port -u upgrade outdated

$ sudo port uninstall inactive

upgrade accepts a number of switches:

The dependents action reports what ports depend upon a given (installed) port, if any.

$ port dependents openssl

apache2 depends on openssl
curl depends on openssl
cyrus-sasl2 depends on openssl
git depends on openssl
kerberos5 depends on openssl
lftp depends on openssl
libssh depends on openssl
mosh depends on openssl
openldap depends on openssl
p5.16-net-ssleay depends on openssl
python27 depends on openssl
python32 depends on openssl
qt4-mac depends on openssl
ruby19 depends on openssl
serf1 depends on openssl
textmate2 depends on openssl
wireshark depends on openssl

Note that dependents does not work for ports that are not installed on your system. If you want to find out, which ports depend on a port that you have not installed, you can use

$ port echo depends:portname

This command will, however, not cover dependencies that are only present in non-default variants.

The livecheck action checks to see if the application corresponding to a given port has been updated at the developer's download site. This action is mostly useful for port maintainers to determine whether their port needs to be updated, but other may also wish to see if a port packages the latest available version. See Section 5.9, “Livecheck / Distcheck” for more information on livecheck.

$ port livecheck rb19-sass

rb19-sass seems to have been updated (port version: 3.3.10, new version: 3.3.14)

The lint action checks if the Portfile conforms to the MacPorts standards specified in Portfile Development. You should use this if you modified a Portfile before submitting patches back to MacPorts.

If a Portfile validates fine the following message is shown.

$ port lint rb19-sass

--->  Verifying Portfile for rb19-sass
--->  0 errors and 0 warnings found.

Otherwise the warnings and errors are listed.

$ port lint abiword

--->  Verifying Portfile for abiword
Warning: Variant use_binary does not have a description
Warning: Variant use_source does not have a description
Warning: no license set
--->  0 errors and 3 warnings found.

lint has the following flag:

Some ports install software that is meant to run as a daemon. Or in other words, a long-running background process.

Examples of this are database servers like MySQL or PostgreSQL.

On macOS, launchd is primarily responsible for starting, stopping, and managing long-running services.

Ports that want to run daemon processes can install their own .plist file(s) into launchd. These files will allow launchd to start and manage the port's daemon processes.

So once a port is installed, the load action can be used to do the above and activate the port's launchd service(s):

$ sudo port load prometheus

--->  Loading startupitem 'prometheus' for prometheus

Now the port's service(s) should be running in launchd. This can be verified with the launchctl command:

$ sudo launchctl list | grep macports

49119   0       org.macports.prometheus

To stop the daemon service and mark it as disabled for launchd, use the port unload command.

As discussed in the port load section, the port load command can be used to install and activate a port's daemon service(s) in launchd.

The unload action reverses this.

port unload will stop the port's daemon processes, and mark the port's service .plist as disabled:

$ sudo port unload prometheus

--->  Unloading startupitem 'prometheus' for prometheus

The port's service(s) should no longer be present in launchctl list.

A variant can only be selected when a port is installed. After you have determined what variants a given port has, if any, you may install a port using a variant by specifying its name preceded by a plus sign on the command line, for example

$ sudo port install apache2 +openldap

Multiple variants can be selected by simply listing them one after another separated by a space.

$ sudo port install apache2 +openldap +universal

Use a minus sign to deselect a variant that is on by default.

$ sudo port install apache2 -preforkmpm +workermpm

Note that you will not see any confirmation of successful variant selection and MacPorts will not warn you if you misspelled a variant's name. If your installation is successful, but the chosen feature still seems to be missing, check for possible typos. You can use port installed to verify that the port has been installed with the chosen variant.

This happens because MacPorts will also use the specified variants for any dependencies. For example,

$ sudo port install apache2 +mariadb

is accepted even though apache2 does not have a +mariadb variant. However, it depends on the apr-util port which does have the +mariadb variant and will be installed with it.

MacPorts will remember the variants that were used when installing a port. If you upgrade a port later, the same variants will be used, unless you manually specify different variants.

A Portfile can specify a default set of variants that will be used when you do not manually override it. Not all ports specify default variants – if there are no default variants, no variants are chosen by default.

If you wish to disable a variant that has been enabled by default, either by the Portfile, or by your configuration in variants.conf, you can negate the variant in question by prefixing the variant name with a minus on the command line:

$ sudo port install apache2 -preformmpm +workermpm

The local ports tree is a collection of files that contain information on which packages are available through MacPorts and how they can be installed. You should regularly update your ports tree to get access to updated versions of software and bug fixes. To do that, use selfupdate:

$ sudo port selfupdate

Password:
---> Updating MacPorts base sources using rsync
MacPorts base version 2.11.6 installed,
MacPorts base version 2.11.6 downloaded.
---> Updating the ports tree
---> MacPorts base is already the latest version
The ports tree has been updated. To upgrade your installed ports, you should run
  port upgrade outdated

To see what's new after running selfupdate, you can use port outdated to generate a list of ports that have newer versions available. This can help in estimating the time required for sudo port upgrade outdated, even though this depends on further factors such as binary package availability and a port's build time.

$ port outdated

The following installed ports are outdated:
gnupg                          1.4.16_0 < 1.4.18_0
gnupg2                         2.0.22_2 < 2.0.25_0
gpg-agent                      2.0.22_1 < 2.0.25_0
gpgme                          1.5.0_0 < 1.5.1_0
HexFiend                       2.1.2_1 < 2.3.0_0
libksba                        1.0.8_0 < 1.3.0_0
p5.16-class-methodmaker        2.180.0_1 < 2.210.0_0
p5.16-gnupg-interface          0.330.0_3 < 0.500.0_1
p5.16-ipc-run                  0.910.0_1 < 0.920.0_0

To upgrade all your installed and outdated ports, run

$ sudo port upgrade outdated

In case you want to upgrade only a specific port (not recommended unless you know what you are doing), replace “outdated” in the command given above with the port's name:

$ sudo port upgrade makedepend

Password:
---> Computing dependencies for makedepend
---> Fetching makedepend
---> Attempting to fetch makedepend-1.0.3.tar.bz2 from https://lil.fr.distfiles.macports.org/makedepend
---> Verifying checksum(s) for makedepend
---> Extracting makedepend
---> Configuring makedepend
---> Building makedepend
---> Staging makedepend into destroot
---> Computing dependencies for makedepend
---> Installing makedepend @1.0.3_0
---> Deactivating makedepend @1.0.2_0
---> Activating makedepend @1.0.3_0
---> Cleaning makedepend

Note that MacPorts will upgrade any dependencies of a port first before updating the port itself. So even if you request the update of a single port only, other ports may be upgraded first because they are in the dependency tree. Do not try to avoid this, as it will very likely lead to problems later on – the new version of the port you want to upgrade might require the newer dependency, or it might only have been upgraded at all to be rebuilt against the updated dependency, in which case avoiding the update of the dependency defeats the purpose of the reinstallation.

By default, upgrading ports in MacPorts does not remove the older versions. This is a safety measure to ensure you can go back to a working and tested version in case an update goes wrong. To save disk space, you should periodically uninstall any old versions you no longer need.

Use

$ port installed inactive

to get a list of inactive ports you likely no longer need.

The following ports are currently installed:
  gnupg @1.4.16_0
  gnupg2 @2.0.22_2
  gpg-agent @2.0.22_1
  gpgme @1.5.0_0
  HexFiend @2.1.2_1
  libksba @1.0.8_0
  p5.16-class-methodmaker @2.180.0_1
  p5.16-gnupg-interface @0.330.0_3
  p5.16-ipc-run @0.910.0_1

Check the list for any ports you might still want to keep. To remove all of them at once, run

$ sudo port uninstall inactive

Password:
--->  Uninstalling p5.16-gnupg-interface @0.330.0_3
--->  Cleaning p5.16-gnupg-interface
--->  Uninstalling gnupg @1.4.16_0
--->  Cleaning gnupg
--->  Uninstalling gpgme @1.5.0_0
--->  Cleaning gpgme
--->  Uninstalling gnupg2 @2.0.22_2
--->  Cleaning gnupg2
--->  Uninstalling gpg-agent @2.0.22_1
--->  Cleaning gpg-agent
--->  Uninstalling HexFiend @2.1.2_1
--->  Cleaning HexFiend
--->  Uninstalling libksba @1.0.8_0
--->  Cleaning libksba
--->  Uninstalling p5.16-class-methodmaker @2.180.0_1
--->  Cleaning p5.16-class-methodmaker
--->  Uninstalling p5.16-ipc-run @0.910.0_1
--->  Cleaning p5.16-ipc-run

Of course you could also select only a specific inactive port, but that requires to specify the exact version:

$ sudo port uninstall HexFiend @2.1.2_1

Password:
--->  Uninstalling HexFiend @2.1.2_1
--->  Cleaning HexFiend

To uninstall all inactive ports but a single one, you can use the following shortcut:

$ sudo port uninstall inactive and not portname

If you want to find all ports that depend on a given other port, you can use

$ port echo depends:portname

If you are only interested in the dependent ports that you actually have installed, you can use the quicker and more accurate dependents:

$ port dependents portname

gnupg2 depends on libksba
gpg-agent depends on libksba

MacPorts also has a recursive version of the dependents action called rdependents:

$ port rdependents libksba

The following ports are dependent on libksba:
  gnupg2
    gpgme
  gpg-agent

Finally, to find out which port you manually installed caused the automatic installation of a dependency, use the following expression:

$ port installed requested and rdependentof:portname

$ port installed requested and rdependentof:libksba

The following ports are currently installed:
  gnupg2 @2.0.25_0 (active)

After a while of using MacPorts, installing and uninstalling ports, packages that have been automatically installed as dependencies for other ports are left behind, even though they are no longer necessary. Ports that have not been manually installed (“requested”) and do not have any dependents are called “leaves” and can be identified using the leaves pseudo-port, for example in conjunction with the echo or installed action.

$ port echo leaves

git-flow                       @0.4.1_2
gmake                          @4.0_0
gpgme                          @1.5.1_0
hs-download-curl               @0.1.4_0
pkgconfig                      @0.28_0
py27-docutils                  @0.12_0
python32                       @3.2.5_0
texi2html                      @5.0_1
yasm                           @1.2.0_0

These leaves may be wanted, but are in most cases unneeded. See Section 3.3.7, “Keep Your Installation Lean by Defining Leaves as Requested Ports” to find out how to mark some of the leaves as requested. You can uninstall all leaves using

$ sudo port uninstall leaves

Note that the uninstallation can cause new ports to become leaves. To uninstall all leaves, you can use the rleaves pseudo-port instead.

To go through this process interactively so you can make sure you're not uninstalling anything you want to keep, you can install the port_cutleaves port. After installation, run it with

$ sudo port_cutleaves

Well, before we come to the procedure of defining your requested ports, let's have a look at a typical scenario where you want to understand what is actually installed and what is on the other hand truly necessary for your system. Say checking leaves of your MacPorts installation gives this output:

$ port echo leaves

git-flow                       @0.4.1_2
gmake                          @4.0_0
gpgme                          @1.5.1_0
hs-download-curl               @0.1.4_0
pkgconfig                      @0.28_0
py27-docutils                  @0.12_0
python32                       @3.2.5_0
texi2html                      @5.0_1
yasm                           @1.2.0_0

Now it is up to the user to decide what's needed and what is not. We've noticed pkgconfig is needed to build many ports, and while it is strictly not needed after installation, we'd like to keep it around to avoid installing it over and over again. python32, texi2html, and yasm are only needed to update mplayer2, and since that software is rarely updated, we will re-install those ports again when they are needed. Since they are all distributable, MacPorts will use pre-built binaries for their installation anyway, so re-installing them wouldn't take long anyway. We don't really know why the rest of the leaves were installed, so we're just going to remove them for now.

Since we decided to keep pkgconfig, we are going to mark it as manually installed (“requested” in MacPorts lingo) using:

$ sudo port setrequested pkgconfig

When you've step-by-step figured out which ports you want to keep on your system and have set them as requested, you'll have a list of unnecessary ports, which you can get rid of using

$ sudo port uninstall leaves

Note that uninstalling leaves may mark new ports as leaves, so you will have to repeat the process. You can install the port_cutleaves port, which is a special script for the job. It allows you to interactively decide whether to keep or uninstall a port. Run it as

$ sudo port_cutleaves

[Leaf 1 of 8] hs-download-curl @0.1.4_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort:
** hs-download-curl @0.1.4_0 will be kept.
[Leaf 2 of 8] gmake @4.0_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** gmake @4.0_0 will be uninstalled.
[Leaf 3 of 8] texi2html @5.0_1 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** texi2html @5.0_1 will be uninstalled.
[Leaf 4 of 8] yasm @1.2.0_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** yasm @1.2.0_0 will be uninstalled.
[Leaf 5 of 8] python32 @3.2.5_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** python32 @3.2.5_0 will be uninstalled.
[Leaf 6 of 8] py27-docutils @0.12_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** py27-docutils @0.12_0 will be uninstalled.
[Leaf 7 of 8] git-flow @0.4.1_2 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** git-flow @0.4.1_2 will be uninstalled.
[Leaf 8 of 8] gpgme @1.5.1_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** gpgme @1.5.1_0 will be uninstalled.
--->  Deactivating gmake @4.0_0
--->  Cleaning gmake
--->  Uninstalling gmake @4.0_0
--->  Cleaning gmake
--->  Deactivating texi2html @5.0_1
--->  Cleaning texi2html
--->  Uninstalling texi2html @5.0_1
--->  Cleaning texi2html
--->  Deactivating yasm @1.2.0_0
--->  Cleaning yasm
--->  Uninstalling yasm @1.2.0_0
--->  Cleaning yasm
--->  Deactivating python32 @3.2.5_0
--->  Cleaning python32
--->  Uninstalling python32 @3.2.5_0
--->  Cleaning python32
--->  Deactivating py27-docutils @0.12_0
--->  Cleaning py27-docutils
--->  Uninstalling py27-docutils @0.12_0
--->  Cleaning py27-docutils
--->  Deactivating git-flow @0.4.1_2
--->  Cleaning git-flow
--->  Uninstalling git-flow @0.4.1_2
--->  Cleaning git-flow
--->  Deactivating gpgme @1.5.1_0
--->  Cleaning gpgme
--->  Uninstalling gpgme @1.5.1_0
--->  Cleaning gpgme
The following ports were uninstalled:
  gmake @4.0_0
  texi2html @5.0_1
  yasm @1.2.0_0
  python32 @3.2.5_0
  py27-docutils @0.12_0
  git-flow @0.4.1_2
  gpgme @1.5.1_0
Search for new leaves?
  [no] / (y)es: y
[Leaf 1 of 1] py27-roman @2.0.0_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** py27-roman @2.0.0_0 will be uninstalled.
--->  Deactivating py27-roman @2.0.0_0
--->  Cleaning py27-roman
--->  Uninstalling py27-roman @2.0.0_0
--->  Cleaning py27-roman
The following ports were uninstalled:
  py27-roman @2.0.0_0
Search for new leaves?
  [no] / (y)es: y
There are no new leaves to process.

You can get a list of all ports you previously set as requested (or installed manually) using:

$ port installed requested

We recommend you check the list of leaves from time to time to keep your system free of too much “garbage”. You should also periodically check the list of your requested ports and mark any ports you no longer need as unrequested using

$ sudo port unsetrequested portname

Then check for new leaves to cut down the number of installed ports and the size of your MacPorts installation.

Binary archives can only be used on a target system running MacPorts. They allow MacPorts utilities to skip the build (which is usually the phase that takes longest) and begin installation after the destroot phase. Binary archives are automatically created whenever a port is installed, and can also be downloaded from a server. MacPorts runs a buildbot infrastructure that creates prebuilt binary packages for all ports in MacPorts for the default installation prefix. Buildbots exist for systems later or equal to Snow Leopard. If a port builds successfully and its license and those of its dependencies allow binary redistribution, the archives are uploaded to packages.macports.org and will be automatically used by MacPorts during installation.

You can manually create an archive (and see debug output for its creation) using

$ sudo port -d archive logrotate

--->  Installing logrotate @3.8.6_2+gzip
[…]
DEBUG: Creating logrotate-3.8.6_2+gzip.darwin_13.x86_64.tbz2
[…]
a .
a ./+COMMENT
a ./+CONTENTS
a ./+DESC
a ./+PORTFILE
a ./+STATE
a ./opt
a ./opt/local
a ./opt/local/etc
a ./opt/local/sbin
a ./opt/local/share
a ./opt/local/var
a ./opt/local/var/run
a ./opt/local/var/run/logrotate
a ./opt/local/var/run/logrotate/.turd_logrotate
a ./opt/local/share/logrotate
a ./opt/local/share/man
a ./opt/local/share/man/man5
a ./opt/local/share/man/man8
a ./opt/local/share/man/man8/logrotate.8.gz
a ./opt/local/share/man/man5/logrotate.conf.5.gz
a ./opt/local/share/logrotate/CHANGES
a ./opt/local/share/logrotate/COPYING
a ./opt/local/share/logrotate/logrotate.conf.example
a ./opt/local/share/logrotate/org.macports.logrotate.plist.example
a ./opt/local/sbin/logrotate
a ./opt/local/etc/logrotate.d
a ./opt/local/etc/logrotate.d/.turd_logrotate
DEBUG: Archive logrotate-3.8.6_2+gzip.darwin_13.x86_64.tbz2 packaged

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

Binary packages are standalone binary installers that are precompiled; they do not require MacPorts on the target system. As such, they are helpful in generating disk images or installers to be redistributed to users without relying on MacPorts for installation. Binary installers created with MacPorts are usually .pkg (macOS Installer packages). MacPorts can also convert a .pkg package into a macOS .dmg disk image. You can create binary packages using port as shown in the following examples.

Create a macOS .pkg installer for the pstree port:

$ sudo port pkg pstree

You may also create a macOS .dmg disk image file instead:

$ sudo port dmg pstree

In most cases you probably want to package a port and all its library and runtime dependencies in a single package. You can use a metapackage to do this. Create one using:

$ sudo port mpkg gimp2

Just as with a single package, a metapackage can also be wrapped in a .dmg.

$ sudo port mdmg gimp2

All packages are placed in a port's work directory, which you can locate using:

$ port work portname

# -*- 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
PortSystem          1.0
name                rrdtool
version             1.2.23
categories          net
platforms           darwin
license             GPL-2+
maintainers         julesverne
description         Round Robin Database
long_description    RRDtool is a system to store and display time-series data
homepage            https://people.ee.ethz.ch/~oetiker/webtools/rrdtool/
master_sites        https://oss.oetiker.ch/rrdtool/pub/ \
                    ftp://ftp.pucpr.br/rrdtool/
checksums           rmd160  7bbfce4fecc2a8e1ca081169e70c1a298ab1b75a \
                    sha256  2829fcb7393bac85925090b286b1f9c3cd3fbbf8e7f35796ef4131322509aa53 \
                    size    1061530
depends_lib         path:bin/perl:perl5 \
                    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}/share/doc/${name}
    xinstall -m 755 ${worksrcpath}/README ${destroot}${prefix}/share/doc/${name}
}

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"

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

subport name body

The subport declaration causes MacPorts to define an additional port, with the name given by the declaration. The keywords for the subport are those in the global section of the Portfile, and those in the brace-enclosed body.

For example, if a Portfile contains:

Portfile                   1.0
name                       example
depends_lib                aaa
configure.args             --bbb
subport example-sub1 {
    depends_lib-append     ccc
    configure.args         --ddd
}
subport example-sub2 {
    depends_lib-append     eee
    configure.args-append  --fff
}

MacPorts will produce the same results as if there were three Portfiles:

Portfile                   1.0
name                       example
# Note: For the parent port, 'subport' has the same value as 'name'.
# Also, one cannot override the subport name; it's shown here merely
# to illustrate what the value is set to, for the given context.
#subport                   example
depends_lib                aaa
configure.args             --bbb

Portfile                   1.0
name                       example
# Value for 'subport' shown here for illustration purposes only; see note above.
#subport                   example-sub1
depends_lib                aaa
depends_lib-append         ccc
configure.args             --ddd

Portfile                   1.0
name                       example
# Value for 'subport' shown here for illustration purposes only; see note above.
#subport                   example-sub2
depends_lib                aaa
depends_lib-append         eee
configure.args             --bbb
configure.args-append      --fff

Because MacPorts treats each subport as a separate port declaration, each subport will have its own, independent phases: fetch, configure, build, destroot, install, activate, etc. However, because the subports share the global declaration part, all the subports will by default share the same dist_subdir. This means that MacPorts only needs to fetch the distfiles once, and the remaining subports can reuse the distfiles.

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.

Generally speaking, you should create one patch file for each logical change that needs to be applied. Patchfile filenames should uniquely distinguish the file and generally be of the form <identifier>.diff or <identifier>.patch, where the identifier is a reference to the problem or bug it is supposed to solve. An example filename would be destdir-variable-fix.diff.

To create a patch to modify a single file, follow the steps below.

MacPorts applies patch files automatically, but 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 set of declarations rather than a piece of code. It is best to format the port file is if it were a table consisting of keys and values. In fact, the simplest of ports will only contain a small block of values. Nicely formatted compact tables will result in more values being visible at the same time.

The two columns should be 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"

When items require multiple lines with line continuation, they can be separated from the previous and next items with a blank line. Indent the additional lines to the same column that the right side begins on in the first line.

checksums               rmd160  7bbfce4fecc2a8e1ca081169e70c1a298ab1b75a \
                        sha256  2829fcb7393bac85925090b286b1f9c3cd3fbbf8e7f35796ef4131322509aa53 \
                        size    1061530

Should a key item such as a phase or variant require braces, the opening brace should appear on the same line and the closing brace should be on its own line. The block formed by the braces is indented for visual clearance. Braces merely quoting strings, for example the description of variants, are placed on the same line without line breaks.

variant mysql5 description {Enable support for MySQL 5} {
    depends_lib-append        port:mysql5
    configure.args-replace    --without-mysql5 --with-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

For packages that use a configuration file, it's generally desirable to not overwrite user-changes in the config file when performing an upgrade or reinstall.

post-destroot {
    # Move conf file to sample so it does not get overwritten
    file rename ${destroot}${prefix}/etc/apcupsd/apcupsd.conf \
                ${destroot}${prefix}/etc/apcupsd/apcupsd.conf.sample
}
post-activate {
    # Create initial conf file if needed
    if {![file exists ${prefix}/etc/apcupsd/apcupsd.conf]} {
        file copy ${prefix}/etc/apcupsd/apcupsd.conf.sample \
                  ${prefix}/etc/apcupsd/apcupsd.conf
    }
}

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}

If there is the need to replace a port with another port or a renaming is necessary for some reason, the port should be marked as replaced_by.

As an illustration of a typical workflow the port “skrooge-devel” shall be taken. This port had been used for testing new versions of skrooge, but it turned out to have become unnecessary due to the fact that skrooge's developers currently prefer a distribution via port “skrooge” instead.

At the end of this section the use of the obsolete PortGroup is suggested as an even shorter approach to the below described workflow.

# -*- 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
PortSystem          1.0
PortGroup           kde4    1.1
fetch.type          svn
svn.url             svn://anonsvn.kde.org/home/kde/trunk/extragear/office/skrooge
svn.revision        1215845
name                skrooge-devel
version             0.8.0-${svn.revision}
categories          kde finance
maintainers         mk pixilla openmaintainer
description         Skrooge
long_description    Personal finance management tool for KDE4, with the aim of being highly intuitive, while \
                    providing powerful functions such as reporting (including graphics), persistent \
                    Undo/Redo, encryption, and much more...
conflicts           skrooge
platforms           darwin
license             GPL-3
homepage            https://skrooge.org
master_sites        https://skrooge.org/files/
livecheck.type      none
distname            skrooge
depends_lib-append  port:kdelibs4 \
                    port:libofx \
                    port:qca-ossl \
                    port:kdebase4-runtime \
                    port:oxygen-icons

# -*- 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
PortSystem          1.0
name                skrooge-devel
svn.revision        1215845
version             0.8.0-${svn.revision}
revision            1
replaced_by         skrooge
categories          kde finance
maintainers         mk pixilla openmaintainer
description         Skrooge
long_description    Personal finance management tool for KDE4, with the aim of being highly intuitive, while \
                    providing powerful functions such as reporting (including graphics), persistent \
                    Undo/Redo, encryption, and much more...
platforms           darwin
license             GPL-3
homepage            https://skrooge.org
livecheck.type      none
pre-configure {
    ui_error "Please do not install this port since it has been replaced by 'skrooge'."
    return -code error
}
distfiles

%% sudo port upgrade skrooge-devel

--->  skrooge-devel is replaced by skrooge
--->  Computing dependencies for skrooge
--->  Fetching skrooge
--->  Verifying checksum(s) for skrooge
--->  Extracting skrooge
--->  Configuring skrooge
--->  Building skrooge
--->  Staging skrooge into destroot
--->  Deactivating skrooge-devel @0.8.0-1215845_0
--->  Cleaning skrooge-devel
--->  Computing dependencies for skrooge
--->  Installing skrooge @0.8.0.6_0
--->  Activating skrooge @0.8.0.6_0
##########################################################
# Don't forget that dbus needs to be started as the local 
# user (not with sudo) before any KDE programs will launch
# To start it run the following command:                  
# launchctl load /Library/LaunchAgents/org.freedesktop.dbus-session.plist
##########################################################
######################################################
#  Programs will not start until you run the command 
#  'sudo chown -R $USER ~/Library/Preferences/KDE'  
#  replacing $USER with your username.              
######################################################
--->  Cleaning skrooge

%% sudo port install skrooge-devel

--->  Fetching skrooge-devel
--->  Verifying checksum(s) for skrooge-devel
--->  Extracting skrooge-devel
--->  Configuring skrooge-devel
Error: Please do not install this port since it has been replaced by 'skrooge'.
Error: Target org.macports.configure returned: 
Log for skrooge-devel is at: /opt/local/var/macports/logs/_opt_local_var_macports_sources_rsync.macports.org_release_ports_kde_skrooge-devel/main.log
Error: Status 1 encountered during processing.
To report a bug, see <https://guide.macports.org/#project.tickets>

# -*- 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
PortSystem          1.0
PortGroup           obsolete 1.0
name                skrooge-devel
replaced_by         skrooge
svn.revision        1215845
version             0.8.0-${svn.revision}
revision            2
categories          kde finance
        

If a port has to be removed from MacPorts one should consider the hints concerning replacing it by some alternative port given above. It is recommended to wait one year before the port directory is actually removed from the MacPorts ports tree.

If there is no replacement for a port, it can simply be deleted immediately.

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

The list of keywords related to the build phase.

The list of keywords related to the test phase.

The list of keywords related to the destroot phase.

There are two types of dependencies: port dependencies and file dependencies. Port dependencies can be satisfied by reference to a port (the MacPorts registry is queried), or by reference to a file (whether provided by a port or not). The most commonly-used type of dependencies in Portfiles are port dependencies, because dependencies should be provided by MacPorts ported software whenever possible, and usually only one port can provide the needed libraries and files.

But when satisfying a dependency with vendor-supplied software is preferred for special reasons, or when it is possible for more than one port to satisfy a dependency, then file dependencies may be used. An example of the former is with ubiquitous utilities like awk, grep, make or sed, where the versions in macOS are often sufficient; an example of the latter is with “-devel” ports—these ports provide a different version of the same files (though only one can be activated at a time).

Port dependencies, the preferred type, are specified as shown in these examples:

depends_lib         port:rrdtool port:apache2
depends_build       port:libtool
depends_run         port:apache2 port:php5

File dependencies should only be used if one of the reasons listed above applies. There are three types: bin for programs, lib for libraries, and path for any installed file. File dependencies are specified in the form: <type>:<filespec>:<port>.

For bin dependencies, <filespec> is the name of a program in a bin directory like ${prefix}/bin, /usr/bin, /bin, and the associated sbin directories.

For lib dependencies, <filespec> is the name of a library (but without its extension) in a lib directory like ${prefix}/lib, /usr/lib, /lib, some Framework directories, and those found in environment variables like DYLD_LIBRARY_PATH.

For path dependencies, <filespec> is the complete absolute path to the file, or more usually, when the file is inside ${prefix}, it is specified relative to ${prefix}. Since path dependencies are the only ones which would find files only in an absolute path or a path inside ${prefix} they are - in cases when a port needs to be more restrictive - often used instead of bin and lib dependencies .

Note that the <port> specified is only installed if the specified library, binary, or file is not found. See the examples below:

depends_lib         lib:libX11.6:xorg
depends_build       bin:glibtool:libtool
depends_run         path:lib/libltdl.a:libtool

User-selected variants are those that are defined so a user can invoke them to enable port options at install time. They also allow a port author a level of modularity and control using the keyword default_variants (see below).

User-selected variants ought to provide a description, which will be displayed when using command port variants foo. The syntax used for the description keyword is shown below.

variant bar description {Add IMAP support} {}

Descriptions should be short but clear, and not merely repeat the name of the variant. To allow for compatibility for possible MacPorts GUI support, a good rule of thumb is to use sentence fragments for brevity, with a capitalized first letter and no trailing punctuation. Think of them as short labels such as ones you'd find next to a GUI checkbox or radio button. Thus, it would be better to write “Build with support for foo” instead of “Builds with support for foo”; “Add support for foo” would be better than “Adds support for foo”.

Variant descriptions are strings, so one should take care not to put whitespace between the brackets and the beginning and end of the variant description, and also not to use unnecessary whitespace, unlike with port descriptions and long_descriptions.

Platform variants are either defined by default in MacPorts base, or defined by a port author to customize a port's installation according to OS (operating system) or hardware platform.

The keywords in this section may be used with either “executable” or “script” StartupItems (see below).

Daemons run continuously, so monitoring the health of daemon processes and restarting them if they die is an important StartupItems' feature. “Executable” StartupItems are preferred over “script” StartupItems because daemondo launches the daemon directly, rather than indirectly via a script, and therefore it automatically knows how to monitor a daemon process and restart it if it dies. Daemons used with “executable” StartupItems may be programs or scripts (shell, perl, python, etc.) as long as the script itself is the daemon, rather than merely what launches the daemon. In the latter case “script” StartupItems are to be used.

StartupItems of type “script” create a wrapper during port installation for daemondo that will be used to launch a daemon startup script present in an application's source distribution (MacPorts does not create daemon startup scripts) for daemons that require a script.

A typical snippet of a startup script that may be used with a “script” StartupItem is shown below. Notice that the script is not a daemon; rather the script indirectly launches the vm-pop3d daemon.

#!/bin/sh
case "$1" in
    start)
        echo -n "Starting vm-pop3d: "
        /opt/local/sbin/vm-pop3d -d 10 -t 600
[... trimmed ...]

A port with a StartupItem places a link to a .plist file for the port's daemon within /Library/LaunchDaemons/. A .plist file is an XML file; MacPorts installs .plist files tagged as “disabled” for the sake of security. You may enable a startup script (tag the.plist file as “enabled”) and load it into launchd with a single command as shown.

%% sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist

You may stop a running startup script, disable it (tag the.plist file as “disabled”), and unload it from launchd with a single command as shown.

%% sudo launchctl unload -w /Library/LaunchDaemons/org.macports.mysql5.plist

During port installation a MacPorts StartupItem creates a .plist file in ${prefix}/etc/LaunchDaemons/, and places a symbolic link to the .plist file within /Library/LaunchDaemons/ if ${startupitem.install} is true.

For example, the StartupItem for the mysql5 port is org.macports.mysql5.plist, and it is linked as shown.

%% ls -l /Library/LaunchDaemons

org.macports.mysql5.plist ->
/opt/local/etc/LaunchDaemons/org.macports.mysql5/org.macports.mysql5.plist

For “script” StartupItems, in addition to a .plist file, a wrapper is also created.

%% ls -l /opt/local/etc/LaunchDaemons/org.macports.mysql5/

-rwxr-xr-x   2 root  wheel  475 Aug  2 14:16 mysql5.wrapper
-rw-r--r--   2 root  wheel  975 Aug  2 14:16 org.macports.mysql5.plist

The wrapper manipulates the script as specified in the startupitem.start and startupitem.stop keywords. An example wrapper script snippet is shown below.

#!/bin/sh
# MacPorts generated daemondo support script
# Start
Start()
{
    /opt/local/share/mysql5/mysql/mysql.server start
}
# Stop
Stop()
{
    /opt/local/share/mysql5/mysql/mysql.server stop
}
[... trimmed ...]

PortGroups are simply include files for portfiles. They can define as much or as little as a portgroup author feels is necessary to provide a set of definitions or behaviors common to a group of portfiles, in order that those portfiles can be expressed as simply as possible with minimum redundancy.

See the following folder for PortGroup definitions:

${prefix}/var/macports/sources/rsync.macports.org/macports/release/tarballs/ports/_resources/port1.0/group/

or if you prefer directly in GitHub .

A sample listing follows:

%% ls -1 /opt/local/var/macports/sources/rsync.macports.org/macports/release/tarballs/ports/_resources/port1.0/group/

active_variants-1.1.tcl
apache2-1.0.tcl
app-1.0.tcl
archcheck-1.0.tcl
bitbucket-1.0.tcl
cmake-1.0.tcl
cmake-1.1.tcl
compiler_blacklist_versions-1.0.tcl
compilers-1.0.tcl
conflicts_build-1.0.tcl
crossbinutils-1.0.tcl
crossgcc-1.0.tcl
cxx11-1.0.tcl
cxx11-1.1.tcl
debug-1.0.tcl
elisp-1.0.tcl
github-1.0.tcl
...

The requirements of a minimum portfile using a portgroup varies by portgroup. The sections below devoted to each portgroup (or, for portgroups not documented there yet, the comments in the header of the portgroup file itself) should provide guidance on how each portgroup is used. Prospective MacPorts developers are also encouraged to examine existing portfiles that use these portgroups.

The github portgroup allows for efficient porting of software hosted on GitHub.

PortGroup           github 1.0
github.setup        author project version [tag_prefix]

github.setup        author project version v

github.tarball_from releases

distname            ${github.project}-${github.version}

github.tarball_from archive

github.setup        someone someproject 0ff25277c3842598d919cd3c73d60768
version             20140401