MacPorts Guide

To launch X11 applications directly from an X11 window (instead of a terminal window), you need to have the MacPorts paths imported into X11 sessions when they are opened. This is a two step process.

First, tell X11 about the ~/.profile file that will be created after you install MacPorts. Do this by editing the file /etc/X11/xinit/xinitrc and adding this line near the top.

source ~/.profile

Now finish the process by making subsequent X11 sessions opened using the menu bar respect your .profile file.

The Mac OS X package installer automatically installs MacPorts, sets the shell environment, and runs a selfupdate operation to update the ports tree and MacPorts base with the latest release.

If you installed MacPorts using the package installer, skip this section. To install MacPorts from the source code, follow the steps below.

%% export PATH=/bin:/sbin:/usr/bin:/usr/sbin
%% cd ~/MacPorts-1.x.x/
%% ./configure --prefix=NEW_PREFIX --with-tclpackage=NEW_TCLPACKAGE
%% make
%% sudo make install

MacPorts base upgrades are performed automatically (when a newer release is available) during a selfupdate operation. To upgrade a copy of MacPorts that was installed from source to the newer release of the source code, simply repeat the source install with the newer version of the MacPorts source code.

To uninstall MacPorts from the default location /opt/local/, perform these commands from a terminal window.

%% sudo rm -rf /opt/local/
%% sudo rm -rf /Applications/MacPorts/
%% sudo rm -rf /Library/Tcl/macports1.0/
%% sudo rm -rf /Library/LaunchDaemons/org.macports.*

The selfupdate option should be used regularly to sync the local ports tree with the global MacPorts ports repository so you will have the latest port versions. It also checks for new revisions of the MacPorts infrastructure, called MacPorts base, and upgrades it when necessary.

%% sudo port selfupdate

Use the debug flag for verbose output.

%% sudo port -d selfupdate

DEBUG: Rebuilding the MacPorts base system if needed.
DEBUG: Synchronizing ports tree(s)
Synchronizing from rsync://rsync.macports.org/release/ports/
DEBUG: /usr/bin/rsync -rtzv --delete-after rsync://rsync.macports.org/release/ports/
receiving file list ... done

[ ... trimmed ... ]


The MacPorts installation is not outdated and so was not updated
DEBUG: Setting ownership to root
selfupdate done!

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

DEBUG: Updating using rsync
receiving file list ... done

Congratulations, you have successfully installed the MacPorts system.

The sync option performs a subset of selfupdate actions. It synchronizes the ports tree, as does selfupdate, but it does not check for upgrades to MacPorts base. On Mac OS X, unless there is a special reason not to do so, you should run selfupdate.

The list option is used to get a list of all available ports. The list of available ports is very long, so use search if you know a port's name or part of it.

%% port list

The search option is very useful to find port names by partial matches.

%% port search rrd

rrdtool          net/rrdtool       1.2.23    Round Robin Database
php5-rrdtool     www/php5-rrdtool  1.0       PHP 5 glue for RRDtool

The info option is used to get information about a port: description, maintainer, etc.

%% port info flowd

flowd 0.9, net/flowd (Variants: universal, darwin_8)
http://www.mindrot.org/flowd.html

flowd is a small, fast and secure NetFlow collector.

Platforms: darwin
Maintainers: nomaintainer@macports.org

The deps option shows you the dependencies of a port; dependencies are explicitly declared in Portfiles.

%% port deps apache2

apache2 has library dependencies on:
        apr
        apr-util
        expat
        openssl
        pcre

The variants option 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 that may be invoked at install time. See Invoking Port Variants below to install ports that have variants.

%% port variants nmap

nmap has the variants:
        universal
        gtk2
        no_ssl
        no_pcre

The option install is used to install a port. See Invoking Port Variants below to install ports that have variants.

%% sudo port install nmap

The option clean deletes all intermediate files that MacPorts creates while building a port. A port clean is also often necessary to remove corrupted tarballs after a failed fetch phase.

%% port clean --all vile

The uninstall option will uninstall an installed port.

%% port uninstall vile

%% port -f uninstall vile

The contents option displays the files that have been installed by a given port. Uninstalled ports will always show no contents.

%% port contents render

Port render contains:
  /opt/local/include/X11/extensions/render.h
  /opt/local/include/X11/extensions/renderproto.h
  /opt/local/lib/pkgconfig/render.pc
  /opt/local/share/doc/render/library
  /opt/local/share/doc/render/protocol

The installed option displays all installed ports.

%% port installed

