PORTFILE(7)

NAME
Portfile - MacPorts description file reference

DESCRIPTION
A complete reference of all available Portfile variables and example syntax. Portfiles consist of valid TCL, allowing for simple key/value pair syntax as well as utilization of TCL's extensive functionality. Portfiles are encoded in UTF-8.

The .Nm MacPorts System uses a target dependency system based on a depends/provides model, allowing for targets to be registered and executed in the correct order based on their individual requirements.

A Portfile author needs to be aware of the various standard targets, the options that they require and the variables that both the targets and the port system provide.

PORTSYSTEM
Portfiles must begin with a PortSystem line that defines which version of the Portfile interpreter should be used.
Synopsis:
    PortSystem 1.0

MAIN VARIABLES
All ports are required to set certain variables.

name
    Full name of port.
    Type: required
    Example:
        name XFree86

version
    Upstream version of software.
    Type: required
    Example:
        version 4.2.1

epoch
    If a port's version numbering changes such that a newer version looks older than the previous version, the epoch should be increased. Often the epoch is formatted like a date.
    Type: optional
    Default: 0
    Example:
        epoch 20041231

description
    One line description of the software and what it does. To appear in the description, brackets and semi-colons need to be escaped with a backslash (i.e. they must be written as "\[", "\]" and "\;"). The escape sequences listed in re_syntax(n) may also be used, with the exception of \n, \r and \f.
    Type: required
    Example:
        description Dictionary Server Protocol (RFC2229) client

long_description
    A verbose description of the software and what it does. To appear in the description, brackets and semi-colons need to be escaped with a backslash (i.e. they must be written as "\[", "\]" and "\;"). The escape sequences listed in re_syntax(n) may also be used, with the exception of \n, \r and \f.
    Type: required
    Example:
        long_description The GNU Image Manipulation Program \
            (GIMP) is a powerful tool for the preparation and \
            manipulation of digital images. The GIMP provides \
            the user with a wide variety of image manipulation, \
            painting, processing, and rendering tools.

revision
    Local revision number of Portfile. Increment for port revisions which would change its installation in any way.
    Type: optional
    Default: 0
    Example:
        revision 1

categories
    Categories to which this port belongs.
    Type: required
    Example:
        categories spelling textproc

maintainers
    E-mail address(es) of port maintainer(s).
    Type: required
    Example:
        maintainers landonf@macports.org

platforms
    Declares which platforms are supported by the port.
    Type: required
    Values: darwin freebsd
    Example:
        platforms darwin

homepage
    Project homepage for the port.
    Type: required
    Example:
        http://wireshark.org

master_sites
    List of sites to fetch distfiles from or a predefined mirror site list. If set to a predefined mirror site, without a subdirectory being defined, the portname is used as the name of the subdirectory.
    Type: required
    Example:
        master_sites ftp://ftp.cdrom.com/pub/magic \
            sourceforge

worksrcdir
    Path to source directory relative to workpath.
    Type: optional
    Default: ${distname}
    Example:
        worksrcdir ${distname}-src-${version}

distname
    Name of distribution file, without the extract.suffix.
    Type: optional
    Default: ${name}-${version}
    Example:
        distname ${name}-${version}-src

    checksums filename type checksum [filename type checksum ...] List of checksums for the distfiles. The checksum type can currently be md5, rmd160 or sha1. The filename can be omitted if there is only one distfile.
    Type: required
    Example:
        checksums dictd-1.7.1.tar.gz md5 81317b86ea0a5df0163900ad2e6bb12c \
        	magic-words-1.7.1.tar.gz md5 897a005182928613eadd30c267ce9c5b

    Example (ledit 1.11):
        checksums md5 a2d38ba641682509c1e964ad699a9dd2 \
        	sha1 1fb6443b5fdf3c83787953f06282d256477c1288

    Example (ssldump 0.9b3):
        checksums md5 ac8c28fe87508d6bfb06344ec496b1dd \
        	sha1 a633a9a811a138eac5ed440d583473b644135ef5 \
        	rmd160 941cf8f2ef8459ec4f9ce65772e134505d46566

