How To Troubleshoot MacPorts

Ryan Schmidt ryandesign at
Fri Apr 12 16:50:13 UTC 2019

On Apr 11, 2019, at 20:25, Michael Newman wrote:

> I suppose the root of my problem is that while I have a basic understanding of how to use MacPorts, I have very little knowledge about how it actually works. 

We explain some of this in our Guide, but I'll try to give an overview.

Of course you know MacPorts installs other software, which we call "ports".  If a usable binary is available from our build server, it downloads and installs that, otherwise it downloads the source and builds it. Both sources and binaries are mirrored on a global network of servers, so downloads should be fast wherever you are. Before installing a port, MacPorts installs any dependencies.

Each port is described in a text file called Portfile, which is written in the Tcl language but with many additional MacPorts-specific variables and procedures. The Portfile is a recipe that MacPorts follows to install that software. "port file XYZ" will show you the location on your disk of the Portfile for port XYZ. You can browse the entire collection of Portfiles on your disk, or online here:

Any reference for the Tcl language, such as the Tcl/Tk web site, can teach you the basics of the language. MacPorts currently use Tcl 8.5.

MacPorts performs port installations in "phases". If a build from source is needed, the phases are fetch, checksum, extract, patch, configure, build, destroot, install, activate. You've seen these terms scroll by on the console when you install a port. Not all phases are used by each port. Each phase has certain default behavior. Individual phases can be modified by each port. For example the default behavior of the configure, build, destroot phases are designed for autotools-based software; a port for software that doesn't use autotools might need to change those defaults. For any phase, additional Tcl code can be run before or after the phase, or a phase can be overridden entirely. Most phases also offer variables that change their behavior. For example, the patch phase uses a variable "patchfiles" which the Portfile author can set to a list of patch files that should be applied to the source code after extracting it but before configuring it, and the fetch phase uses a variable called "distfiles" to know what file(s) to download and a variable called "master_sites" to know what server(s) to download from.

Many ports need the same changes to the defaults. For example, hundreds of ports for software that uses the cmake configuration system need a common set of modifications while ports that build using xcodebuild need a different set of common changes. MacPorts accommodates this need with a feature called PortGroups, which are like include files in other languages. A port can include as many PortGroups as needed, and a PortGroup can include other PortGroups. For example, a port using the cmake build system and requiring a compiler supporting the C++ 11 standard would include both the cmake and cxx11 PortGroups. PortGroups are Tcl files just like Portfiles, and they might define additional variables or procedures of their own which ports which include that PortGroup can use. PortGroups should be described in the Guide, but for those several that aren't, you'll have to read their code if you want to see what they do. Their code is here:

> For example, I’ve been confused as to why some ports generate a config log and some don’t. You explained that. 

Yes, some configuration systems like autotools and cmake automatically generate logs, some others don't. And some ports don't have a configuration step at all.

> I suppose the takeaway from your post is that I should take more time to study other threads and learn from them. My failure is to only read this list when I have a problem of my own to solve. That’s a poor strategy for learning. 

I recommend that, and it's why I like that we use mailing lists for our discussions. Sometimes people ask why we don't use a web forum, but those seem to lend themselves to people only receiving notifications for the specific topics they've started or participated in. If you subscribe to a mailing list, you get all the topics. You don't have to read all of them, but maybe you'll see a topic that interests you and you'll read it and learn something, or you'll see a topic with a question you know the answer to and then you can participate, and in this way we build the community and the knowledge base.

If you want to know more about how MacPorts works or how Portfiles are written, you might want to join the macports-dev mailing list, since that kind of thing is usually discussed there. The macports-users list is mostly just for how to use MacPorts, without a great deal of talk about how it all works under the hood.

More information about the macports-users mailing list