Chapter 3. Using MacPorts

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.10.5 installed,
MacPorts base version 2.10.5 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.10.4 installed,
MacPorts base version 2.10.5 downloaded.
---> Updating the ports tree
---> MacPorts base is outdated, installing new version 2.10.5
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 are required by a port at runtime (library and runtime dependencies) or required to install it (build, fetch, and extract 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 two 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.8, “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.