use_automake
    If set to yes, run the automake target to build any Makefile.in files for use by configure.
    Type: optional
    Default: no
    Example:
        use_automake yes

use_autoconf
    If set to yes, run the autoconf target to build any configure script required.
    Type: optional
    Default: no
    Example:
        use_autoconf yes

use_configure
    If set to yes, run the configure target to configure the build.
    Type: optional
    Default: yes
    Example:
        use_configure no

TARGET HOOKS
A number of hooks are available for customizing many of the standard targets that port(1) executes. The targets supporting these hooks are fetch, automake, autoconf, configure, build, destroot, and test. The hooks are:

target.dir
    Directory in which to run the target.
    Example:
        automake.dir src

target.env
    Change the environment the target is run in. This is often overridden on a per Portfile basis.
    Example:
        configure.env CPP=/usr/bin/cpp-4.0

target.pre_args
    Additional arguments passed before the main arguments.
    Example:
        extract.pre_args -cd

target.args
    Main arguments to pass to the target. This is often overridden on a per Portfile basis.
    Example:
        configure.args --enable-fooble

target.post_args
    Additional arguments passed after the main arguments.
    Example:
        extract.post_args | tar xf -

RUNTIME VARIABLES
Read-only access to the MacPorts configuration is provided.

prefix
    Install prefix
    Type: optional
    Default: /opt/local

libpath
    Location of ports-specific TCL libraries.
    Type: read-only

portpath
    Full path to the Portfile location.
    Type: read-only
    Default: work

workpath
    Full path to work directory.
    Type: read-only
    Default: ${portbuildpath}/work

worksrcpath
    Full path to working sources (where port has unpacked itself).
    Type: read-only
    Default: ${workpath}/${worksrcdir}

filesdir
    Path to port files relative to portpath.
    Type: read-only
    Default: files

filespath
    Full path to the port files location.
    Type: read-only
    Default: ${portpath}/${filesdir}

distpath
    Location to store downloaded distfiles.
    Type: read-only
    Default: ${sysportpath}/distfiles/${dist_subdir}/

os.arch
    Identifies hardware type (eg "powerpc").
    Type: read-only

os.version
    Version number of operating system (eg "7.0").
    Type: read-only

os.endian
    Endianness of the processor (eg "bigEndian").
    Type: read-only

os.platform
    Operating system name (eg "darwin").
    Type: read-only

install.user
    User for MacPorts installation (eg root)
    Type: read-only

install.group
    Group for MacPorts installation (eg wheel)
    Type: read-only

x11prefix
    Absolute path to X11 (eg /usr/X11R6)
    Type: read-only

DEPENDENCY OPTIONS
Port dependencies should refer to other MacPort ports whenever possible, therefore each dependency should be expressed in the format:

port:<port>

Where <port> represents the name of an existing MacPorts port. If satisfying a dependency with a MacPorts port is not practical and it is likely that a dependency must be met by an Apple optional install, then the alternative dependency format:

type:<filename>:<port>

may be used. Where type is "bin" if <filename> is a program, "lib" if it is a library, or "path" if it is a path to an installed file.
Example:
    lib:libX11.6:XFree86

depends_build
    List of dependencies to check before build, destroot, install, and package targets.
    Type: optional
    Example:
        depends_build port:autoconf

depends_run
    List of dependencies to check before destroot, install and package targets.
    Type: optional
    Example:
        depends_run port:bash

depends_lib
    List of dependencies to check before configure, build, destroot, install, and package targets.
    Type: optional
    Example:
        depends_lib port:libfetch

FETCH OPTIONS
Fetch all distribution files and patches.

master_sites.mirror_subdir
    Subdirectory to append to all mirror sites for any list specified in master_sites.
    Type: optional
    Default: ${name}
    Example:
        master_sites.mirror_subdir magic

patch_sites
    List of sites to fetch patchfiles from or a predefined mirror site list.
    Type: optional
    Default: ${master_sites}
    Example:
        patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches

patch_sites.mirror_subdir
    Subdirectory to append to all mirror sites for any list specified in patch_sites.
    Type: optional
    Default: ${name}
    Example:
        patch_sites.mirror_subdir magic

extract.suffix
    Suffix to append to distname.
    Type: optional
    Default: .tar.gz
    Example:
        extract.suffix .tgz

distfiles
    List of distribution files to fetch from master_sites.
    Type: optional
    Default: [suffix ${distname}]
    Example:
        distfiles magicsource.tar.gz cluebat.tar.bz2

patchfiles
    List of patches to fetch and apply.
    Type: optional
    Example:
        patchfiles japanese-widechar-fix.diff japanese-localization.diff

use_zip
    Use zip.
    Sets extract.suffix to: .zip
    Sets extract.cmd to: unzip
    Sets extract.pre_args to: -q
    Sets extract.post_args to: "-d ${workpath}"
    Type: optional
    Example:
        use_zip yes

use_bzip2
    Use bzip2.
    Sets extract.suffix to: .bz2
    Sets extract.cmd to: bzip2
    Type: optional
    Example:
        use_bzip2 yes

use_lzma
    Use lzma.
    Sets extract.suffix to: .lzma
    Sets extract.cmd to: lzma
    Type: optional
    Example:
        use_lzma yes

dist_subdir
    Create a sub-directory in distpath to store all fetched files.
    Type: optional
    Default: ${name}
    Example:
        dist_subdir vim${version}

  ADVANCED FETCH OPTIONS
Some mirrors require special options for a resource to be properly fetched.

fetch.user
    HTTP or FTP user to fetch the resource.
    Type: optional

fetch.password
    HTTP or FTP password to fetch the resource.
    Type: optional

fetch.use_epsv
    Whether to use EPSV command for FTP transfers.
    Type: optional
    Default: yes

fetch.ignore_sslcert
    Whether to ignore the host SSL certificate (for HTTPS).
    Type: optional
    Default: no

  FETCHING FROM CVS
As an alternative to fetching distribution files, pulling the sources from a CVS repository is supported. Use of CVS can give rise to non-reproducible builds, so it is strongly discouraged.

cvs.root
    Specify the address to a CVS repository from which to checkout files.
    Type: optional
    Default: none
    Example:
        cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs

cvs.tag
    Specify a CVS tag identifying the code to checkout.
    Type: optional
    Default none
    Example:
        cvs.tag HEAD

cvs.date
    A date that identifies the CVS code set to checkout.
    Type: optional
    Default none
    Example:
        cvs.date 12-April-2005

cvs.module
    A CVS module from which to check out the code.
    Type: optional
    Default none
    Example:
        cvs.module Sources

  FETCHING FROM SUBVERSION
As an alternative to fetching distribution files, pulling the sources from a subversion repository is supported. Use of subversion can give rise to non-reproducible builds, so it is strongly discouraged.

svn.url
    Specify the url from which to fetch files.
    Type: required
    Default: none
    Example:
        svn.url http://www.domain.com/svn-repo/mydirectory
    svn.url svn://www.domain.com/svn-repo/mydirectory