The following ports are currently installed:
  aalib @1.4rc5_2 (active)
  apr @1.2.8_0 (active)
  apr-util @1.2.8_2 (active)
  atk @1.18.0_0 (active)

[ ... trimmed ...]

  wxWidgets @2.8.4_2+darwin_8 (active)
  Xft2 @2.1.7_0 (active)
  xrender @0.9.0_0+darwin_8 (active)
  zlib @1.2.3_1 (active)

The outdated option checks your installed ports against the MacPorts repository to see if updated Portfiles have been released since your ports were installed.

%% port outdated

apr                            1.2.8_0 < 1.2.9_0
autoconf                       2.61_0 < 2.61_1
gimp                           2.2.14_0 < 2.2.16_0
libtool                        1.5.22_0 < 1.5.24_0
pkgconfig                      0.21_0 < 0.22_0

The upgrade option upgrades installed ports and their dependencies when a Portfile in the repository has been updated after a port was installed.

%% port upgrade gnome

If you wish not to upgrade a port's dependencies, use the -n switch.

%% port -n upgrade gnome

If you'd like to upgrade all outdated ports, use this command.

%% port upgrade outdated

%% port -u upgrade vile

The dependents option reports what ports depend upon a given port, if any. MacPorts learns about dependents during port installation, so uninstalled ports will always report that there are no dependents.

%% port dependents openssl

neon depends on openssl
gnome-vfs depends on openssl
libdap depends on openssl

The livecheck option checks to see if the application corresponding to a given port has been updated at the developer's download site. It's especially useful for port maintainers, but others may also wish to see if a port has the latest available distribution source. See section Livecheck for more information.

%% port livecheck rrdtool

rrdtool seems to have been updated (port version: 1.2.23, new version: 1.3beta1)

A variant can only be invoked when a port is installed. After you have determined what variants a given port has, if any, you may install a port using the variant as shown.

%% port install fetchmail +ssl

Port variant execution may be verified using the port command with the verbose switch.

%% port -v install fetchmail +ssl

When a port is installed using a valid variant and specified correctly, the verbose output will contain:

DEBUG: Executing variant ssl provides ssl

For an explanation of default variants see Port Variants. Default variants are optional, and not all ports using variants have them. For ports with default variants, you may install a port without them by negating default variants using "-" as shown.

%% port install fetchmail -ssl

To verify that you have properly negated a default variant, you may want to use verbose mode. But negated variants are simply not reported in any way by the port command, as if they did not exist. You will know you have successfully negated the default variant in the example above if you do not see this line in the verbose output.

DEBUG: Executing variant ssl provides ssl

Binary archives can only be used on a target system running MacPorts. Binary archives allow MacPorts utilities to begin installation after the destroot phase and install and activate a port on the target system. Binary archives are created using the port command as shown.

%% port -d archive logrotate

Debug output is shown below.

--->  Creating logrotate-3.7_0.i386.tgz

[ ... trimmed ... ]

DEBUG:
./
./+COMMENT
./+CONTENTS
./+DESC
./+PORTFILE
./+STATE
./opt/
./opt/local/
./opt/local/etc/
./opt/local/etc/logrotate.conf
./opt/local/man/
./opt/local/man/man8/
./opt/local/man/man8/logrotate.8
./opt/local/sbin/
./opt/local/sbin/logrotate
--->  Archive logrotate-3.7_0.i386.tgz packaged
DEBUG: Executing archive_finish
--->  Archive for logrotate 3.7_0 packaged

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

Binary packages are standalone binary installers that are precompiled; they do not require MacPorts on the target system. Binary files created with MacPorts may be either .pkg (Mac OS X Installer Packages), or RPM (RPM Package Manager) format. MacPorts may also process a .pkg package into a Mac OS X .dmg disk image file. You may create binary packages with the port command as shown in these examples.

%% port pkg pstree

You may create a Mac OS X .dmg disk image file as shown.

%% port dmg pstree

You may compile a port into an RPM file as shown, in order to install it onto a target that has RPM utilities or a full package management system that can install RPMs.

%% port rpm pstree

All packages are placed in a port's work directory.

Source packages are bundles consisting of a Portfile, patches if needed, and any other files required to install the port. Port source packages are mainly used by developers of package management and port submission frameworks. Port source packages may be in either .portpkg (XAR) or .nosrc.rpm (SRPM) format.

# $Id$
PortSystem          1.0

name                rrdtool
version             1.2.23
categories          net
maintainers         julesverne
description         Round Robin Database
long_description    RRDtool is a system to store and display time-series data
homepage            http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/
platforms           darwin
master_sites        http://oss.oetiker.ch/rrdtool/pub/ \
                    ftp://ftp.pucpr.br/rrdtool/

checksums           md5 dafa161bc9c61e57636a6085c87c1fe8 \
                    sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
                    rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23

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

configure.args      --prefix=${prefix} \
                    --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}/bin
    xinstall -m 755 ${worksrcpath}/cdpr ${destroot}${prefix}/bin
}

To eliminate a default phase, simply define a phase with no contents as shown.

build {}

Startupitems may be placed in the global section of a Portfile.

startupitem.create      yes
startupitem.name        nmicmpd
startupitem.executable  "${prefix}/bin/nmicmpd"

Startupitems keywords may also be used within a variant definition to make their installation conditional.

variant server {
    startupitem.create  yes
    startupitem.start   "${prefix}/share/${name}/vm-pop3d.init start"
    startupitem.stop    "${prefix}/share/${name}/vm-pop3d.init stop"
}

The most common use for a variant is to add or remove dependencies, configure arguments, and build arguments from the global Portfile section. Here is an example of a port providing four variants that add additional configure arguments to a port.

variant pop     { configure.args-append --enable-pop }
variant imap    { configure.args-append --enable-imap }
variant ssl     { configure.args-append --with-ssl }
variant debug   { configure.args-append --enable-debug }

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

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 be sent to the application developer (not the port author) so the modifications may be included in the next version; then the port patch may be removed after an updated tarball is released.

Though MacPorts applies patch files automatically, you may want to know how to apply patch files manually if you want to test patch files you have created or you wish to apply uncommitted Portfile patches.

Portfiles may be thought of as a table of keys and values in two columns 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:filetype=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 ("set libver") and variant declarations ("variant mysql5") are exceptions, and may be considered a single word on the left side, with a single space between words.

Frequently multiple items are necessary in the second column. For example, to set multiple source download locations, multiple "master_sites" must be defined. Unless the second column items are few and short you should use multiple lines, separate lines with a backslash, and (to emphasize the unity of the block) indent the first line at a deeper level than the following lines as shown in this example.

destroot.keepdirs   ${destroot}${prefix}/var/run \
                    ${destroot}${prefix}/var/log \
                    ${destroot}${prefix}/var/cache/mrtg

Configuration files should never be overwritten!

TODO:

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}

TODO: revisions should be increased if all users should update the port, for example if a bug was introduced which causes problems for users. It should not be increased if it only affects the installation process, for example if it failed for some users. Users which got it working by themselves need no update so the revision doesn't need to be updated.

If a new version is released then you should set the revision back to 0 or remove it completely until it's necessary again

TODO:

If a port doesn't need a configure phase, use the keyword use_configure instead of defining an empty configure phase.

use_configure    no

A MacPorts port has ten distinct phases. The MacPorts base is set to perform default steps for applications that use the standard configure, make, and make install steps, but for applications that do not conform to this behavior, installation phases may be declared in a Portfile to augment or override the default behavior as described in the Portfile Development chapter.

MacPorts keywords are used to specify required or optional items within a Portfile, or to override default options used by MacPorts base for individual ports. Keywords are to be used within the "global" and "variant" sections of Portfiles, and not within optional port phase declarations.

In other words, port phase keywords are not located within port phase declarations, but rather they refer to port phases and set options for those phases, and they take affect whether or not phase declarations have been explicitly defined in a Portfile.

The list of keywords related to the fetch phase.

The list of keywords related to the checksum phase.

The list of keywords related to the extract phase.

The list of keywords related to the patch phase.

The list of keywords related to the configure phase.

MacPorts base sets some important default configure options, so should use the -append version of most configure keywords so you don't overwrite them. For example, MacPorts base sets default configure.cflags so you should always use configure.cflags-append to set additional CFLAGS in Portfiles.

The list of keywords related to the build phase.

The list of keywords related to the test phase.

The list of keywords related to the destroot phase.

Port dependencies should be provided by MacPorts ports whenever possible, however dependencies may be provided by vendor-supplied software when satisfying a dependency by a port is not practical or desirable for a special reason. Dependencies of this type are called non-port dependencies.

Non-port dependencies should only be used if the application or library can be installed by multiple ports (for example stable and -devel version) or if it can't be installed with MacPorts.

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

depends_lib         port:rrdtool port:apache2

depends_build       port:libtool

depends_run         port:apache2 port:php5

Non-port dependencies are specified as shown in these examples:

depends_lib         lib:libX11.6:xorg

depends_build       bin:glibtool:libtool

depends_run         path:${prefix}/lib/libltdl.a:libtool

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

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

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

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

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

#!/bin/sh

case "$1" in
    start)
        echo -n "Starting vm-pop3d: "
        /opt/local/sbin/vm-pop3d -d 10 -t 600

[... trimmed ...]

But if a script itself is a daemon, use the “executable” StartupItem type since that way it will be launched directly and its health tracked automatically. When using “script” StartupItems, the startupitem.pidfile keyword must be used if you want daemondo to monitor a daemon process and restart it if it dies.

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

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

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

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

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

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

%% ls -l /Library/LaunchDaemons

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

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

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

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

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

#!/bin/sh

# MacPorts generated daemondo support script

# Start
Start()
{
    /opt/local/share/mysql5/mysql/mysql.server start
}

# Stop
Stop()
{
    /opt/local/share/mysql5/mysql/mysql.server stop
}

[... trimmed ...]

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.

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.

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

PortGroup xcode allows for efficient porting of Xcode-based opensource software. It handles configuration, build, and destroot phases. It also defines some values for Xcode-based software. A minimum Portfile using the xcode PortGroup class only defines the fetch and the checksum phases.

Using PortGroup xcode is a way to make your port able to tolerate Xcode version updates because the PortGroup is tested against all supported Mac OS X and Xcode versions.

sources.conf is where the location(s) are set to scan for MacPorts Portfiles. This file is commonly modified to add a local Portfile repository.

macports.conf contains advanced MacPorts configuration options. See the file comments for instructions.

variants.conf is used to specify variants to be used for all ports where they exist.

The code for the Port API is located in base/src/port1.0. The Port API provides all the primitives required for a Portfile to be parsed, queried, and executed. It also provides a single procedure call that the MacPorts API uses to kick off execution: "eval_targets". The port Tcl library supplies these procedures, all of which are generated at run-time using the options procedure in portutil.tcl.

The macports Tcl library loads the Portfile into a sub-interpreter, within which all port-specific code is run. This process ensures that there will never be pollution of the Tcl space of other ports, nor the MacPorts libraries, nor the calling application.

The Ports API performs the following functions:

The code for the MacPorts API is located in base/src/macports1.0. The MacPorts API provides a public API into the MacPorts system by providing simple primitives for handling Portfiles, dependencies, and registry operations, and exports the MacPorts API for the port command line utility, or any other. The API has very little information about the contents Portfiles; instead, it relies entirely upon the port Tcl library. By keeping the high level API simple and generic, revisions to the underlying ports system will not necessarily require a revision of the high level MacPorts API.

The MacPorts API is also responsible for loading user specified options into a sub-interpreter to be evaluated by the ports API. In that case it sets the variable name in the sub-interpreter and adds the option to the sub-interpreter's global array user_options(). User options are passed as part of the call to mportopen.

The MacPorts API performs the following functions:

For an example of the MacPorts API, when one executes port search cm3, the port utility:

For another MacPorts API example, when one executes port install cm3, the port utility:

The pextlib TCL library provides a variety of C extensions to add capabilities to TCL procedures; for example, an interface to flock(2) and mkstemp(3).

The flat file registry (MacPorts default registry) files are contained in ${portdbpath}/receipts, which by default is location ${prefix}/var/macports/receipts. File mappings and dependency mappings are tracked in the flat file registry by two files:

The MacPorts registry provides a public API in the registry1.0 Tcl package. Using this API listed below you can access the MacPorts Registry using the default receipt storage mechanism chosen in macports.conf.

There are certain conventions used to ensure that Trac tickets convey as much accurate information as possible so problems and contributions may be acted upon efficiently.

Ports are contributed by following these steps. See Ticket Submission Guidelines above for a description of all fields.

Enhancements to existing ports may comprise new functionality for a given port, bug fixes or even simple version updates. They should always be contributed as Portfile patches. See Ticket Submission Guidelines above for a description of all fields.

If you have a port update or bugfix for a port you do not maintain, to respect the rights of the port maintainer you should follow the following guidelines:

However, for maintained ports without <openmaintainer@macports.org>, there are some conditions under which maintainer permission may be waived:

A port may be considered abandoned if a bug has not been acknowledged for more than three weeks after a ticket is filed. If this time period has passed and you wish to initiate the Port Abandonment protocol and volunteer as the new maintainer: