MacPorts Guide

To launch X11 applications directly from an X11 window (instead of a regular terminal window), you need to make it so X11 sessions opened using the menu bar respect your .profile file.

Download the latest version of Xcode as a disk image from the Apple developer website or get it using 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.0.x. Xcode 4 costs money, but Xcode 3 is still available free of charge. There are two options for downloading it:

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 OS X 10.5 (v3.1.4) or for 10.4 (v2.5).

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

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.

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 run completely from trunk, using only Subversion to keep MacPorts up to date.

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.

%% export PATH=/bin:/sbin:/usr/bin:/usr/sbin
%% MP_PREFIX=/opt/macports-test
%% ./configure --prefix=$MP_PREFIX --with-applications-dir=$MP_PREFIX/Applications
%% make
%% sudo make install

The postflight script automatically sets the PATH variable, and optionally the MANPATH and DISPLAY variables according to the rules described below. If a current shell configuration file exists at installation time it is renamed to “mpsaved_$timestamp”. Those installing 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, type env in the terminal to verify the current environment settings after the file has been created. Example output for the env command is shown below.

MANPATH=
TERM_PROGRAM=Apple_Terminal
TERM=xterm-color
SHELL=/bin/bash
TERM_PROGRAM_VERSION=237
USER=joebob
__CF_USER_TEXT_ENCODING=0x1FC:0:0
PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
PWD=/Users/joebob
EDITOR=/usr/bin/pico
SHLVL=1
HOME=/Users/joebob
LOGNAME=joebob
DISPLAY=:0.0
SECURITYSESSIONID=b0cea0
_=/usr/bin/env

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

MacPorts will check MP_EDITOR, VISUAL and EDITOR in this order, allowing you to either use a default editor shared with other programs (VISUAL and EDITOR) 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 editor TextWrangler (installation required), add this line:

export EDITOR=/usr/bin/edit

To keep a command-line text editor as default while using a graphic editor with portfiles, add this:

      export EDITOR=/usr/bin/vi
      export MP_EDITOR=/usr/bin/edit

The help action shows some brief information about the specified action, or if no action is specified, shows basic usage information for the port command in general.

%% port help selfupdate

Usage: selfupdate --nosync

Upgrade MacPorts itself and run the sync target

The selfupdate action 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 action 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 action lists the currently available version of the specified ports, or if no ports are specified, displays a list of all available ports. The list of available ports is very long, so use search if you know a port's name or part of it.

%% port list

The search action allows finding ports by partial matches of the name or description. Other fields can be matched against, and matched in different ways, by using options. Run port help search for details.

%% port search rrd

php5-rrdtool @1.0 (php, net, devel)
    PHP 5 glue for rrdtool

rrdtool @1.4.4 (net)
    Round Robin Database

Found 2 ports.

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

%% port info flowd

flowd @0.9 (net)
Variants:             universal

Description:          flowd is a small, fast and secure NetFlow collector.
Homepage:             http://www.mindrot.org/flowd.html

Platforms:            darwin
License:              unknown
Maintainers:          nomaintainer@macports.org

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

%% port deps apache2

Full Name: apache2 @2.2.17_0+preforkmpm
Library Dependencies: apr, apr-util, expat, openssl, pcre

The variants action allows you to check what variations of a port are available before you install it. Variants are a way for port authors to provide options 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:
   no_pcre: build without pcre support
   no_ssl: build without ssl support
   universal: Build for multiple architectures
   zenmap: build zenmap in addition to nmap

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

%% sudo port install nmap

The action 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.

%% sudo port clean --all vile

The uninstall action will remove an installed port.

%% sudo port uninstall vile

%% sudo port uninstall --follow-dependencies vile

%% sudo port uninstall --follow-dependents ncurses

%% sudo port -f uninstall ncurses

The contents action displays the files that have been installed by a given port. Uninstalled ports cannot have their contents listed.

%% 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

The installed action displays the installed versions, variants and activation status of the specified ports, or if no ports are specified, all installed ports. Use the -v option to also display the platform and CPU architecture(s) for which the ports were built, and any variants which were explicitly negated.

%% 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 (active)
  Xft2 @2.1.7_0 (active)
  xrender @0.9.0_0 (active)
  zlib @1.2.3_1 (active)

%% port -v installed atlas

The following ports are currently installed:
  atlas @3.8.3_4+gcc44-gcc43 (active) platform='darwin 10' archs='x86_64'

The outdated action checks your installed ports against the current ports tree to see if updated Portfiles have been released since your ports were installed. Note that you will not see new versions unless you have updated your ports tree using selfupdate or sync.

%% 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 action upgrades installed ports and their dependencies when a Portfile in the repository has been updated after a port was installed.

%% sudo port upgrade gnome

If you wish not to upgrade a port's dependencies, use the -n switch. Note that this will often cause problems.

%% sudo port -n upgrade gnome

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

%% sudo port upgrade outdated

%% sudo port -u upgrade vile

The dependents action 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 action 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)

The lint action checks if the Portfile conforms to the MacPorts standards specified in Portfile Development.

If a Portfile validates fine the following message is shown.

%% port lint chemtool

--->  Verifying Portfile for chemtool
--->  0 errors and 0 warnings found.

Otherwise the warnings and errors are listed.

%% port lint KeyArcher

--->  Verifying Portfile for KeyArcher
Warning: Line 2 should be a newline (after RCS tag)
Warning: Line 5 has trailing whitespace before newline
Error: Missing required variable: platforms
--->  1 errors and 2 warnings found.

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.

%% sudo port install fetchmail +ssl

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

%% sudo 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.

%% sudo 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

is essential to stay up-to-date with MacPorts:

%% sudo port selfupdate

Password:
--->  Updating the ports tree
--->  Updating MacPorts base sources using rsync
MacPorts base version 1.9.1 installed,
MacPorts base version 1.9.1 downloaded.
--->  MacPorts base is already the latest version

The ports tree has been updated. To upgrade your installed ports, you should run
  port upgrade outdated

is often useful, in case you don't have time to wait for port upgrades (Every port needs to be downloaded, configured, built and installed, which can be - depending on your systems resources - a very time consuming procedure.):

%% port outdated

The following installed ports are outdated:
makedepend                     1.0.2_0 < 1.0.3_0         
Xft2                           2.1.14_0 < 2.2.0_0        
xorg-bigreqsproto              1.1.0_0 < 1.1.1_0         
xorg-compositeproto            0.4.1_0 < 0.4.2_0         
xorg-damageproto               1.2.0_0 < 1.2.1_0         
xorg-fixesproto                4.1.1_0 < 4.1.2_0         
xorg-libXdmcp                  1.0.3_0 < 1.1.0_0         
xorg-libXmu                    1.0.5_0 < 1.1.0_0         
xorg-libXScrnSaver             1.2.0_0 < 1.2.1_0         
xorg-randrproto                1.3.1_0 < 1.3.2_0         
xorg-scrnsaverproto            1.2.0_0 < 1.2.1_0         
xorg-xcmiscproto               1.2.0_0 < 1.2.1_0         
xpm                            3.5.8_0 < 3.5.9_0         
xorg-util-macros               1.10.1_0 < 1.11.0_0

is usually done with the following command:

%% sudo port upgrade outdated

In case you want to upgrade only a specific port (for whatever reason):

%% 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

makes sense if you are sure that you won't change back to the older version(s) (which could be necessary in case of newly introduced bugs in the upgraded port version):

%% port installed inactive

The following ports are currently installed:
  makedepend @1.0.2_0

%% sudo port uninstall inactive

Password:
--->  Uninstalling makedepend @1.0.2_0

Of course one could also select only a specific inactive port, but that requires to specify the exact version:

%% sudo port uninstall makedepend @1.0.2_0

Password:
--->  Uninstalling makedepend @1.0.2_0

can sometimes be very helpful (example: find ports depending on 'xorg-util-macros'):

%% port echo depends:xorg-util-macros

mkfontscale
xorg-libAppleWM
xorg-libX11
xorg-libXaw
xorg-libXevie
xorg-libXp
xorg-libXt
xorg-server
xorg-server-devel
xscope
xtrap

can be sometimes worthwhile, since often additional ports get installed when a specific port is installed. One can imagine that if one keeps installing and uninstalling ports for some time the MacPorts tree can be swamped with ports actually not necessary anymore. Leaves can be found by issuing the command:

%% port echo leaves

aalib                          @1.4rc5_4 
autoconf                       @2.68_0 
autoconf263                    @2.63_0 
automake                       @1.11.1_0 
cmake                          @2.8.2_4 
coreutils                      @8.5_0

The following command delivers a similar result:

