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. Some Portfile authors have used large epoch values that look like a date, but there is no reason to do so. The epoch is simply an unsigned integer, and the only requirement is that it never be decreased.
    Type: optional
    Default: 0
    Example:
        epoch 1

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.

notes
    Notes for setup and use of the port. This is shown after the port is activated and anytime the notes command is used; for example:

        port notes python26

    The advantage to using notes instead of ui_msg is that it can be queried after a port is installed but ui_msg is only printed during an install. Therefore notes is good for any information which may be needed anytime after an install.
    Type: optional
    Example:
        notes To fully complete your installation and make python \
           ${branch} the default, please run: \
           sudo port install python_select \
           sudo python_select ${name}

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

supported_archs
    The CPU architectures for which this port can be built. Archs currently supported by Mac OS X are: i386, ppc, ppc64, x86_64. If this option is not set, it is assumed that the port can build for all archs. If a port does not install any architecture-specific files, use the special value noarch.
    If the building architecture isn't among supported_archs, port fails with an error message except when building on x86_64 (or ppc64) and supported_archs contains i386 (or ppc). In this case, the port will be built in 32-bit mode.
    Type: optional
    Values: i386 x86_64 ppc ppc64 noarch
    Default: i386 x86_64 ppc ppc64
    Examples:
        supported_archs i386 x86_64
        supported_archs noarch

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, sha1, rmd160 or sha256. 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

macosx_deployment_target
    Value for MACOSX_DEPLOYMENT_TARGET environment variable when invoking the configure script.
    Type: optional
    Default: (current OS version)
    Example:
        macosx_deployment_target 10.8

use_parallel_build
    If set to yes (and the user has enabled buildmakejobs in macports.conf ), the port can be built using more than one job. Type: optional
    Default: yes
    Example:
        use_parallel_build no

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

copy_log_files path/to/logfile1 path/to/logfile2 ...
    Copy specific log files from the workdir to the main macports log dir
    Type: optional
    Example:
        copy_log_files config.log

conflicts
    Used to list ports which conflict with the one containing the conflicts declaration.
    Type: optional
    Default: none (empty)
    Example:
        conflicts cdrtools

replaced_by
    When a particular port is deprecated in favor of another, use replaced_by in the deprecated port and list the new one to be used.
    Type: optional
    Default: none (empty)
    Example:
        replaced_by xorg-renderproto

add_users
    Consists of a list of usernames and settings. At appropriate times during the port installation process, a user will be created for each username with the corresponding settings. Settings are of the form name=value. A setting applies to the username that appeared most recently before it in the list.

    Applicable options are: group, gid (may be used instead of group), passwd, realname, home, and shell.

    Type: optional
    Default: none (empty)
    Example:
        add_users squid group=squid realname=Squid\ Proxy home=${prefix}/var/squid

        add_users user1 group=mygroup user2 group=mygroup

installs_libs
    By default, it is assumed that ports may install libraries or headers that can be incorporated into their dependents. If this is not the case, set installs_libs to no. This means that this port's dependents need not check that it is installed for the same architectures as them; that it is permissible to distribute binaries of the dependents even if their licenses conflict with the license of this port; and that updates to this port can never result in broken dynamic linking in its dependents.
    Type: optional
    Default: none
    Example:
        installs_libs no

license_noconflict
    By default, it is assumed that ports may use libraries or headers from their dependencies and thus form a derivative work. A dependency with an incompatible license thus prevents the port from being distributed in binary form. If a dependency with an incompatible license is not used in such a way that a derivative work is formed, or should not prevent binary distribution for any other reason, add its name to this list.
    Type: optional
    Default: none
    Example:
        license_noconflict openssl
        license_noconflict readline gdbm

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.asroot
    Run the target with root privileges.
    Example:
        install.asroot yes

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:
        build.env CC="${configure.cc} [get_canonical_archflags]"

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 (e.g. "powerpc").
    Type: read-only

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

os.major
    Major version number of operating system (e.g. "7").
    Type: read-only

os.endian
    Endianness of the processor (e.g. "big").
    Type: read-only

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

os.subplatform
    Name of specific operating system variant (e.g. "macosx").
    Type: read-only

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

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

applications_dir
    Absolute path to the final location to install Mac OS X application bundles (.app directories).
    Type: read-only
    Default: /Applications/MacPorts

frameworks_dir
    Absolute path to the final location to install Mac OS X framework bundles (.framework directories).
    Type: read-only
    Default: ${prefix}/Library/Frameworks

DEPENDENCY OPTIONS
Port dependencies should refer to other MacPorts 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_fetch
    List of dependencies to check before fetch, checksum, extract, patch, configure, build, destroot, install, and package targets.
    Type: optional
    Example:
        depends_fetch port:mercurial

depends_extract
    List of dependencies to check before extract, patch, configure, build, destroot, install, and package targets.
    Type: optional
    Example:
        depends_extract path:bin/xz:xz

depends_build
    List of dependencies to check before configure, 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. Will be recorded in the registry as being required by the dependent port when it is installed.
    Type: optional
    Example:
        depends_run port:bash

depends_lib
    List of dependencies to check before configure, build, destroot, install, and package targets. Will be recorded in the registry as being required by the dependent port when it is installed.
    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: ${distname}${extract.suffix}
    Example:
        distfiles magicsource.tar.gz cluebat.tar.bz2

patchfiles
    List of patches to fetch and apply.
    Type: optional
    Example:
        patchfiles patch-Makefile.in.diff patch-main.c.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

use_xz
    Use xz.
    Sets extract.suffix to: .xz
    Sets extract.cmd to: xz
    Type: optional
    Example:
        use_xz yes

use_7z
    Use 7z (7zip).
    Sets extract.suffix to: .7z
    Sets extract.cmd to: 7za
    Type: optional
    Example:
        use_7z 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 https://www.example.com/svn/project/tags/1.2.3
    svn.url svn://www.example.com/svn/project/tags/1.2.3

svn.revision
    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.revision 37192
    svn.revision \{\"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

extract.mkdir
    Create the worksrcdir prior to extraction; useful for ports which extract directly into the current working directory instead of a subdirectory.
    Type: optional
    Default: no
    Example:
        extract.mkdir yes

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.optflags
    Flags to use for optimization.
    Type: optional
    Default: -Os
    Example:
        configure.optflags -O3

configure.cflags
    Flags to put in the CFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: ${configure.optflags}
    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: ${configure.optflags}

configure.objcflags
    Flags to put in the OBJCFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: ${configure.optflags}

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

configure.fflags
    Flags to put in the FFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: ${configure.optflags}

configure.f90flags
    Flags to put in the F90FLAGS environment variable when invoking the configure script.
    Type: optional
    Default: ${configure.optflags}

configure.fcflags
    Flags to put in the FCFLAGS environment variable when invoking the configure script.
    Type: optional
    Default: ${configure.optflags}

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

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 gcc-4.2 llvm-gcc-4.2 clang use the standard Xcode compiler suites, apple-gcc-4.0 apple-gcc-4.2 use Apple's gcc suite installed via MacPorts, macports-gcc-4.2 macports-gcc-4.3 macports-gcc-4.4 macports-gcc-4.5 macports-gcc-4.6 macports-gcc-4.7 macports-gcc-4.8 macports-llvm-gcc-4.2 use the vanilla compiler suites installed via MacPorts.
    Type: optional
    Values: gcc-3.3 gcc-4.0 gcc-4.2 llvm-gcc-4.2 clang apple-gcc-4.0 apple-gcc-4.2 macports-gcc-4.2 macports-gcc-4.3 macports-gcc-4.4 macports-gcc-4.5 macports-gcc-4.6 macports-gcc-4.7 macports-gcc-4.8 macports-llvm-gcc-4.2
    Example:
        configure.compiler llvm-gcc-4.2

configure.sdk_version
    Mac OS X SDK version to build against.
    Type: optional
    Default: (current OS version)
    Example:
        configure.sdk_version 10.8

  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 scons

build.type
    Defines which 'make' is required, either 'gnu' or 'bsd'. Can also choose 'xcode' (or the deprecated synonym 'pbx'), however you should generally use the xcode PortGroup rather than setting this directly. Sets build.cmd to either gnumake, bsdmake or xcodebuild 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 scons

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

startupitem.netchange
    Control whether the startupitem should be restarted when a change in the machine's network state is detected.
    Type: optional
    Default: no
    Values: yes|no
    Example:
        startupitem.netchange 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.type
    What kind of check to perform to figure out if the software has been updated. Can be freecode (uses the date_updated tag of the freecode 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 freecode
    Values: freecode sourceforge googlecode moddate regex regexm md5 none

livecheck.name
    Name of the project for live checks (used for freecode, sourceforge, and googlecode checks).
    Type: optional
    Default: ${name} or the sourceforge/freecode/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://freecode.com/projects/${livecheck.name}/releases.atom 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 one or more 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 port: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 code to be specified in a Portfile, for handling differences between platforms and versions of the same platform.

    platform platform [version] [arch] body The body is executed if the given platform/version/arch combination matches os.platform or os.subplatform and/or os.major and/or os.arch. The following examples are from the lang/php5, audio/flac and sysutils/getopt Portfiles respectively.
    Type: optional
    Example:
        platform darwin 10 { configure.env-append LIBS=-lresolv }

    Example:
        platform darwin i386 { configure.args-append --disable-asm-optimizations }

    Example:
        platform darwin 8 powerpc { configure.universal_ldflags-append -liconv }

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. Note that it is usually preferable to set the add_users option rather than call adduser directly, since it may need to be called in multiple places to handle all cases (e.g. installing from a binary archive).

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 [-W dir] 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.

    -W  Change to dir before working.

variant_isset variant
    Checks if the given variant is being built.

variant_set variant
    Set 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).

mkdtemp template
    Create a temporary directory using a template. See mkdtemp(3).

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

vercmp versionA versionB
    Compare two EVR-format versions for equality. The return value is like strcmp(), returning -1, 0, or 1 when versionA is earlier, equal to, or later than versionB, respectively. Note that some comparisons featuring floating-point notation may compare incorrectly, e.g. 2.101 is considered later than 2.2 (101 is larger than 2) which may be incorrect per some projects versioning methods (see ticket #11873).

    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>