svn.tag
    Specify a tag from which svn should fetch files. This corresponds to the -r option to the svn cli. Note that you will need to use backslashes to escape characters that have meaning to the Tcl interpreter, such as braces and double quotes.
    Type: optional
    Default: none
    Example:
        svn.tag 37192
    svn.tag \{\"2006-02-17 15:30 +0230\"

  FETCHING FROM GIT
As an alternative to fetching distribution files, pulling the sources from a git repository is supported. Use of git can give rise to non-reproducible builds, so it is strongly discouraged.

git.url
    Specify the url from which to fetch files
    Type: required
    Default: none
    Example:
        git.url git://git.kernel.org/pub/scm/git/git.git
    git.url http://www.kernel.org/pub/scm/git/git.git

git.branch
    Specify a branch (or other commit-ish) that git should checkout. Note that any branch besides HEAD should be prefixed by origin/.
    Type: optional
    Default: none
    Example:
        git.branch 72bf1c8
    git.branch origin/next

EXTRACT OPTIONS
Extract all compressed/archived files.

extract.only
    List of files to extract into workpath.
    Type: optional
    Default: ${distfiles}
    Example:
        extract.only worksrc-1.4.4.tar.gz

extract.cmd
    Command to perform the extraction.
    Type: optional
    Default: gzip
    Example:
        extract.cmd bzip2

CONFIGURE OPTIONS
MacPorts provide special support for configure flags (CFLAGS, LDFLAGS, CPPFLAGS, CXXFLAGS, CC, CXX, CPP, FC, F77, F90). Please note that the previous way to alter these flags (using configure.env) may become deprecated at some point. The following options are defined:

configure.cflags
    Flags to put in the CFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -O2
    Example:
        configure.cflags-append -DHAS_LRINTF

configure.cppflags
    Flags to put in the CPPFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -I${prefix}/include

configure.cxxflags
    Flags to put in the CXXFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -O2

configure.objcflags
    Flags to put in the OBJCFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -O2

configure.ldflags
    Flags to put in the LDFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -L${prefix}/lib

configure.fflags
    Flags to put in the FFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -O2

configure.f90flags
    Flags to put in the F90FLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -O2

configure.fcflags
    Flags to put in the FCFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -O2

configure.classpath
    Flags to put in the CLASSPATH environment variable when invoking the configure script.
    Type: optional

configure.macosx_deployment_target
    Flags to put in the MACOSX_DEPLOYMENT_TARGET environment variable when invoking the configure script.
    Type: optional
    Example:
        configure.macosx_deployment_target 10.4

configure.cc
    C-compiler to put in the CC environment variable when invoking the configure script.
    Type: optional
    Example:
        configure.cc /usr/bin/gcc

configure.cpp
    C-preprocessor to put in the CPP environment variable when invoking the configure script.
    Type: optional

configure.cxx
    C++-compiler to put in the CXX environment variable when invoking the configure script.
    Type: optional

configure.objc
    Objective-C-compiler to put in the OBJC environment variable when invoking the configure script.
    Type: optional
    Example:
        configure.objc ${prefix}/bin/gcc-mp-4.1

configure.fc
    Fortran-compiler to put in the FC environment variable when invoking the configure script.
    Type: optional

configure.f77
    Fortran-77-compiler to put in the F77 environment variable when invoking the configure script.
    Type: optional

configure.f90
    Fortran-90-compiler to put in the F90 environment variable when invoking the configure script.
    Type: optional

configure.javac
    Java compiler to put in the JAVAC environment variable when invoking the configure script.
    Type: optional

configure.compiler
    Selects a complete compiler suite to use. This option will override the compiler environment variable for all compilers the named suite features. Please note that this option will intentionally not set any dependencies on the selected compiler suite! gcc-3.3 gcc-4.0 use the standard system compiler suites, apple-gcc-3.3 apple-gcc-4.0 use Apple's gcc suite installed via MacPorts, macports-gcc-3.3 macports-gcc-3.4 macports-gcc-4.0 macports-gcc-4.1 macports-gcc-4.2 macports-gcc-4.3 use the vanilla gcc installed via MacPorts.
    Type: optional
    Values: gcc-3.3 gcc-4.0 apple-gcc-3.3 apple-gcc-4.0 macports-gcc-3.3 macports-gcc-3.4 macports-gcc-4.0 macports-gcc-4.1 macports-gcc-4.2 macports-gcc-4.3
    Example:
        configure.compiler gcc-4.0

  UNIVERSAL TARGET HOOKS
For universal builds of configure-based ports, we also define specific target hooks. These can be overridden for specific ports. Please note that these hooks are used by the default universal variant and redefining the variant will make them useless.

configure.universal_args
    Arguments appended to the configure script to build the port universal.
    Type: optional
    Default: --disable-dependency-tracking

configure.universal_cflags
    Additional flags to put in the CFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc

configure.universal_cppflags
    Additional flags to put in the CPPFLAGS environment variable when invoking the configure script.
    Type: optional

configure.universal_cxxflags
    Additional flags to put in the CXXFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc

configure.universal_ldflags
    Additional flags to put in the LDFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: -arch i386 -arch ppc

BUILD OPTIONS
Execute necessary build commands.

build.cmd
    Make command to run relative to worksrcdir.
    Type: optional
    Default: make
    Example:
        build.cmd pbxbuild

build.type
    Defines which 'make' is required, either 'gnu' or 'bsd'. Sets build.cmd to either gnumake or bsdmake accordingly.
    Type: optional
    Default: gnu
    Example:
        build.type bsd

build.target
    Target passed to build.cmd.
    Type: optional
    Default: all
    Example:
        build.target all-src

DESTROOT OPTIONS
Execute necessary commands to install into a temporary destination root ("destroot") staging area.

destroot.cmd
    Install command to run relative to worksrcdir.
    Type: optional
    Default: ${build.cmd}
    Example:
        destroot.cmd pbxbuild

destroot.type
    Defines which 'make' is required, either 'gnu' or 'bsd'. Sets destroot.cmd to either gnumake or bsdmake accordingly.
    Type: optional
    Default: ${build.type}
    Example:
        destroot.type gnu

destroot.destdir
    Arguments passed to destroot.cmd in order to install correctly into the destroot.
    Type: optional
    Default: DESTDIR=${destroot}
    Example:
        destroot.destdir prefix=${destroot}${prefix}

destroot.target
    Install target to pass to destroot.cmd.
    Type: optional
    Default: install
    Example:
        destroot.target install-src

destroot.umask
    Umask to use during destroot.
    Type: optional
    Default: 022
    Example:
        destroot.umask 002

destroot.keepdirs
    List of directories that should not be pruned if empty upon destroot completion.
    Type: optional
    Example:
        destroot.keepdirs ${destroot}${prefix}/var/log/mysql

destroot.violate_mtree
    Indicates if a port will violate the common directory structure. Enables or disables tests for violations of mtree (e. g. non-standard directories in ${prefix}). The standard mtree can be found in porthier(7).
    Type: optional
    Values: yes no
    Default: no

TEST OPTIONS
Execute commands to run test suites bundled with a port.

test.run
    Enable running test suites bundled with a port.
    Type: optional
    Example:
        test.run yes

test.cmd
    Test command to run relative to worksrcdir.
    Type: optional
    Default: ${build.cmd}
    Example:
        test.cmd checks.sh

test.target
    Test target to pass to test.cmd.
    Type: optional
    Default: test
    Example:
        test.target checks

STARTUPITEM OPTIONS
If a port needs to run on system startup, it can use MacPorts startupitem keywords to install native OS X startup scripts. Startup scripts require user interaction after port installation to activate them and instructions are given during port installs.

startupitem.create
    Choose whether or not to generate a startup item.
    Type: optional
    Default: no
    Values: yes no
    Example:
        startupitem.create yes

startupitem.type
    Select the type of startupitem to generate. By default, a startupitem will be generated that is of the appropriate type for the OS. For instance, launchd is used on system 10.4, while SystemStarter is used on prior Mac OS X systems. A global default may be specified with the startupitem_type preference in ports.conf.
    Type: optional
    Default: default
    Values: SystemStarter launchd default rcNG
    Example
        startupitem.type launchd

startupitem.name
    Displayed name of the startup item.
    Type: required
    Example:
        startupitem.name OpenSSH

startupitem.executable
    The name of the daemon to be run in the background. This is the preferred type of startup item rather than any of startupitem.init, startupitem.start, startupitem.stop, or startupitem.restart, and may not be used together with any of these options. This option may contain multiple arguments, but they must be appropriate for a call to exec; they may not contain arbitrary shell code.
    Type: optional
    Values: /path/to/executable <args>
    Example:
        startupitem.executable ${prefix}/bin/wonka

startupitem.init
    Shell code that will be executed prior to any of the options startupitem.start, startupitem.stop and startupitem.restart.
    Type: optional
    Values: sh code
    Example:
        startupitem.init FOO=start

startupitem.start
    Shell code executed to start the daemon.
    Type: optional
    Values: sh code
    Example:
        startupitem.start ${prefix}/share/mysql/mysql.server start

startupitem.stop
    Shell code executed to stop the daemon.
    Type: optional
    Values: sh code
    Example:
        startupitem.stop ${prefix}/share/mysql/mysql.server stop

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.
    Type: optional
    Values: sh code
    Example:
        startupitem.restart ${prefix}/share/mysql/mysql.server restart

startupitem.pidfile
    Specification for pidfile handling. This is particularly useful in conjunction with the startupitem.executable key, because it is important that the startupitem know how to track the executable. This 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).
    Type: optional
    Default: none ${prefix}/var/run/${name}.pid
    Values: none|auto|manual|clean [/path/to/pidfile]
    Example:
        startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile

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.
    Type: optional
    Default: /dev/null
    Values: path
    Example:
        startupitem.logfile ${prefix}/var/log/mydaemon.log

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.
    Type: optional
    Default: no
    Values: yes|no
    Example:
        startupitem.logevents yes

DISTCHECK AND LIVECHECK OPTIONS
MacPorts can automatically check if the software has been updated since the Portfile was modified and if some external changes require an update to the Portfile. This helps maintainers have up-to-date and working Portfiles.
Two checks are available. With distcheck, MacPorts can check that the distfile(s) are still downloadable and did not change since the portfile was modified. With livecheck, MacPorts can query a resource to determine if a newer version of the software is available.

distcheck.check
    This option can be used to disable distcheck. It specifies what kind of check should be performed on distfiles: moddate (check if the Portfile is older than the distfile) or none (no check).
    Type: optional
    Default: moddate
    Values: moddate none

livecheck.check
    What kind of check to perform to figure out if the software has been updated. Can be freshmeat (uses the date_updated tag of the freshmeat XML file), sourceforge (uses the version of the latest file release of the project), googlecode (uses the version of the latest file release of the project), moddate (uses the modification date of some URL resource), regex (retrieve the version by applying a regex to some URL resource), regexm (retrieve the version by applying a multi-line regex to some URL resource), md5 (compares the md5 sum of some URL resource) or none (no check).
    Type: optional
    Default: sourceforge or googlecode if the master_sites is one of these, else freshmeat
    Values: freshmeat sourceforge googlecode moddate regex regexm md5 none

livecheck.name
    Name of the project for live checks (used for freshmeat, sourceforge, and googlecode checks).
    Type: optional
    Default: ${name} or the sourceforge/freshmeat/googlecode project name if it can be guessed by looking at the master_sites.

livecheck.distname
    Name of the file release (used for sourceforge and googlecode checks). For sourceforge releases use the name of the package release. For googlecode releases use the name of the file download, including extension. Replace the version part of the name with "(.*)".
    Type: optional
    Default: ${livecheck.name} for sourceforge projects or the first entry in ${distfiles} for googlecode projects

livecheck.version
    Version of the project for live checks (used for regex-based checks).
    Type: optional
    Default: ${version}

livecheck.url
    URL to query for the check.
    Type: optional
    Default: ${homepage} or http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml or http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name} or http://code.google.com/p/${livecheck.name}/downloads/list

livecheck.regex
    Regular expression to parse the resource for regex checks. Be sure to use a regular expression grouping around the version component.
    Type: optional

livecheck.md5
    md5 sum to use for md5 comparison.
    Type: optional

VARIANT OPTIONS
MacPorts allows for conditional modification to be specified in a Portfile, allowing for user-customization of a software's build-time settings.

    variant [requires variant] [conflicts variant] [description description] The value is usually a TCL script which modifies other port's Portfile variables. Dependencies and conflicts with other variants in the same port can be expressed with requires and conflicts. description provides a means to supply a description of the variant for the user.
    Type: optional
    Example: Add a "gnome" variant to a port.
        variant gnome requires glib { configure.args-append --with-gnome \
            depends_lib-append lib:gnome-session:gnome-session }

default_variants
    If variants are defined, then the default_variants value lists which variants are enabled by default.
    Type: optional
    Example:
        default_variants +ssl +tcpd

universal_variant
    When using MacPorts on Mac OS X, a universal variant is defined and the default behavior is to configure ports with universal flags (see the UNIVERSAL TARGET HOOKS section above). The variant can be overridden if the default code does not work. It can also be suppressed if having a universal variant for the port does not make sense. To suppress it, use the universal_variant option.
    Type: optional
    Default: yes
    Example:
        universal_variant no

PLATFORM OPTIONS
MacPorts allows for platform-specific conditional modification to be specified in a Portfile, much like variants, for handling differences between platforms and versions of the same platform.

    platform platform [version] [arch] The platform key is used to begin the darwin platform definitions as shown in the examples from the databases/db4 and devel/libidl1 Portfiles respectively.
    Type: optional
    Example:
        platform darwin 6 { configure.args-append   --enable-tcl \
                --with-tcl=/System/Library/Tcl/8.3 }

    Example:
        platform darwin powerpc { configure.args-append \
                --host=${os.arch}-apple-rhapsody${os.version} }
        platform darwin i386 { configure.args-append \
                --host=i386-gnu-rhapsody${os.version} }

PORTGROUP
To factorize the work with similar ports, MacPorts provides the notion of PortGroup that can be used to load definitions for a given class or group of ports. See portgroup(7) for more details on the various PortGroup classes.

TCL EXTENSIONS
A number of TCL extensions are available for use in Portfiles.

    xinstall [-c] [-B suffix] [-b] [-C] [-f flags] [-g group] [-M] [-m mode] [-o owner] [-p] [-S] [-s] [-W dir] [file ...] destination
    xinstall -d [-B suffix] [-b] [-C] [-f flags] [-g group] [-M] [-m mode] [-o owner] [-p] [-S] [-s] [-W dir] directory Install file(s) to a target file or directory. The options are intended to be compatible with install(1):

    -b  Backup any existing files with an .old extension.

    -B  Specify a different backup suffix for the -b flag.

    -c  Install files (this is the default).

    -C  Only copy a file if it is different.

    -d  Create directories, including (if necessary) parent directories.

    -f  Specify target flags, see chflags(1) for details.

    -g  Specify the group.

    -M  Disable use of mmap(2).

    -m  Specify an alternate mode. The default is 0755. See chmod(1) for defails.

    -p  Preserve the modification time.

    -S  Copy safely, using a temporary file.

    -s  Strip binaries using strip(1).

    -W  Change to dir before working.

    fs-traverse [-depth] [-ignoreErrors] varname target-list body Traverse the filesystem hierarchy rooted in each element of target-list and execute body for each found file/directory. varname is set to the path of the file/directory. If break is called during execution, the filesystem traversal is stopped. If continue is called during execution, the current file and any children are skipped and traversal continues with the next file/directory.

    -depth
        Equivalent to the -d switch to find(1). Please note that using -depth means you cannot prune a directory with continue as it will be processed after its children.

    -ignoreErrors
        Causes fs-traverse to ignore any permissions/read errors encountered during processing.

    If fs-traverse is called directly on a symbolic link, the link will be followed. All other links encountered during traversal will not be followed.

    fs-traverse will not descend into directories that have a different device number than the root of the descent.

    If you remove the current directory during traversal, be aware that you must call continue to inform fs-traverse that the directory should not be descended into.

    curl fetch url file Fetch a resource at url and save it to file.

    curl isnewer url date Determine if resource at url is newer than date (expressed in seconds since epoch).

    adduser username [uid=uid] [gid=gid] [passwd=passwd] [realname=realname] [home=home] [shell=shell] Add a new local user to the system with the specified uid, gid, password, real name, home directory and login shell.

existsuser username
    Check if a local user exists.

nextuid
    Returns the highest used uid plus one.

    addgroup group [gid=gid] [passwd=passwd] [realname=realname] [users=users] Add a new local group to the system, with the specified gid, password, real name, and with a list users as members.

existsgroup group
    Check if a local group exists and return the corresponding gid. This can be used with adduser:
        addgroup foo
        adduser foo gid=[existsgroup foo]

nextgid
    Returns the highest used gid plus one.

    reinplace [-E] regex file ... Provide in-place sed(1) like editing of a file. The -E flag does the same thing as in sed(1)
    Example:
        reinplace s|/usr/local|${prefix}|g doc/manpage.1