%% port installed leaves

  aalib @1.4rc5_4 (active)
  autoconf @2.68_0 (active)
  autoconf263 @2.63_0 (active)
  automake @1.11.1_0 (active)
  cmake @2.8.2_4 (active)
  coreutils @8.5_0 (active)

These leaves may be wanted, but could also be unwanted ports. (See the following entry!)

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

aalib                          @1.4rc5_4 
autoconf                       @2.68_0 
autoconf263                    @2.63_0 
automake                       @1.11.1_0 
cmake                          @2.8.2_4 
coreutils                      @8.5_0 
physfs                         @2.0.1_0

Now it is up to the user to decide what's needed and what is not. Let's say one certainly would want ports starting with autoconf up to coreutils, since they are often used in port installation. Set those as requested ports using:

%% sudo port setrequested autoconf autoconf263 automake cmake coreutils

Say port aalib is not needed anymore, while physfs seems odd and since you don't know what to make of it, you need to check out what it actually is and which ports needed its installation at some time in the past.

%% port info physfs

physfs @2.0.1 (devel)
Variants:             debug, universal

Description:          PhysicsFS is a library to provide abstract access to various
                      archives. It is intended for use in video games, and the design
                      was somewhat inspired by Quake 3's file subsystem.
Homepage:             http://icculus.org/physfs/

Build Dependencies:   cmake
Library Dependencies: zlib
Platforms:            darwin
License:              unknown
Maintainers:          nomaintainer@macports.org

Well, hmm, you certainly didn't want to install Quake 3 in the past. So, let's find out which ports actually depend on it, perhaps that might ring a bell:

%% port echo depends:physfs

fbg                             
libsdl_sound                    
lincity-ng                      
netpanzer

No, you didn't install netpanzer either, but - see there - fbg (The classic Falling Block Game!) was once on your agenda. But unfortunately that port was broken (see issue #24641) when you were trying to install it... Before you ran into the issue, of course, fbg's dependencies were resolved by MacPorts, which is why port physfs is still present on your system. Uff, great, confusion resolved. :-)

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 might be eventually as short as this:

%% port echo leaves

aalib                          @1.4rc5_4 
physfs                         @2.0.1_0 

Get rid of them by issuing the command:

%% sudo port uninstall leaves

--->  Deactivating physfs @2.0.1_0
--->  Cleaning physfs
--->  Uninstalling physfs @2.0.1_0
--->  Cleaning physfs
--->  Deactivating aalib @1.4rc5_4
--->  Uninstalling aalib @1.4rc5_4

Find all installed ports you previously set as requested using:

%% port installed requested

Checking the list of leaves from time to time will help to keep your system free of too much “garbage”. However, keep in mind that some ports may be dependencies only during the installation of a port (library dependencies, installation or configuration tools, etc.). So, be careful when removing seemingly unnecessary leaves, otherwise you'll see them being installed again and again.

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 whenever a port is installed, and can also be downloaded from a server.

%% sudo port -d archive logrotate

Debug output is shown below.

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

[ ... 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.tbz2 packaged
DEBUG: Executing archive_finish
--->  Archive for logrotate 3.7_0 packaged

Binary archive files are placed in ${prefix}/var/macports/software/. The archive file type is set in the macports.conf file. The default format is .tbz2; other options are: tar, tbz, tbz2, tgz, tlz, txz, 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.

%% sudo port pkg pstree

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

%% sudo port dmg pstree

You can also create a metapackage containing packages of a port and all its dependencies:

%% sudo port mpkg gimp2

Just as with a single package, a metapackage can also be wrapped in a .dmg.

%% sudo port mdmg gimp2

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.

%% sudo port rpm pstree

All packages are placed in a port's work directory, except for rpms that are placed under the regular “RPMS”:

%% port work pstree

%% rpm --eval %{_rpmdir}

# $Id$

PortSystem          1.0

name                rrdtool
version             1.2.23
categories          net
platforms           darwin
license             GPL
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/
master_sites        http://oss.oetiker.ch/rrdtool/pub/ \
                    ftp://ftp.pucpr.br/rrdtool/

checksums           rmd160  7bbfce4fecc2a8e1ca081169e70c1a298ab1b75a \
                    sha256  2829fcb7393bac85925090b286b1f9c3cd3fbbf8e7f35796ef4131322509aa53

depends_lib         path:bin/perl:perl5 \
                    port:tcl \
                    port:zlib

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

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 file to be patched. Patchfile filenames should uniquely distinguish the file and generally be of the form patch-<directory>-<filename>.diff, as shown in this example: patch-src-Makefile.in.diff.

You may use patch files that patch multiple files under these conditions:

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.

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


variant mysql5 { ... }

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

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}

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 as replaced_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; truncate-lines: t -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4
# $Id$

