MacPorts Guide

Copyright © 2007–2025 The MacPorts Project

Copyright © 2002–2004 The OpenDarwin Project

2.1.1. Install Xcode on OS X 10.9 or Later

2.1.2. Install Xcode on OS X 10.7 Lion or OS X 10.8 Mountain Lion

2.1.3. Install Xcode on Mac OS X 10.6 Snow Leopard

2.1.4. Install Xcode on Older Releases of Mac OS X

Note

Always make sure to install the latest available version of Xcode for your macOS release; using outdated versions of Xcode may cause port install failures. Also note that Xcode is not updated via OS X's Software Update utility on OS versions prior to 10.6, and is updated via the Mac App Store starting with 10.7.

(Optional) Download the latest version of Xcodefrom the Apple developer website or get itusing the Mac App Store.

A few ports require a full Xcode installation to use, but most don’t (read the description of theuse_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, runxcode-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 fromthe Apple developer website.

Download the latest version of Xcodefrom the Apple developer website or get itusing 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 theApple 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 theApple developer website.

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

2.2.1. macOS Package Install

2.2.2. Source Install

2.2.3. Git Install

2.2.4. Install Multiple MacPorts Copies

The macOS package installer automatically installs MacPorts,sets the shell environment, and runs aselfupdate 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. Theselfupdate 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 setstartupitem_install no in the newmacports.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

2.4.1. Uninstall All Ports

2.4.2. Remove Users and Groups

2.4.3. Remove the Rest of MacPorts

If you want to uninstall MacPorts and theport 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 theport 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, amacports 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 ofmacports.

Individual ports may create users and groups as well; you can remove them with the same commands, but replacingmacports 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 changedprefix,applications_dir orframeworks_dir from their default values, then replace/opt/local with yourprefix, replace/Applications/MacPorts with yourapplications_dir, and/or add yourframeworks_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 toremove themacports 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.

2.5.1. The Postflight Script

2.5.2. Verify the Configuration File

2.5.3. Optional Editor Variables

The postflight script automatically sets thePATH variable, and optionally theMANPATH andDISPLAY variables according to the rules described below. If a current shell configuration file exists at installation time it is renamed to“mpsaved_$timestamp”. Thoseinstalling 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, typeenv in the terminal to verify the current environment settings after the file has been created. Example output forenv is shown below.

MANPATH=TERM_PROGRAM=Apple_TerminalTERM=xterm-colorSHELL=/bin/bashTERM_PROGRAM_VERSION=237USER=joebob__CF_USER_TEXT_ENCODING=0x1FC:0:0PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbinPWD=/Users/joebobEDITOR=/usr/bin/picoSHLVL=1HOME=/Users/joebobLOGNAME=joebobDISPLAY=:0.0SECURITYSESSIONID=b0cea0_=/usr/bin/env

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

MacPorts will checkMP_EDITOR,VISUAL andEDITOR in this order, allowing you to either use a default editor shared with other programs (VISUAL andEDITOR) 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 editorBBEdit (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/viexport MP_EDITOR=/Applications/BBEdit.app/Contents/Helpers/bbedit_tool

3.1.1. port help

3.1.2. port selfupdate

3.1.3. port sync

3.1.4. port diagnose

3.1.5. port reclaim

3.1.6. port list

3.1.7. port search

3.1.8. port info

3.1.9. port deps

3.1.10. port variants

3.1.11. port install

3.1.12. port notes

3.1.13. port clean

3.1.14. port uninstall

3.1.15. port contents

3.1.16. port installed

3.1.17. port outdated

3.1.18. port upgrade

3.1.19. port dependents

3.1.20. port livecheck

3.1.21. port lint

3.1.22. port load

3.1.23. port unload

Thehelp action shows some brief information about the specified action, or if no action is specified, shows basic usage information forport in general.

$port help selfupdate

Usage: selfupdate --no-syncUpgrade 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.

Theselfupdate 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 rsyncMacPorts base version 2.10.5 installed,MacPorts base version 2.10.5 downloaded.---> Updating the ports tree---> MacPorts base is already the latest version

Ifselfupdate 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 rsyncMacPorts 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.5Installing new MacPorts release in /opt/local as root:admin; permissions 755

If theselfupdate 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 yourselfupdate 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 bysudo port -d selfupdate.

selfupdate accepts a single switch:

Thesync action performs a subset ofselfupdate. It synchronizes the ports tree, as doesselfupdate, but it does not check for MacPorts upgrades. On macOS, unless there is a special reason not to do so, runselfupdate instead.

sync does not accept any switches.

Thediagnose 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:

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

Thelist 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 usesearch if you are looking for a specific port.

$port list

Thesearch 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. Runport help search for an exhaustive list of possible switches.

Suppose you are looking for PHP in MacPorts. You might start withport 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 tophp*:

$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 ofport search:

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

php     5.5       lang www    PHP: Hypertext Preprocessorphp4    4.4.9     lang www    PHP: Hypertext Preprocessorphp5    5.3.28    lang www    PHP: Hypertext Preprocessorphp52   5.2.17    lang www    PHP: Hypertext Preprocessorphp53   5.3.28    lang www    PHP: Hypertext Preprocessorphp54   5.4.31    lang www    PHP: Hypertext Preprocessorphp55   5.5.15    lang www    PHP: Hypertext Preprocessorphp56   5.6.0RC2  lang www    PHP: Hypertext Preprocessor

Let us look at another example that is less complicated. Assuming you are looking forrrdtool, 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 RRDToolnetmrg @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 extensionphp5-rrd @1.1.3 (php, net, devel)    PHP rrdtool extensionphp5-rrdtool @1.0.5 (php, net, devel)    this port is only a stub and has been made obsolete by php5-rrdphp53-rrd @1.1.3 (php, net, devel)    PHP rrdtool extensionphp54-rrd @1.1.3 (php, net, devel)    PHP rrdtool extensionphp55-rrd @1.1.3 (php, net, devel)    PHP rrdtool extensionrrdtool @1.4.7_5 (net)    Round Robin DatabaseFound 11 ports.

The possible switches tosearch and their meaning are:

Theinfo 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:             universalDescription:          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-pamBuild Dependencies:   pkgconfig, autoconf, automake, libtoolLibrary Dependencies: ykpers, yubico-c-clientPlatforms:            darwinLicense:              BSDMaintainers:          cal@macports.org

Thedeps 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+preforkmpmLibrary 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 ofapache2 adds a dependency onopenldap:

$port deps apache2 +openldap

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

deps accepts two switches:

Thevariants 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. SeeInvoking 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 thePortfile. While() are derived from thevariants.conf. SeeSection 6.2.3, “variants.conf” for more information onvariants.conf.

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

$sudo port install apache2 -preforkmpm +workermpm

installs theapache2 port without thepreforkmpm, but with theworkermpm 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 inmain.log for the port you installed. Its path will be printed automatically if the installation fails. You can manually get the path usingport 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 cleanportname

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 installportname

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

$sudo port destroot apache2

install takes the following switches:

Thenotes 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 actionclean deletes intermediate files created by MacPorts while installing a port. Aport clean is often necessary when builds fail and should be the first thing to try after a failed installation attempt.

$sudo port cleanportname

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

$sudo port clean --distportname

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

clean accepts the following options:

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

$sudo port uninstallportname

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_0Error: 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 theleaves pseudo-port, e.g., usingsudo port uninstall leaves.

uninstall supports the following switches:

Thecontents action displays a list of all files that have been installed by a given port. You can only usecontents 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 forcontents are finding the location of a port's executable after installing it. The following line is usually helpful in this case:

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

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

contents accepts:

Theinstalled 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'

Theoutdated 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 usingselfupdate (orsync).

$port outdated

The following installed ports are outdated:gnupg                          1.4.16_0 < 1.4.18_0gnupg2                         2.0.22_2 < 2.0.25_0gpg-agent                      2.0.22_1 < 2.0.25_0gpgme                          1.5.0_0 < 1.5.1_0HexFiend                       2.1.2_1 < 2.3.0_0libksba                        1.0.8_0 < 1.3.0_0p5.16-class-methodmaker        2.180.0_1 < 2.210.0_0p5.16-gnupg-interface          0.330.0_3 < 0.500.0_1p5.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.

Theupgrade 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 installedportname

$sudo port activateportname @old-version

$sudo port -u upgrade outdated

$sudo port uninstall inactive

upgrade accepts a number of switches:

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

$port dependents openssl

apache2 depends on opensslcurl depends on opensslcyrus-sasl2 depends on opensslgit depends on opensslkerberos5 depends on openssllftp depends on openssllibssh depends on opensslmosh depends on opensslopenldap depends on opensslp5.16-net-ssleay depends on opensslpython27 depends on opensslpython32 depends on opensslqt4-mac depends on opensslruby19 depends on opensslserf1 depends on openssltextmate2 depends on opensslwireshark depends on openssl

Note thatdependents 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.

Thelivecheck 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. SeeSection 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 thePortfile conforms to the MacPorts standards specified inPortfile Development. You should use this if you modified aPortfile before submitting patches back to MacPorts.

If aPortfile 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 abiwordWarning: Variant use_binary does not have a descriptionWarning: Variant use_source does not have a descriptionWarning: 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) intolaunchd. These files will allowlaunchd to start and manage the port's daemon processes.

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

$sudo port load prometheus

--->  Loading startupitem 'prometheus' for prometheus

Now the port's service(s) should be running inlaunchd. This can be verified with thelaunchctl command:

$sudo launchctl list | grep macports

49119   0       org.macports.prometheus

To stop the daemon service and mark it as disabled forlaunchd, use theport unload command.

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

Theunload 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 inlaunchctl list.

3.2.1. Invoking Variants

3.2.2. Negating Default Variants

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 useport 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 thoughapache2 does not have a+mariadb variant. However, it depends on theapr-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.

APortfile 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 thePortfile, or by your configuration invariants.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

3.3.1. Updating Your Ports Tree

3.3.2. Show Ports Which Need Updating

3.3.3. Upgrading Outdated Ports

3.3.4. Removing Inactive Version(s) of Upgraded Port(s)

3.3.5. Finding Ports Depending on a Certain Port

3.3.6. Finding Leaves

3.3.7. Keep Your Installation Lean by Defining Leaves as Requested Ports

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, useselfupdate:

$sudo port selfupdate

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

To see what's new after runningselfupdate, you can useport outdated to generate a list of ports that have newer versions available. This can help in estimating the time required forsudo 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_0gnupg2                         2.0.22_2 < 2.0.25_0gpg-agent                      2.0.22_1 < 2.0.25_0gpgme                          1.5.0_0 < 1.5.1_0HexFiend                       2.1.2_1 < 2.3.0_0libksba                        1.0.8_0 < 1.3.0_0p5.16-class-methodmaker        2.180.0_1 < 2.210.0_0p5.16-gnupg-interface          0.330.0_3 < 0.500.0_1p5.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 http://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. Donot 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 notportname

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 accuratedependents:

$port dependentsportname

gnupg2 depends on libksbagpg-agent depends on libksba

MacPorts also has a recursive version of thedependents action calledrdependents:

$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 theleaves pseudo-port, for example in conjunction with theecho orinstalled action.

$port echo leaves

git-flow                       @0.4.1_2gmake                          @4.0_0gpgme                          @1.5.1_0hs-download-curl               @0.1.4_0pkgconfig                      @0.28_0py27-docutils                  @0.12_0python32                       @3.2.5_0texi2html                      @5.0_1yasm                           @1.2.0_0

These leaves may be wanted, but are in most cases unneeded. SeeSection 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 therleaves 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 theport_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_2gmake                          @4.0_0gpgme                          @1.5.1_0hs-download-curl               @0.1.4_0pkgconfig                      @0.28_0py27-docutils                  @0.12_0python32                       @3.2.5_0texi2html                      @5.0_1yasm                           @1.2.0_0

Now it is up to the user to decide what's needed and what is not. We've noticedpkgconfig 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, andyasm are only needed to updatemplayer2, 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 keeppkgconfig, 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 theport_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 gpgmeThe 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_0Search 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-romanThe following ports were uninstalled:  py27-roman @2.0.0_0Search for new leaves?  [no] / (y)es: yThere 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 unsetrequestedportname

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

3.4.1. Binary Archives

3.4.2. Binary Packages

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 topackages.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 ./+COMMENTa ./+CONTENTSa ./+DESCa ./+PORTFILEa ./+STATEa ./opta ./opt/locala ./opt/local/etca ./opt/local/sbina ./opt/local/sharea ./opt/local/vara ./opt/local/var/runa ./opt/local/var/run/logrotatea ./opt/local/var/run/logrotate/.turd_logrotatea ./opt/local/share/logrotatea ./opt/local/share/mana ./opt/local/share/man/man5a ./opt/local/share/man/man8a ./opt/local/share/man/man8/logrotate.8.gza ./opt/local/share/man/man5/logrotate.conf.5.gza ./opt/local/share/logrotate/CHANGESa ./opt/local/share/logrotate/COPYINGa ./opt/local/share/logrotate/logrotate.conf.examplea ./opt/local/share/logrotate/org.macports.logrotate.plist.examplea ./opt/local/sbin/logrotatea ./opt/local/etc/logrotate.da ./opt/local/etc/logrotate.d/.turd_logrotateDEBUG: 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 inmacports.conf using theportarchivetype key. The default format istbz2; other options are:tar,tbz,tbz2,tgz,tlz,txz,xar,zip,cpgz, andcpio.

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 usingport as shown in the following examples.

Create a macOS.pkg installer for thepstree 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 workportname

• Fetch

• Extract

• Patch

• Configure

• Build

• Destroot

Note

For a detailed description of all port phases, see thePortfile Reference chapter.

1. Modeline

   This should be the first line of a Portfile. It sets the correct editing options for vim and emacs. SeePort Style for more information. Its use is optional and up to the port maintainer.

   # -*- 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

2. PortSystem line

   This statement is required for all ports.

   PortSystem          1.0

3. Port name

   name                rrdtool

4. Port version

   version             1.2.23

5. Port categories

   A port may belong to more than one category, but the first (primary) category should match the directory name in the ports tree where the Portfile is to reside.

   categories          net

6. Platform statement

   platforms           darwin

7. Port maintainers

   A port's maintainers are the people who have agreed to take responsibility for keeping the port up-to-date. Themaintainers keyword lists the maintainers' GitHub usernames or email addresses, preferably in the obfuscated form which hides them from spambots. For more, see the full explanation of themaintainers keyword in theGlobal Keywords section of thePortfile Reference chapter.

   maintainers         @neverpanic \                    jdoe \                    example.org:julesverne

8. Port description

   description         Round Robin Database

9. Port long_description

   long_description    RRDtool is a system to store and display time-series \                    data

10. A port's application homepage

    homepage            https://people.ee.ethz.ch/~oetiker/webtools/rrdtool/

11. A port's download URLs

    master_sites        https://oss.oetiker.ch/rrdtool/pub/ \                    ftp://ftp.pucpr.br/rrdtool/

12. Port checksums

    The checksums specified in a Portfile are checked with the fetched tarball for security. For the best security, use rmd160 and sha256 checksum types. Checksums should also include the target file's size.

    checksums               rmd160  7bbfce4fecc2a8e1ca081169e70c1a298ab1b75a \                        sha256  2829fcb7393bac85925090b286b1f9c3cd3fbbf8e7f35796ef4131322509aa53 \                        size    1061530

    To find the correct checksums for a port's distribution file, follow one of these examples:

    %%openssl dgst -rmd160 rrdtool-1.2.23.tar.gz%%openssl dgst -sha256 rrdtool-1.2.23.tar.gz

    RIPEMD160( ... rrdtool-1.2.23.tar.gz)= 7bbfce4fecc2a8e1ca081169e70c1a298ab1b75aSHA256( ... rrdtool-1.2.23.tar.gz)= 2829fcb7393bac85925090b286b1f9c3cd3fbbf8e7f35796ef4131322509aa53

    or update the version in the Portfile:

    %%sudo port edit rrdtool

    and run:

    %%port -v checksum rrdtool

    --->  Fetching distfiles for rrdtool--->  Verifying checksums for rrdtool--->  Checksumming rrdtool-1.2.23.tar.gzError: Checksum (rmd160) mismatch for rrdtool-1.2.23.tar.gzPortfile checksum: rrdtool-1.2.23.tar.gz rmd160 ...WRONGCHECKSUM...Distfile checksum: rrdtool-1.2.23.tar.gz rmd160 7bbfce4fecc2a8e1ca081169e70c1a298ab1b75aError: Checksum (sha256) mismatch for rrdtool-1.2.23.tar.gzPortfile checksum: rrdtool-1.2.23.tar.gz sha256 ...WRONGCHECKSUM...Distfile checksum: rrdtool-1.2.23.tar.gz sha256 2829fcb7393bac85925090b286b1f9c3cd3fbbf8e7f35796ef4131322509aa53The correct checksum line may be:checksums           rmd160  7bbfce4fecc2a8e1ca081169e70c1a298ab1b75a \                    sha256  2829fcb7393bac85925090b286b1f9c3cd3fbbf8e7f35796ef4131322509aa5Error: Failed to checksum rrdtool: Unable to verify file checksumsError: See ...SOMEPATH.../rrdtool/main.log for details.Error: Follow https://guide.macports.org/#project.tickets to report a bug.Error: Processing of port rrdtool failed

13. Port dependencies

    A port's dependencies are ports that must be installed before another port is installed.

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

14. Port configure arguments (optional)

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

4.3.1. A Basic Portfile

4.3.2. Augment Phases Using pre- / post-

4.3.3. Overriding Phases

4.3.4. Eliminating Phases

4.3.5. Creating a StartupItem

# -*- 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=4PortSystem          1.0name                rrdtoolversion             1.2.23categories          netplatforms           darwinlicense             GPL-2+maintainers         julesvernedescription         Round Robin Databaselong_description    RRDtool is a system to store and display time-series datahomepage            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    1061530depends_lib         path:bin/perl:perl5 \                    port:tcl \                    port:zlibconfigure.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      yesstartupitem.name        nmicmpdstartupitem.executable  "${prefix}/bin/nmicmpd"

4.4.1. Example Variants

4.4.2. Variant Actions in a Phase

4.4.3. Default Variants

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

4.5.1. Subport Declarations

4.5.2. Subport Examples

4.5.3. Subport Tips

subportnamebody

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

For example, if a Portfile contains:

Portfile                   1.0name                       exampledepends_lib                aaaconfigure.args             --bbbsubport 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.0name                       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                   exampledepends_lib                aaaconfigure.args             --bbb

Portfile                   1.0name                       example# Value for 'subport' shown here for illustration purposes only; see note above.#subport                   example-sub1depends_lib                aaadepends_lib-append         cccconfigure.args             --ddd

Portfile                   1.0name                       example# Value for 'subport' shown here for illustration purposes only; see note above.#subport                   example-sub2depends_lib                aaadepends_lib-append         eeeconfigure.args             --bbbconfigure.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.

4.6.1. Creating Portfile Patches

4.6.2. Creating Source Code Patches

4.6.3. Manually Applying Patches

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 theidentifier is a reference to the problem or bug it is supposed to solve. An example filename would bedestdir-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.

1. Opensources.conf in a text editor. For example, to open it into TextEdit:

   %%open -e ${prefix}/etc/macports/sources.conf

2. Insert a URL pointing to your local repository location before the rsync URL as shown.

   file:///Users/julesverne/portsrsync://rsync.macports.org/macports/release/tarballs/ports.tar [default]

   Note

   The file URL should always appear before the rsync URL so that local Portfiles can be tested that are duplicated in the MacPorts tree, becauseport will always operate on the first Portfile it encounters.

3. Place the Portfiles you create inside a directory whose name matches the port, which should in turn be placed inside a directory that reflects the port's primary category (the first category entry in the Portfile). For example, to create the directory for a hypothetical port“bestevergame” and to begin editing its Portfile in TextEdit, you can use these commands:

   %%mkdir -p ~/ports/games/bestevergame%%cd ~/ports/games/bestevergame%%touch Portfile%%open -e Portfile

   See other sections in the Guide for help writing Portfiles. If you've already written the Portfile elsewhere, you can instead copy the Portfile into this directory.

4. If your Portfile needs to apply any patches to the port's source files, create afiles directory and place the patchfiles in it, and reference the patchfiles in your Portfile, as explained inCreating Source Code Patches.

5. After you create or update your Portfile, useportindex in the local repository's directory to create or update the index of the ports in your local repository.

   %%cd ~/ports%%portindex

   Creating software index in /Users/julesverne/portsAdding port games/bestevergameTotal number of ports parsed:   1Ports successfully parsed:      1Ports failed:                   0

4.8.1. Port Style

4.8.2. Don't Overwrite Config Files

4.8.3. Install Docs and Examples

4.8.4. Provide User Messages

4.8.5. Use Variables

4.8.6. Renaming or replacing a port

4.8.7. Removing a port

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, multiplemaster_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 asreplaced_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=4PortSystem          1.0PortGroup           kde4    1.1fetch.type          svnsvn.url             svn://anonsvn.kde.org/home/kde/trunk/extragear/office/skroogesvn.revision        1215845name                skrooge-develversion             0.8.0-${svn.revision}categories          kde financemaintainers         mk pixilla openmaintainerdescription         Skroogelong_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           skroogeplatforms           darwinlicense             GPL-3homepage            https://skrooge.orgmaster_sites        https://skrooge.org/files/livecheck.type      nonedistname            skroogedepends_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=4PortSystem          1.0name                skrooge-develsvn.revision        1215845version             0.8.0-${svn.revision}revision            1replaced_by         skroogecategories          kde financemaintainers         mk pixilla openmaintainerdescription         Skroogelong_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           darwinlicense             GPL-3homepage            https://skrooge.orglivecheck.type      nonepre-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-develError: 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.logError: 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=4PortSystem          1.0PortGroup           obsolete 1.0name                skrooge-develreplaced_by         skroogesvn.revision        1215845version             0.8.0-${svn.revision}revision            2categories          kde finance

If a port has to be removed from MacPorts one should consider the hints concerning replacing it by some alternative port givenabove. 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.

PortSystem

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

PortSystem          1.0

name

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

name                foo

version

The version of the software. Version numbers are often dotted decimals, though some projects may use other formats.

The version keyword should adhere as closely as possible to the format used by the upstream project (e.g., as reported by a program's-v or--version flag or on the project's web site), omitting any precedingv or other extraneous characters that are not part of the version number. Especially, the version should not be misformatted merely to accommodate an unusual distfile name. For example, if the distfile name isfoo-v1_2_3.tar.gz and the project reports its version asv1.2.3, the version keyword should be set to1.2.3 and distname should be overridden as needed (ideally by transforming the version using a procedure such asstring map).

When updating the version of a port that installs a dynamic library, check (by examining the second line of output from theotool -L command run on the library before and after upgrading) whether its install name has changed. If it has, increase the revision of every port that links with the library to rebuild it with the new library.

version             1.23.45

revision

An optional integer (the default is0) that is incremented when a port is updated independently of the version of the software. The revision line usually follows the version line.

In Portfiles that have subports, it is often appropriate for each subport (including the main port) to have a separate revision line. (This does not usually apply to Portfiles for Perl, PHP, Python, or Ruby modules which create numerous similar subports for the same version of the software.)

It is recommended to set the revision in all ports, even if the revision is 0. This makes it easier for other developers to see where to increase the revision in your port, should that need arise. This is especially helpful for Portfiles that have subports.

When increasing the revision in a Portfile with subports, consider carefully which of the subports (possibly including the main port) need to have their revisions increased.

When increasing the revision in a Portfile that does not have any revision lines yet, take a moment to check if the Portfile has subports.

Just like when a port's version increases, a port is considered outdated when its revision increases. To avoid causing users to rebuild ports unnecessarily, don't increase the revision unless doing so would result in a change for users who already have the ports installed.

Some examples of situations in which a port's revision should usually be increased:

• changing configure arguments or build flags or any other change that will cause the installed files to be different

• installing additional files, such as documentation, or removing any files which had previously been installed

• changing the names or locations of any installed files

• adding a dependency that causes the installed files to be different

• a library dependency's install_name has changed

• removing a variant that a user might have installed

• adding a variant name to default_variants

Some examples of situations in which a port's revision should not usually be increased:

• fixing a build failure

• adding a dependency to depends_fetch, depends_extract, depends_patch, depends_build, or depends_test

• adding a direct dependency on a port that was already an indirect dependency

• changing a dependency's type, e.g. from depends_lib to depends_build

• removing a dependency that is not used

• setting or changing the port's license

• adding a new non-default variant

• removing a variant name from default_variants

• changing comments or whitespace in the Portfile

• any other change to the Portfile that does not change the files it installs

revision            1

epoch

An optional integer (the default is0) that must be increased when a port is updated to a version that appears (according to thevercmp procedure's version number comparison algorithm) to be less than the previous version. For example, updating from2.0-rc1 to2.0, or from1.10 to1.2, or from20070928 to1.0.

The purpose of increasing the epoch is to cause MacPorts to consider a port to be outdated, even if that wouldn't otherwise be the case due to the specific version numbers. Don't set the epoch unless it's required. In most ports, the version number advances according to the normal dotted-decimal sequence, so most ports will never have a need to set the epoch.

Some Portfile authors have used large epoch values that look like dates in YYYYMMDD format (e.g.,20091231). When it is necessary to increase the epoch in such ports, the new epoch can be set to the current date. It is not recommended to use this format when adding an epoch to a port that does not already have one; instead, just set the epoch to1, and when needing to increase an existing small epoch, increase it by 1.

epoch               1

Note

A port's epoch can never be decreased. Removing the epoch from the port would decrease it to its default value of0, so once added to a port the epoch can also never be removed. When adding an epoch, take extra care to ensure that it is necessary, since a mistakenly added epoch cannot be undone. In Portfiles that have subports with different software versions, consider whether the epoch needs to be increased in all subports or only in some of them.

categories

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

categories          net security

maintainers

A port's maintainers are the people who have agreed to take responsibility for keeping the port up-to-date. Most ports have only a single maintainer, but some ports have two or more co-maintainers. Themaintainers keyword lists the maintainers' GitHub usernames or email addresses. GitHub usernames start with an@ symbol. Email addresses are preferably listed in the obfuscated form below to hide them from spambots:

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

• For addresses in other domains, e.g.,<account@example.org>, use the conventionexample.org:account to specify the address.

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

maintainers         @neverpanic \                    jdoe \                    example.org:julesverne

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

maintainers         {@jverne example.org:julesverne}

Note

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

description

A short sentence fragment describing the software.

description         a classic shooter arcade game

long_description

One or more sentences describing the software.

The long description can be based on a description provided by the upstream project (e.g., in its readme or on its web site) but avoid repeating information already present elsewhere in the Portfile, such as the software's license (see thelicense keyword) or the platforms on which it runs (see theplatforms keyword), and avoid including information irrelevant to a MacPorts user, such as compilation instructions or other steps the Portfile has already performed for the user. More specific usage instructions are best left to thenotes keyword.

If a port provides a program that is different from the port name, it can be a good idea to include the program name in the long description so that a user could find it by searching.

Long descriptions are usually a single paragraph. MacPorts will word-wrap long lines to the terminal width as needed. Break long lines with escaped newlines for better legibility within the Portfile. If literal newlines need to be displayed to the user, they can be inserted using\n. Place the\n at the beginning of the next line, not at the end of the previous line. To create a new paragraph, insert two newlines.

Sometimes the port's name and short description are reused as part of the long description. When referencing thedescription keyword (or any other list keyword with more than one item), it should be preceded with the expand operator.

long_description    ${name} is {*}${description} derived from \                    the game alien-munchers.  Not suitable for \                    children under two years old.

long_description    foobar provides the following programs: \                    \n \                    \n* foo, a lorem ipsum utility \                    \n* bar, a high-performance amet consectetur \                    \n* baz, an eiusmod tempor converter

homepage

The software's primary web site.

Usually the homepage should be a URL that does not redirect to another URL. For example, if an http URL redirects to an https URL, list the https URL. Or if a URL without a trailing slash redirects to the URL with the trailing slash, list the URL with the trailing slash. If the project advertises a short URL that redirects to a longer URL, it is acceptable to list the short URL despite the redirect.

When the homepage is just a hostname with no path component, don't include a trailing slash.

homepage            https://www.example.org/apps/

homepage            https://www.example.com

platforms

A list of the platforms on which the port is expected to work. Defaults todarwin if not set. Consists of a list of platform specifiers, each of which is at minimum a platform name and may also include version information. Possible platform names are:

• darwin (equivalent to specifying bothmacosx andpuredarwin)

• macosx (macOS as distributed by Apple)

• puredarwin (the open-source Darwin OS without Apple's proprietary components)

• freebsd

• linux

• netbsd

• openbsd

• solaris

• sunos

A platform specifier that is just a platform name is purely informational for users; it is displayed in the output ofport info but has no other effect. Ports for software that does not require macOS-specific features can generally use the default value ofdarwin. Most ports use this value on the presumption that they would work on Pure Darwin, even if that has not been attempted. Ports for software that is known to require macOS-specific features should usemacosx. Including the xcode portgroup will change the default tomacosx automatically.

See alsoos.platform.

platforms           macosx freebsd

(Added: MacPorts 2.8.0) A platform specifier can also be a list, where the first element is a platform name and subsequent elements are pairs of comparison operators and versions. This indicates the version ranges of each platform that the port works on.

If a platform specifier's name matches${os.platform}, then each comparison operator in the specifier is applied to${os.version} as the left operand and the listed version as the right operand. If any of the comparisons evaluate to false, then the default value ofknown_fail is changed toyes.

Possible operators are:<,<=,>,>=,==,!=. The== and!= operators support globbing. The rest of the operators compare as per thevercmp command.

Examples:

A port that works on Darwin 12 and later:

platforms           {darwin >= 12}

A port that works on Darwin versions between 10 and 19 inclusive:

platforms           {darwin >= 10 < 20}

A port that works on Darwin versions between 10 and 19 but not version 12.x:

platforms           {darwin >= 10 != 12.* < 20}

The special valueany can also be used to indicate that a port will install identical files across platforms or platform versions. This can help to reduce the number of binary archives that have to be built. In most cases, this is only applicable to ports that don't install any architecture-specific files.

Ports that install identical files on any platform should use:

platforms           any

Ports that install identical files on any Darwin version, but may install different files on other platforms (or don't work on other platforms), should use:

platforms           {darwin any}

It is possible to combineany with version ranges. A port that only works on Darwin 17 or later and installs identical files regardless of the Darwin version would do this:

platforms           {darwin any >= 17}

supported_archs

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

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

supported_archs     i386 ppc

supported_archs     noarch

license

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

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

license             GPL-3

license             {freetype GPL}

license_noconflict

By default, it is assumed that ports may use libraries or headers from their dependencies and thus form a derivative work. A dependency with an incompatible license thus prevents the port from being distributed in binary form. If a dependency with an incompatible license is not used in such a way that a derivative work is formed, or should not prevent binary distribution for any other reason, add its name to this list.

license_noconflict  openssl

license_noconflict  readline gdbm

use_xcode

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

use_xcode           no

use_xcode           yes

known_fail

Setting this option toyes indicates that the port is known not to work. Users will be told this and asked for confirmation if they attempt to install it, and the Buildbot and GitHub Actions will not attempt to build it.

Don't set this option conditionally on the basis of anything that can change dynamically, such as$build_arch or$xcodeversion, since it will be recorded in the static PortIndex. If a port works only on certain OS versions, use theplatforms option to indicate this rather than settingknown_fail directly.

known_fail           yes

macosx_deployment_target

The macOS release to target.

During the configure phase, environment variableMACOSX_DEPLOYMENT_TARGET is set to the specified value.

This option is also used when building binary packages, viaport pkg,port mpkg,port dmg, andport mdmg. Specifically, MacPorts will create a package/DMG that is compatible with the desired macOS release. In addition, it is used to set version-related metadata for the Apple installer package, includingallowed-os-versions.

macosx_deployment_target 10.8

installs_libs

By default, it is assumed that ports may install libraries or headers that can be incorporated into their dependents. If this is not the case, setinstalls_libs tono. This means that this port's dependents need not check that it is installed for the same architectures as them; that it is permissible to distribute binaries of the dependents even if their licenses conflict with the license of this port; and that updates to this port can never result in broken dynamic linking in its dependents.

installs_libs        no

add_users

Consists of a list of usernames and settings. At appropriate times during the port installation process, a user will be created for each username with the corresponding settings.

Settings are of the formname=value. A setting applies to the username that appeared most recently before it in the list.

Applicable options are:group,gid (may be used instead ofgroup),passwd,realname,home, andshell.

add_users           squid \                    group=squid \                    realname=Squid\ Proxy \                    home=${prefix}/var/squid

add_users           user1 group=mygroup \                    user2 group=mygroup

prefix

Installation prefix, set at compile time and displayed in${prefix}/etc/macports/macports.conf —- may be overridden on a per-port basis, for example to install into a wholly-contained subdirectory of ${prefix}, but most ports should have no reason to do so.

Default:/opt/local

libpath

Path to the MacPorts Tcl libraries.

portpath

Full path to the Portfile of the port being executed. Portfile repositories are defined in the filesources.conf.

Default:${prefix}/var/macports/sources/rsync.macports.org/macports/release/tarballs/ports/<category>/<portname>/

filesdir

Path to files directory relative to${portpath}.

Value:files

filespath

Full path to files directory.

Value:${portpath}/${filesdir}

workpath

Full path to work directory.

Value:${portbuildpath}/work

worksrcpath

Full path to extracted source code.

Value:${workpath}/${worksrcdir}

destroot

Full path into which software will be destrooted.

Value:${workpath}/destroot

distpath

Location to store downloaded distfiles.

Value:${portdbpath}/distfiles/${dist_subdir}

install.user

The Unix user at the time of port installation.

install.group

The Unix group at the time of port installation.

os.platform

The underlying operating system platform (e.g.,“darwin” on macOS,“freebsd”, etc.).

os.arch

The hardware architecture -- either“powerpc”,“i386”, or“arm”.

os.version

The version number of the host operating system (e.g.,“12.3.0” for Darwin 12.3.0 a.k.a. OS X 10.8.3).

os.endian

Endianness of the processor -- either“big” (on PowerPC systems) or“little” (on Intel and Apple Silicon systems).

os.major

The major version number of the host operating system (e.g.,“12” for Darwin 12.x).

macos_version

The full macOS version number of the host operating system, if applicable (e.g.,“10.15.7”).

macos_version_major

The major macOS version number of the host operating system, if applicable (e.g.,“12” for Monterey or“10.15” for Catalina).

xcodeversion

The installed version of Xcode, if any (e.g.,“14.0.1”).

xcodecltversion

(Added: MacPorts 2.8) The installed version of the Command Line Tools for Xcode, if any (e.g.,“14.0.0.0.1.1661618636”).

universal_possible

Boolean value indicating whether it is possible to build universal binaries given the configured SDK and universal_archs and the port's supported_archs.

5.3.1. Introduction

5.3.2. Installation Phase Keywords

5.3.3. Fetch Phase Keywords

5.3.4. Checksum Phase Keywords

5.3.5. Extract Phase Keywords

5.3.6. Patch Phase Keywords

5.3.7. Configure Phase Keywords

5.3.8. Build Phase Keywords

5.3.9. Test Phase Keywords

5.3.10. Destroot Phase Keywords

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 standardconfigure,make, andmake install steps. For applications that do not conform to this standard, installation phases may be declared in a Portfile toaugment oroverride the default behavior as described in thePortfile 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 theyrefer 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 defaultconfigure.cflags so you should always useconfigure.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.

5.4.1. Port and File Dependencies

depends_fetch,depends_fetch-append,depends_fetch-delete

The list of dependencies to check before phasesfetch,checksum,extract,patch,configure,build,destroot,install, andpackage. Fetch dependencies are needed to download the distfiles for a port, and are not needed at all once the software is installed.

depends_extract,depends_extract-append,depends_extract-delete

The list of dependencies to check before phasesextract,patch,configure,build,destroot,install, andpackage. Extract dependencies are needed to unpack a port's distfiles into the work directory, and are not needed at all once the software is installed.

depends_build,depends_build-append,depends_build-delete

The list of dependencies to check before phasesconfigure,build,destroot,install, andpackage. Build dependencies are needed when software is being built, but not needed at all once it is installed.

depends_lib,depends_lib-append,depends_lib-delete

The list of dependencies to check before phasesconfigure,build,destroot,install, andpackage. Library dependencies are needed both at build time (for headers and libraries to link against) and at run time.

depends_test,depends_test-append,depends_test-delete

The list of dependencies to check before phasetest. Test dependencies are only needed when the port enables testing (i.e.test.run yes).

depends_run,depends_run-append,depends_run-delete

The list of dependencies to check before phasesdestroot,install, andpackage. Run dependencies are needed when the software is run, but not to compile it.

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:apache2depends_build       port:libtooldepends_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, andpath for any installed file. File dependencies are specified in the form:<type>:<filespec>:<port>.

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

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

Forpath 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}. Sincepath 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 ofbin andlib 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:xorgdepends_build       bin:glibtool:libtooldepends_run         path:lib/libltdl.a:libtool

5.5.1. User-Selected Variants

5.5.2. User-Selected Variant Descriptions

5.5.3. Platform Variants

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 keyworddefault_variants (see below).

User-selected variants ought to provide a description, which will be displayed when using commandport 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.

subport name body

Example:

Portfile                   1.0name                       exampledepends_lib                aaaconfigure.args             --bbbsubport example-sub1 {    depends_lib-append     ccc    configure.args         --ddd}subport example-sub2 {    depends_lib-append     eee    configure.args-append  --fff}

Note

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.

file

The standard Tclfile command can be used for a number of operations on files, such as moving, renaming, deleting, or creating directories, among others. For a complete list, consult theTcl reference manual for thefile command, or the Tcl file manpage in then section of manpages on your machine usingman n file

file copy

Copy a file.

file rename

Rename a file.

file delete [-force]

Remove a file or (with-force) a directory and its contents.

file mkdir

Create a directory.

macros

For the above operations provided by Tcl'sfile command, MacPorts provides the following shorthands. These should be used in preference to the Tcl commands above, as they may work around certain bugs.

copy

Shorthand forfile copy.

move

Similar tofile rename but correctly handles renames that only change the case of a file on a case-insensitive filesystem.

delete

Shorthand forfile delete -force.

touch

Mimics the BSD touch command.

ln

Mimics the BSD ln command.

xinstall

xinstall copies files and creates directories; it is intended to be compatible with install(1).

xinstall [-oowner] [-ggroup] [-mmode] [file1 file2 ...]directory

Install the specified file(s) to a destination directory.

xinstall [-oowner] [-ggroup] [-mmode] [-Wdir] [file1 file2 ...]directory

Change todir and install file(s) to a destination directory.

xinstall [-oowner] [-ggroup] [-mmode] {*}[globpattern]directory

Install the file(s) matching the glob pattern to a destination directory. Note the use of the{*} operator to convert the list returned byglob into separate arguments toxinstall.

xinstall -d [-oowner] [-ggroup] [-mmode]directory

Create a directory including parent directories if necessary.

Defaults:

• owner -

• group -

• mode -0755

Examples:

xinstall -m 640 ${worksrcpath}/README \   ${destroot}${prefix}/share/doc/${name}

xinstall -m 640 -W ${worksrcpath}/doc README INSTALL COPY \   ${destroot}${prefix}/share/doc/${name}

xinstall -m 640 {*}[glob ${worksrcpath}/doc/*] \   ${destroot}${prefix}/share/doc/${name}

xinstall -d ${destroot}${prefix}/share/doc/${name}

strsed

strsed can be used for string manipulations using regular expressions. It supports a small subset of the commands known from sed(1).

strsedstring s/regex/replacement/

Replaces the first instance ofregex withreplacement. Refer to re_format(7) for a definition of regular expression syntax.

strsedstring g/regex/replacement/

The same as the previous format, except all instances of the pattern will be replaced, not only the first (mnemonic: 'g' is for global).

reinplace

Allows text specified by a regular expression to be replaced by new text, in-place (the file will be updated itself, no need to place output into a new file and rename).

reinplace [-localelocale] [-n] [-Wdir] [--]commandfile [file2 ...]

Replace text given by the regular expression portion of the command with the replacement text, in all files specified.

Use -locale to set the locale. The default locale isen_US.UTF-8. For example,-locale C will allow a non-UTF-8 file to be modified (which may otherwise give the error "sed: RE error: illegal byte sequence"), but only operating on ASCII characters. If you need it to work on non-ASCII characters you need to set a locale with the correct charset for the file, e.g. "en_US.ISO8859-1".

-n is passed to sed to suppress echoing result

-W to set a common working directory for multiple files

Use -E to use the extended regular expression style (see re_format(7) for a description of the basic and extended styles)

Use -- to end option processing and allow any further dashes not to be treated as options.

Examples:

reinplace -W ${worksrcpath} "s|/usr/local|${prefix}|g" configure setup.py

reinplace "s|@@PREFIX@@|${prefix}|g" ${worksrcpath}/Makefile

user/group

adduser username [uxml:id=uid] [gxml:id=gid] [passwd=passwd] [realname=realname] [home=home] [shell=shell]

Add a new local user to the system with the specified uid, gid, password, real name, home directory and login shell.

existsuserusername

Check if a local user exists. Returns the uid for the given user, or 0 if the user wasn't found. Checking for the root user is not supported because its uid is 0, and it will always exist anyway.

nextuid

Returns the highest used uid plus one.

addgroupgroup [gxml:id=gid] [passwd=passwd] [realname=realname] [users=users]

Add a new local group to the system, with the specified gid, password, real name, and with a list of users as members.

existsgroupgroup

Check if a local group exists and return the corresponding gid. This can be used with adduser:

addgroup fooadduser foo gxml:id=[existsgroup foo]

nextgid

Returns the highest used gid plus one.

External program execution

Use only when ....

5.8.1. StartupItem Attributes

5.8.2. Executable StartupItems

5.8.3. Script StartupItems

5.8.4. Loading / Unloading StartupItems into launchd

5.8.5. StartupItem Internals

Note

The variablestartupitem_type in${prefix}/etc/macports/macports.conf may be set tonone to override the default value of thestartupitem.type option in Portfiles; this prevents StartupItems from being created.

Additionally, thestartupitem_install variable can be set tono inmacports.conf to override the default value of thestartupitem.install option, which will prevent links from being created under/Library. This is useful for MacPorts installations that are not used with root privileges.

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 becausedaemondo launches the daemondirectly, rather thanindirectly 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 scriptitself 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 fordaemondo 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/shcase "$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 intolaunchd 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 fromlaunchd 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 isorg.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# StartStart(){    /opt/local/share/mysql5/mysql/mysql.server start}# StopStop(){    /opt/local/share/mysql5/mysql/mysql.server stop}[... trimmed ...]

livecheck.type

Specify what kind of update check to perform.

Open source mirror site options are to use the project's latest file release fromsourceforge or the project'sdate_updated XML tag forfreecode. These options are automatically used if a matching${master_sites} URL is used.

Generic download site options are to specify amoddate (modification date of a URL resource), aregex (retrieve the version by applying a regex to a URL resource),regexm (retrieve the version by applying a multi-line regex to a URL resource),md5 (compares the md5 sum of a URL resource) ornone (no check).

• Default:sourceforge orgooglecode if the${master_sites} is one of these, elsefreecode.

• Values:freecodesourceforgegooglecodemoddateregexregexmmd5none

• Examples:

  livecheck.type      regexlivecheck.url       ${homepage}livecheck.regex     "Generally Available (\\d+(?:\\.\\d+)*)"

livecheck.name

Name of the project for live checks. Is only used with freecode, sourceforge

• Default:${name} or the sourceforge, freecode project name if it can be guessed from${master_sites}.

• Example:

  livecheck.name      hibernate

livecheck.distname

Name of the file release for sourceforge checks. Use the name of the package release. You may use this keyword withoutlivecheck.version if you replace the version part of the name with“(.*)”.

• Default: sourceforge:${livecheck.name}

• Example:

  livecheck.distname  faad2.src

livecheck.version

Version of the project for a check; used for regex-based checks.

• Default:${version}

• Example:

  livecheck.version   ${name}-${version}

livecheck.url

URL to query for a check.

• Default:

  • ${homepage} or the first hit among the following sites:

  • http://freecode.com/projects-xml/${livecheck.name}/${livecheck.name}.xml

  • https://sourceforge.net/api/file/index/project-name/${livecheck.name}/rss

  • https://code.google.com/p/${livecheck.name}/downloads/list

• Example:

  livecheck.url       https://ftp.gnu.org/gnu/bison/

livecheck.regex

Regular expression to parse the resource for regex checks. Be sure to use a regular expression grouping around the version component. Also remember that square brackets need to be quoted because Tcl otherwise interprets them as a procedure call.

• Default: none

• Example:

  livecheck.regex     4th-(\[a-z0-9.\]+)-unix${extract.suffix}

livecheck.md5

md5 checksum to use for an md5 comparison.

• Default: none

• Example:

  livecheck.md5       37e6a5b6516a680c7178b72021d3b706

livecheck.ignore_sslcert

Disables verification of the server's SSL certificate.

• Default:no

• Example:

  livecheck.ignore_sslcert       yes

livecheck.compression

Sets the Accept-Encoding HTTP header in the request and automatically decompresses the server's response.

• Default:yes

• Example:

  livecheck.compression       no

distcheck.check

This option can be used to disable distcheck. It specifies what kind of check should be performed on distfiles:moddate (check if the Portfile is older than the distfile) ornone (no check).

• Default:moddate

• Example:

  distcheck.check     none

5.10.1. PortGroup Introduction

5.10.2. PortGroup github

5.10.3. PortGroup gnustep

5.10.4. PortGroup golang

5.10.5. PortGroup java

5.10.6. PortGroup perl5

5.10.7. PortGroup python

5.10.8. PortGroup ruby

5.10.9. PortGroup xcode

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

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.tclapache2-1.0.tclapp-1.0.tclarchcheck-1.0.tclbitbucket-1.0.tclcmake-1.0.tclcmake-1.1.tclcompiler_blacklist_versions-1.0.tclcompilers-1.0.tclconflicts_build-1.0.tclcrossbinutils-1.0.tclcrossgcc-1.0.tclcxx11-1.0.tclcxx11-1.1.tcldebug-1.0.tclelisp-1.0.tclgithub-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.

Thegithub portgroup allows for efficient porting of software hosted on GitHub.

PortGroup           github 1.0github.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 0ff25277c3842598d919cd3c73d60768version             20140401

github.tarball_from downloads

github.tarball_from tarball

fetch.type          gitpost-fetch {    system -W ${worksrcpath} "git submodule update --init"}

PortGroup gnustep allows for efficient porting of GNUstep-based open source software using the GNU objective-C runtime that defines options for the configuration, build, and destroot phases, and also defines some values for GNUstep-based software. A minimum Portfile using the gnustep PortGroup class need only define the fetch and the checksum phases.

Thegolang PortGroup allows for efficient porting of Go-based open source software.

PortGroup           golang 1.0go.setup            domain/author/project version [tag_prefix] [tag_suffix]

go.setup        domain/author/project version v

go.vendors      example.com/dep1/foo \                    lock    abcdef123456... \                    rmd160  fedcba654321... \                    sha256  bdface246135... \                    size    1234 \                example.com/dep2/bar \                    lock    abcdef123456... \                    rmd160  fedcba654321... \                    sha256  bdface246135... \                    size    4321

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

PortGroup java is useful for Java packages.

PortGroup perl5 allows for efficient porting of perl modules and other perl open source software.

PortGroup python allows for efficient porting of python-based open source software.