file
    Standard TCL command to manipulate file names and attributes, recommended if you wish to preserve Mac OS resource forks when destrooting ports on Mac OS X 10.3.x and Mac OS X 10.4.x . Use xinstall to also preserve Extended Attributes (i.e. Access Control Lists). See file(n) for more information on this command.

copy
    Built-in shorthand alternative to "file copy".

move
    Built-in shorthand alternative to "file rename".

delete file ...
    Deletes each of the given files/directories. Behaves similarly to file delete -force except that file delete -force will fail to delete directories properly on 10.3 systems.

touch
    Built-in command mimicking the BSD touch command.

ln
    Built-in command mimicking the BSD ln command.

system commandline
    Execute a program. See system(3). For calls to install(1) please use xinstall. For calls to mv(1), cp(1), rm(1) or similar, please use the built-in commands or file if they don't meet your requirements.

variant_isset variant
    Checks if the given variant is being built.

variant_set variant
    Set the given variant.

variant_unset variant
    Unset the given variant.

variable-append item
    Append item to the variable.
    Example:
        configure.args-append --with-gnomedb

variable-delete item
    Delete item from the variable.
    Example:
        configure.args-delete --with-gnomedb

readdir directory
    Return the list of elements in a directory, excluding ~. and ...

strsed string pattern
    Perform ed(1)/ tr(1)-like search, replace, and transliteration on a string.

mktemp template
    Create a temporary file using a template. See mktemp(3).

mkstemp template
    Create a temporary file securely using a template. See mkstemp(3).

md5 file ...
    Compute the MD5 hashes of the file(s).

rpm-vercomp versionA versionB
    Compare two RPM-format versions for equality.

sudo password command ...
    Execute command using sudo with the provided password.

    lpush varName [value ...] Treats the variable given by varName as a list and appends each of the value arguments to that list as a separate element. If varName doesn't exist, it is created as a list with elements given by the value arguments. Really just an alias for lappend(n).

lpop varName
    Removes the last element from the list given by varName and returns it. If there are no elements in the list, the empty string is returned. If varName doesn't exist, an exception is raised.

    lunshift varName [value ...] Treats the variable given by varName as a list and prepends each of the value arguments to that list as a separate element. If varName doesn't exist, it is created as a list with elements given by the value arguments.

lshift varName
    Removes the first element from the list given by varName and returns it. If there are no elements in the list, the empty string is returned. If varName doesn't exist, an exception is raised.

    ldindex varName [index ...] Treats the variable given by varName as a list and removes the element pointed to by the sequence of index arguments and returns it. If no index arguments are provided, varName is set to the empty string and the entire former value is returned. Has the same usage semantics as lindex(n).

    try body [ catch { type-list [ecvar] [msgvar] [infovar] } body ...] [finally body] Implements a try-catch-finally block as defined in TIP #89.
    Example: Basic try-finally construct.
        try {
            set fd [open $file r]
            # do stuff here
        } finally {
            close $fd
        }

    Example: Basic try-catch construct
        try {
            set result [expr $num / $div]
        } catch {{ARITH DIVZERO}} {
            set result -1
        }

    Example: Basic try with multiple catches construct
        try {
            set fd [open $file r]
            # do stuff here
        } catch {{POSIX ENOENT} {} msgvar} {
            puts stderr $msgvar
        } catch {*} {
            puts stderr "An error occurred while processing the file"
            close $fd
            throw
        }

    throw [type] [message] [info] Throws an exception. If given arguments, works just like error message info type. If called with no arguments from within a catch block, re-throws the caught exception.

ui_debug message
ui_error message
ui_info message
ui_msg message
ui_warn message
    Display a message to the user, at various different levels.
    Example:
        ui_msg Add each user to the system using the clamav command

SEE ALSO
port(1), macports.conf(5), portgroup(7), portstyle(7), porthier(7), file(n)

AUTHORS
Landon Fuller <landonf@macports.org> Juan Manuel Palacios <jmpp@macports.org> Mark Duling <markd@macports.org> Kevin Van Vechten <kevin@opendarwin.org> Jordan K. Hubbard <jkh@macports.org> Chris Ridd <cjr@opendarwin.org> Kevin Ballard <eridius@macports.org> Markus W. Weissmann <mww@macports.org>