PortSystem          1.0
PortGroup           kde4    1.1

fetch.type          svn
svn.url             svn://anonsvn.kde.org/home/kde/trunk/extragear/office/skrooge
svn.revision        1215845

name                skrooge-devel
version             0.8.0-${svn.revision}

categories          kde finance
maintainers         mk pixilla openmaintainer
description         Skrooge
long_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           skrooge

platforms           darwin
license             GPL-3

homepage            http://skrooge.org
master_sites        http://skrooge.org/files/

livecheck.type      none

distname            skrooge

depends_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; truncate-lines: t -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4
# $Id$

PortSystem          1.0

name                skrooge-devel
svn.revision        1215845
version             0.8.0-${svn.revision}
revision            1

replaced_by         skrooge

categories          kde finance
maintainers         mk pixilla openmaintainer
description         Skrooge
long_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           darwin
license             GPL-3

homepage            http://skrooge.org

livecheck.type      none

pre-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-devel
Error: 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.log
Error: Status 1 encountered during processing.
To report a bug, see <http://guide.macports.org/#project.tickets>

# -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4; truncate-lines: t -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4
# $Id$
PortSystem          1.0
replaced_by         skrooge
PortGroup           obsolete 1.0
name                skrooge-devel
svn.revision        1215845
version             0.8.0-${svn.revision}
revision            2

If a port has to be removed from MacPorts one should consider the hints concerning replacing it by some alternative port given above. If there is no replacement for it, insert a pre-configure block as described there to alert the user about why the port is not allowed for installation anymore.

It is recommended to wait about a year before the port directory is actually being removed from MacPorts' Subversion repository.

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 standard configure, make, and make install steps. For applications that do not conform to this standard, 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 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 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.

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 OS X's versions 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:apache2

depends_build       port:libtool

depends_run         port:apache2 port:php5

File dependencies may be of three types: bin for programs, lib for libraries, and path for any installed file. File dependencies are specifed in the form: <type>:<filespec>:<port>.

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

For lib 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.

For path 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}. Since path 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 of bin and lib 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:xorg

depends_build       bin:glibtool:libtool

depends_run         path: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).

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

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.) as long as the script itself 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 for daemondo that 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/sh

case "$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 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 ...]

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/release/tarballs/ports/_resources/port1.0/group/

A sample listing follows:

%% ls -1 /opt/local/var/macports/sources/rsync.macports.org/release/tarballs/ports/_resources/port1.0/group/

archcheck-1.0.tcl
cmake-1.0.tcl
crossbinutils-1.0.tcl
gnustep-1.0.tcl
haskell-1.0.tcl
hocbinding-1.0.tcl
hunspelldict-1.0.tcl
kde4-1.0.tcl
kde4-1.1.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.

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 haskell simplifies the addition of Haskell 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.

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

PortGroup xcode allows for efficient porting of Xcode-based opensource software. A minimum Portfile for PortGroup xcode uses defaults for the configuration, build, and destroot phases. It also defines some values for Xcode-based software.

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.

macports.conf is the configuration file used to bootstrap the MacPorts system. This file is read by the port command and determines how it behaves.

Options locating other .conf files.

Options for MacPorts general operating characteristics.

Options for MacPorts Universal Binaries (+universal variant)

Options for StartupItems

Other options

This file enables rsync synchronization of the default ports tree with the MacPorts rsync server when either of the commands port selfupdate or port sync are run.

Default: rsync://rsync.macports.org/release/tarballs/ports.tar [default]

Optional local repositories are enabled using a file url: file:///path/to/localportsrepository

This optional file specifies any variants you'd like to be invoked globally. If a variant specified ib this file is not supported by a given Portfile, the variant is simply ignored.

Default: none

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.

Once you are logged into Trac, you may click New Ticket and you will be presented with a new ticket window shown in the graphic below. Follow the Trac ticket guidelines below to fill out the form. If you are reporting a failed port install and a log was mentioned in the error, please use the I have files to attach to this ticket checkbox to add that log file to the ticket.

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 any of the following apply:

If you wish to initiate the Port Abandonment protocol and volunteer as the new maintainer: