FAQ – MacPorts

Context Navigation

Version 74 (modified by blb@…, 15 years ago) (diff)
Add entry about upgrading/downloading Xcode

There is also a HOWTO section, which may answer your questions not listed here and provides useful tutorials for all sorts of using MacPorts.

General Questions
Software Questions
Portfile Development and Maintenance Questions
Runtime Errors
1. I try to disable a variant, but it just informs me of the proper usage for the port command
2. When trying to selfupdate, I get the error: failed to connect to rsync.macports.org: Connection refused (61)

General Questions

A port fails to build

Before filing a bug in the issue tracker, please make sure you have the latest version of MacPorts and of the ports tree by running

sudo port selfupdate

Then run

sudo port upgrade outdated

to upgrade your installed ports to the latest available versions.

Also, make sure you have the latest version of Xcode. Old versions of Xcode are known to make certain ports fail.

I get the error "C compiler cannot create executables" when I try to install a port

You need to install Xcode. Ensure you include both X11SDK and Unix Development.

How do I upgrade my Xcode install?

Some ports need newer versions of Xcode than that which ships with the OS, and will fail to install due to that requirement. Xcode is not updated via Software Update, you have to download it manually. To do so, go to http://connect.apple.com/ and log in with your ADC information (the free online account is enough to get access to Xcode). Once you log in, go to Downloads, then select Developer Tools on the right section under Downloads. You can then search for Xcode (there are quite a few versions available, make sure to get the latest for you OS version).

Is MacPorts Universal?

MacPorts works on both Intel- and PowerPC-based Macs, but the ports you install will be compiled only for the architecture you're currently running on. This means that if you migrate from, say, a PowerPC Mac to an Intel one and use Migration Assistant to copy your data to the new machine, you should reinstall all your ports on the new machine to rebuild them for Intel. It may be simpler to completely remove all of MacPorts and start fresh. See below for uninstallation instructions, but be sure to keep any configuration files you need.

For many ports, there's now an alternative: select the +universal variant when you build each port, and MacPorts will create universal binaries that work on both Intel and PowerPC. This can be useful if you anticipate migrating to a different Mac soon, or if you want to install MacPorts on an external hard drive that's used by both Intel- and PowerPC-based Macs. But note that because +universal is new, it may not work correctly for all ports, even if no error message is shown during installation. If you find a port that will not build with +universal, or if it builds but then does not work correctly, please file a bug report. If you can provide a patch to fix the problem, that's even better.

Some ports may only work on PowerPC Macs or only on Intel Macs. In some cases, these are bugs that need to be fixed. If there is a newer version of the software available, you should report this to the port maintainer. Maybe the new version works correctly on both architectures. If the port is already using the latest version, report the problem to the upstream authors of the software; the software may need to be updated. In other cases, the software may be specifically written for one processor architecture such that it will not be possible to make it available to the other.

See also Universal for a list of ports that were tested for +universal support and the results.

Why is /opt/local the default install location for MacPorts?

/opt/local was chosen so as to avoid stomping on other various installations (e.g. fink uses /sw to do the same); /usr/local is not a viable choice for several reasons:

Some software (especially auto* tools from Gnu) look in /usr/local as a default location, which means MacPorts can't be easily isolated when needed
/usr/local is usually reserved for the given system's admin to install items local to that system, and tends to be a bad choice to have taken over by a non-system port system
gcc considers /usr/local to be a standard system directory, causing (at least) the include directory to be unable to appear early in the list of include directories, and hence causing MacPorts-installed items to be difficult to use properly for items which need them (where another version is installed elsewhere, like /usr/X11R6)

How do I remove or uninstall MacPorts?

Uninstalling MacPorts can be a drastic step, and depending on the issue you're experiencing, you may not need to do so. If you're unsure, ask on the macports-users mailing list first.

If you need to uninstall MacPorts, and your port command is functioning, have it uninstall all the installed ports by typing this in the Terminal:

sudo port -f uninstall installed

All that will be left in your installation prefix now will be files that were not registered to any port. This includes any configuration files you edited, any databases you created, 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 /opt/local/etc), databases, or any other unique data.

To remove all traces of MacPorts, type this in the Terminal:

sudo rm -rf /opt/local \
/Applications/MacPorts \
/Applications/DarwinPorts \
/Library/Tcl/macports1.0 \
/Library/Tcl/darwinports1.0 \
/Library/LaunchDaemons/org.macports.* \
/Library/StartupItems/DarwinPortsStartup \
/Library/Receipts/MacPorts*.pkg \
/Library/Receipts/DarwinPorts*.pkg \
~/.macports

Substitute your own MacPorts prefix for /opt/local, if you've installed MacPorts in a different place.

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

Note that depending on which version of MacPorts you have and which ports you've installed, not all of the above paths will exist on your system. This is ok.

What are the folders in `${prefix}/var/macports/ for and why do they take up so much space?

man porthier says: "MacPorts runtime data", but it contains some more subfolders:

build

Is used during the building of ports, usually it contains only empty folders, does not take much space. During the building of a port there is a soft link ${prefix}/var/macports/sources/rsync.macports.org/release/ports/<category>/<name>/work pointing to the corresponding folder here.

distfiles

The downloaded sources of each built port, could be removed with port clean --dist <port>.

packages

Containing the binary archive of each installed port. Could be removed with port clean --archive <port> <version>+<variant>. These files are helpfull for uninstalling and later reinstalling the exact same ports (eg. for testing something). Only unpacking the archive is needed and no build will be performed. If these archives are never needed they can be disabled in ${prefix}/etc/ports/ports.conf with the portarchivemode option.

receipts

Contains detail information about each installed port, eg. which files belong to the port with corresponding checksums.

software

Contains the installed software itself. If a port is activated its files are hard links in the ${prefix} folders to the corresponding files here. port uninstall <port> <version>+<variant> would remove it from here, but then this port can not be used anymore.

sources

In the subfolder rsync.macports.org/release/base are the MacPorts sources themselves (e.g., for the port(1) command). A port selfupdate updates this from the MacPorts rsync server. In the subfolder rsync.macports.org/release/ports are folders for each port category and the ports themselves therein, where the corresponding Portfile and patches are found. port sync and also port selfupdate update this from the MacPorts rsync server.

I get `Error: checksum (md5/sha1/rmd160) mismatch for port`. What can I do about it?

MacPorts computes checksums of downloaded files to ensure they aren't corrupted and haven't been tampered with. Each portfile lists the checksums for the files that the port will download (using md5, sha1 and/or rmd160). If the computed checksum of the downloaded file doesn't match the one listed in the portfile, that means the file you downloaded is not the one the port designer used when creating the port, and so MacPorts stops the installation.

The first thing you should do if you get a checksum error is update your ports with sudo port sync — can you install the port now? If so, it means somebody else encountered the same checksum mismatch before and already fixed it.

If updating doesn't help, then you should attempt to discover why there is a checksum mismatch. There are several possible reasons:

The file is corrupt. If it was corrupted by the transfer, download it again (port clean --all <portname> and port install <portname>). If it is corrupted on the server, there is not much you can do about it. Open a bug in Trac and assign it to the port's maintainer. As for solving the problem: if there are other mirrors, try one of them. You can also ask if someone has a complete file they can send you on the MacPorts users' mailing list.
The developer has performed a "stealth upgrade". Sometimes upstream developers make "stealth upgrades" in which they change the contents of their distribution archive but not its version number, without informing MacPorts of this change. Perhaps the developer has repackaged the distribution with a different archiving program, or has fixed typos in the included documentation or made other presumably minor changes that did not warrant a regular release. This practice is not recommended because of the obvious difficulties it presents to MacPorts and other port systems that compute package checksums. Attempt to get confirmation from the developer of the software that this has occurred. If the developer cannot be reached, attempt to determine yourself whether a stealth upgrade has happened. Search the Internet and try to locate the older version of the archive that matches the checksum in the portfile. Also download the version currently available on the developer's site, extract both, and compare the contents (for example with diff -r -u <old> <new>). If the changes look minor and benign, or there are no changes at all, then it is safe for you to update the checksum in the portfile, and the port maintainer should be informed of this so that they can make the change official. If you cannot determine whether a stealth upgrade has taken place, ask for help on the users' mailing list.
The file has been tampered with. It is perhaps somewhat unlikely yet theoretically possible (and it has happened a few times in practice) that the archive being distributed by the developer (or by a mirror) has been genuinely compromised. If a hacker was able to manipulate the developer's (or the mirror's) server, the hacker could have uploaded a revised archive containing malware (a virus, a trojan horse, a spam-sending platform, etc.) of the hacker's choosing, and you would certainly not want to install such software. You must attempt to determine, as above, whether this has occurred by contacting the developer, or by locating an older version of the archive and comparing them. You can also contact the port maintainer or the users' mailing list.
A proxy is blocking your request. Some internet connections are protected by a proxy which may not allow file downloads, tar/zip downloads, or may not allow your particular computer to access the internet without being specifically allowed. In that case, the proxy may return a simple "disallowed" message (with an erroneous 200 status), which MacPorts mistakes for the file that should be downloaded. Examining the content of the downloaded file will determine if this is the case. If so, contact your network administrator for access.

Where can I find a GUI frontend for MacPorts?

There are several GUIs for MacPorts in development.

PortAuthority has been around for a long time. It's shareware and costs $20.
Pallet is a new GUI under development which can be installed with MacPorts by running sudo port install pallet.
Porticus is another new GUI currently in development.

What do I do if `port selfupdate` doesn't work or the Rsync server refuses connections?

First try sudo port -d selfupdate to get all errors to display. If your connection to the rsync server fails you may get blocked by a firewall or other network control software.

If you run LittleSnitch create a rule for rsync (/usr/bin/rsync) that allows connections to server hostname rsync.macports.org, port 873 (rsync), protocol 6 (TCP). Make sure the rule is enabled.

If you run PeerGuardian disable all filters or create an exception for rsync.macports.org. It is also possible to disable PeerGuardian before running a selfupdate command by typing the following command in Terminal, but make sure you stop all processes associated with PeerGuardian before doing this.

sudo kextunload -b xxx.qnation.PeerGuardian

If getting through a firewall is not a possibility, there are other methods you can use which are a bit more manual:

When I run `port list installed` I see the identical versions of some ports installed, why?

Using port list installed will give confusing results as the 'list' command bases its version information only on what is the currently-available version; so if you have port foo installed at versions 1 and 2 (with 2 being the current version available), list installed will only show foo at version 2, twice.

Instead, use port installed which will show the version which is actually installed.

Software Questions

Why do I have to install xorg-* ports?

MacPorts does not use the X11 client libraries provided by the system, but installs its own copy. Reasons to do so are consistent support for older machines and not violating /usr/X11. Most X11 related software is newer in MacPorts anyway.

Don't be scared away, MacPorts will still use the X11 server provided by the system.

Python fails to build

If you get an error building Python like

Python/mactoolboxglue.c:440: warning: return makes integer from pointer without a cast Python/mactoolboxglue.c:440

your Xcode installation is incomplete (you are missing e.g. the QuickTime SDK).

How do I get readline support for MacPort's Python?

If you're using python24, install the py-readline port.

If you're using python25, make sure your python25 port is up to date, at least 2.5.4_4, when the standard modules were reintegrated back into the port itself (see ticket #12369).

Will MacPorts link to system libraries rather than its own?

No, MacPorts maintains its own versions of libraries. See the next question for the reason why.

You may find some ports that link with some system libraries. Some of these are intentional, such as in cases where the MacPorts version is missing some crucial functionality (e.g. ports that need Kerberos support use the Mac OS X-supplied library, not the MacPorts one). In other cases these are bugs in the relevant ports, and tickets should be filed so it can be corrected.

Why is MacPorts using its own libraries?

There are several reasons why MacPorts uses its own libraries. It makes ports more consistent across different versions of Mac OS X. If we can rely on e.g. openssl 0.9.8 from MacPorts, we don't have to test every port that needs ssl for every available openssl installation. Apple's software tends to break from time to time (e.g. openssl refuses to build with an old zlib, but for awhile Apple shipped the old headers of the vulnerable zlib version). Even if Apple's versions aren't broken, they're rarely up-to-date. Apple has a habit of not updating the libraries in Mac OS X until absolutely necessitated by a security vulnerability.

The drawbacks of this policy are minimal: Wasting a few megabytes for e.g. a Python installation is next to nothing if you have a multi-gigabyte hard disk, and the time required to build the additional ports decreases as computers get faster.

GNOME has an empty menu

See the GNOME section of this Wiki for more information.

Why do the python ports have so many dependencies?

Earlier versions of the python ports either used variants (python23) or split some modules out from the base port (python24) in order to reduce the number of dependencies for the port. Using variants is bad as that requires a complete rebuild of the port in order to add a given module (like readline support); also, dependencies can't specify variants currently (see ticket #126).

Using separate ports for these modules (like py-readline) avoids the need to completely rebuild the base port, and can be used as a dependency, but ends up having other issues. One is that these modules are installed using the standard distutils method for python, which causes them to be installed in a different location than where they would be when installed normally (see ticket #12369). The other is that many python developers have expectations when they install python, and installing python24 simply does not match that.

When should I use the force option (-f)

Use of the force option (-f) is rarely necessary, but some suggestions in the past have recommended its use quite frequently. One of the few useful applications of it is in forcing a reinstall of an already-installed port to add a new variant, for example

sudo port -fn upgrade mysql5 +server

will install a new version of the mysql5 port with the current variants plus +server. Note the use of the -n (don't follow dependencies) option, which is important in this case (otherwise ports depended on by mysql5 will be upgraded as well even when it isn't needed).

One of the other times -f is needed is when you run into a stray file in your MacPorts prefix, not owned by a port, but blocks the install of one. This is seen with an error message from port similar to

Error: Activating some-port @1.0_0 failed: Image error: /opt/local/path/to/stray/file already exists and does not belong to a registered port.  Unable to activate port some-port.

Unless you know the source of that file and that you need to keep it, this is a good use of force. However, don't use it with install but with activate:

sudo port -f activate some-port

Outside of -fn upgrade and -f activate force can be extremely dangerous, and should be avoided unless you know precisely how port is going to act.

Portfile Development and Maintenance Questions

Is it possible to have a dependency on a specific variant of another port? E.g. "postgresql8 +server"?

No. This is ticket #126. The dependency engine is currently unable to handle specifying anything beyond "port X requires port Y" or "port X requires file Z which can be provided by port Y." There have been discussions on revamping the engine (see the mailing list archives) but nothing concrete as yet. This is why the most useful variants really shouldn't be variants at all but rolled into the port itself. It can also sometimes be useful to break variants out into separate ports (e.g. the postgresql83-doc and postgresql83-server ports, instead of having +doc or +server variants of the postgresql83 port).

Why won't `portindex` work? I have a local repository set up

Your local repository needs the ports to be nested within a category for portindex to work, as explained in the relevant documentation.

Why was the `cd` command removed from trunk?

The cd command was removed from trunk in r28796. As of release 1.7.0 it will no longer be available for use in Portfiles. cd is harmful as it changes the current directory of the whole process and not only of the current Tcl interpreter. Also, it becomes unreliable when used inside phases and other phases begin to rely on it.

Please use absolute paths instead, starting with ${worksrcpath}. If you need to run a command with system, use it like system "cd ${worksrcpath} && autoreconf".

What is the process for becoming a committer?

The process is pretty much the same as for any other open source project. See the relevant documentation and the New commiters guide for what commit access to MacPorts entails.

Why Tcl?

These mailing list posts by Landon Fuller, one of the original authors, explain why Tcl was chosen for MacPorts:

http://permalink.gmane.org/gmane.os.opendarwin.darwinports/369
http://permalink.gmane.org/gmane.os.opendarwin.darwinports/8826

Runtime Errors

I try to disable a variant, but it just informs me of the proper usage for the `port` command

When using

port <command> <portname> -<variant>

the dash in the command is going to be interpreted as an option, hence getting the usage message. It needs to be escaped away with a double-dash:

port <command> <portname> -- -<variant>

When trying to selfupdate, I get the error: failed to connect to rsync.macports.org: Connection refused (61)

Some firewalls, such as PeerGuardian, block connections to certain corporate IP addresses as a way to prevent software from "phoning home" and violating your privacy. Our main rsync server is hosted by Apple Inc. Self updating requires an rsync connection to download files, but this will be blocked. In order to work around this, you need to temporarily disable or white-list rsync.macports.org. Another alternative is to use another mirror that is not hosted by Apple.

The black list entry is all of Apple Inc's subnet, which is 17.0.0.0/8, in case you want to find it. PeerGuardian will filter your network connections even if it is not actively running as an application.

Download in other formats:

Plain Text