Portfile Reference
This chapter serves as a reference for the major elements of a
Portfile: port phases, variants, StartupItems,
variables, keywords, and Tcl primitives.
Port Phases
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 override or
eliminate the default behavior, or augment it using pre- and/or post-
phases as shown in the section "Portfile Development".
Fetch
Overview: Fetch the ${distfiles} from
${master_sites} and place it in
${prefix}/var/macports/distfiles.
Checksum
Overview: Compare ${checksums} specified in a
Portfile to the checksums of the fetched
${distfiles}.
Extract
Overview: Unzip and untar the ${distfiles} into
the path ${prefix}/var/macports/build/..../work
Patch
Overview: Apply optional patch files
specified in ${patchfiles} to modify a port's source
code file(s).
Details: Patch files are made using the diff command, and
MacPorts patches should be created as unified
diffs.
Configure
Overview: Execute the command "configure" in
${workpath}.
Build
Overview: Execute the command "make" in
${workpath}.
Destroot
Overview: Execute the command make install
DESTDIR=${destroot} in ${workpath}.
Details: Understanding the destroot phase is critical to
understanding MacPorts, because, unlike some port systems, MacPorts
"stages" an installation into an intermediate location —not the final
file destination. There are two main advantages to this method.
A port's files may be cleanly uninstalled because all files
and locations are tracked.
Since a port's files are not installed into MacPorts directory
structure until an activation phase, a port may be deactivated
through MacPorts to allow activation of a different version of the
same port, thus allowing two versions of a port to be present,
though not both active, on a given host.
The $(DESTDIR) variable must be supported in
an application's Makefile for the MacPorts destroot phase to work
properly. Urge developers to fully support
$(DESTDIR) in their Makefiles.
Archive
Overview: Use tar to create a tarball of a port's destrooted files
and copy it to
${prefix}/var/macports/packages/.
Install
Overview: Copy a port's destrooted files into
${prefix}/var/macports/software. See "Port Images"
in section "MacPorts Internals" for details.
Activate
Overview: Set hardlinks pointing
to ${prefix}/var/macports/software to point to ${prefix}.
Variants
Variants are a way for port authors to provide options that may be
invoked at install time. They are declared in a
Portfile's global section using the "variant" keyword
and may provide a description.
Append / Delete Keywords
The most common use for a variant is to add or remove
dependencies, configure arguments, and build arguments from the global
Portfile section. In the example below, the global
configure argument --without-x11 is removed and 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
}
Variant Actions in Port Phases
If a variant requires options in addition to those provided by
keywords using -append and/or -delete, or actions that would normally
take place within a port installation phase or its pre- and post-
phases, 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}
}
}
Default Variants
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
The default_variant keyword may only be used in the global
Portfile section.
StartupItems
StartupItems are keywords that create Mac OS X LaunchDaemon startup
scripts. To create these startup scripts for a port, choose from the
following keywords.
startupitem.create
This triggers the creation of a StartupItem, defaults to
"no".
startupitem.name
Sets the name for the StartupItem, defaults to
${portname}.
startupitem.executable
The name of the daemon to be run in the background. This is
the preferred type of startup item and may not be used together
with any other startupitem. This option may contain multiple
arguments, but they must be appropriate for a call to exec; they
may not contain arbitrary shell code.
startupitem.init
Shell code that will be executed prior to any of the options
startupitem.start, startupitem.stop and startupitem.restart.
Typically a startup script is specified.
startupitem.start
Shell code executed to start the daemon.
startupitem.stop
Shell code executed to stop the daemon.
startupitem.restart
Shell code executed to restart the daemon. In the absence of
this key, the daemon will be restarted by taking the stop action,
followed by taking the start action.
startupitem.pidfile
Specification for pidfile handling. It is useful in
conjunction with the startupitem.executable key, because it is
important that the startupitem know how to track the executable.
This keyword specifies whether the daemon generates its own
pidfile (auto), whether it generates its own but forgets to delete
it, so that the startupitem should delete it (clean), or whether
it never generates one, in which case the startupitem should
manage the pidfile on its own (manual), or whether no pidfile
should be used at all (none).
startupitem.logfile
Path to a logfile for logging events about the lifetime of
the startupitem. Depending on the type of startupitem, and the
manner in which it is started, standard output from the daemon may
also be directed to the logfile.
startupitem.logevents
Control whether or not to log events to the log file. If
logevents is set, events with timestamps are logged to the
logfile.
Variables
This section describes the MacPorts preset variables that may be
used within Portfiles.
General
These are the variables available to any
Portfile.
prefix
Installation prefix, set in the system-wide configuration
file ${prefix}/etc/macports/macports.conf
—may be overridden on a per port basis. For example, aqua
applications are installed in
/Applications/MacPorts.
binpath
Default PATH to use in finding executables. Read
only.
libpath
Path to the MacPorts TCL libraries. Read only.
portpath
Path to the directory containing the downloaded
Portfiles. Read only.
filesdir
Path to port files relative to
${portpath}. Read only.
workpath
Full path to work directory. Read only.
worksrcpath
Full path to extracted source code. Equivalent to
${workpath}/${worksrcdir}.
destroot
Full path into which software will be destrooted.
Equivalent to ${workpath}/destroot. Read
only.
distpath
Location to store downloaded distfiles. Read only.
os.platform
Identifies platform type (ie, "darwin", "freebsd", etc).
Read only.
os.arch
Identifies hardware type (ie, "powerpc", "intel"). Read
only.
os.version
The version number of the host operating system (ie "8.0"
for Darwin 8.0). Read only.
os.major
The major version number of the host operating system (ie
"8" for Darwin 8.0). Read only.
PortGroup Variables
In addition to the general Portfile type for
standard Unix applications and libraries, there are six optional
PortGroup types that provide special Portfile
handling to make creating a Portfile easier.
perl5
python24 and python25
ruby
xcode
gnustep
zope
Some PortGroups provide additional variables when they are
declared within a Portfile. The additional variables provided by
PortGroups perl5, python, and ruby are listed below. You may view the
port Tcl code for each group in the directory
${prefix}/share/macports/resources/port1.0/group.
PortGroup perl5
Description: The variables available to a
Portfile when the PortGroup
perl5 keyword is declared.
perl5.version
The MacPorts Perl version.
perl5.bin
The Perl binary path (ie,
${prefix}/bin/perl).
perl5.lib
Path to the Perl vendor directory.
perl5.archlib
Path to the Perl architecture-dependent modules
directory.
PortGroup python2x
Description: The variables available to a
Portfile when the PortGroup
python2x keyword is declared.
python.bin
The MacPorts Python binary location.
python.lib
The Python dynamic library and path (ie,
${prefix}/lib/libpython2.x.dylib).
python.include
Path to the Python include directory.
python.pkgd
Path to the Python site-packages directory. (ie,
${prefix}/lib/python2.4/site-packages).
PortGroup ruby
Description: The variables available to a
Portfile when the PortGroup
ruby keyword is declared.
ruby.version
The MacPorts Ruby version.
ruby.bin
The Ruby binary location.
ruby.lib
Path to the Ruby vendorlibdir directory (ie,
${prefix}/lib/ruby/vendor_ruby/${ruby.version})
ruby.archlib
Path to the Ruby vendor archdir (ie,
${ruby.lib}/${ruby.arch}).
Keywords
MacPorts keywords are used to specify required or optional items for
a Portfile or to override default options when
necessary. All the keywords are to be used within the global section of a
Portfile. The keywords listed below in category
"global" specify information for a port as a whole, whereas the keywords
listed under a port phase specify information to be used during a
particular installation phase.
Remember that default port installation phase behavior is performed
by the MacPorts base, so that Portfile phase
declarations need only be defined for non-default behavior. But keywords
for port phases affect installation phase behavior, whether it is
performed by the MacPorts base code or defined using
Portfile phase declarations.
Global
Global keywords.
name
Port name.
version
Port version.
categories
Port category(s).
maintainers
Port maintainer(s).
description
Short description.
long_description
Long description.
homepage
Port application's homepage.
platforms
Platform(s) supported.
master_sites
Download site(s) for the distribution files.
checksums
Checksum(s) of the distribution files.
depends_lib
depends_build
depends_run
Fetch
Fetch phase keywords.
fetch.keyword1
Description fetch keyword 1.
Checksum
Checksum phase keywords.
checksum.keyword1
Description checksum keyword 1.
Extract
Extract phase keywords.
extract.keyword1
Description extract keyword 1.
Patch
Patch phase keywords.
patch.keyword1
Description patch keyword1.
Configuration
Configuration phase keywords. Avoid using keywords with defaults
defined or you will overwrite the default variables.
configure.env
Configure environment variables.
Defaults: CFLAGS=-I${prefix}/include
LDFLAGS=-L${prefix}/lib
configure.cflags-append
Set additional CFLAGS to be added to the variable
defaults.
configure.ldflags-append
Set additional LDFLAGS to be added to the variable
defaults.
Build
Build phase keywords.
build.keyword1
Description build.keyword 1.
Destroot
Destroot phase keywords.
destroot.keyword1
Description destroot keyword1.
Install
Install phase keywords.
install.keyword1
Description install.keyword 1.
Tcl Primitives
A MacPorts Portfile is a Tcl script, so it may
contain Tcl code anywhere within it, whether in the global section or a
phase. The Tcl primitives listed below are defined within the MacPorts
base code for use in Portfiles.
reinplace
Description reinplace.
xinstall
Description xinstall.
file copy
Description file copy.
file delete
Description file delete.