wiki:eborisch/man_portfile

UNOFFICIAL VERSION

Output of man portfile; Here so Google can digest it. Check your local man portfile for up-to-date information.


 PORTFILE(7)          BSD Miscellaneous Information Manual          PORTFILE(7)

NAME
     Portfile -- MacPorts description file reference

DESCRIPTION
     A complete reference of all available Portfile variables and example syn-
     tax.  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 MacPorts System uses a target dependency system based on a
     depends/provides model, allowing for targets to be registered and exe-
     cuted 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.

     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

     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

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

     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: no
         Example:
               use_parallel_build yes

     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 depen-
         dents need not check that it is installed for the same architectures
         as them; that it is permissible to distribute binaries of the depen-
         dents 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

TARGET HOOKS
     A number of hooks are available for customizing many of the standard tar-
     gets 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:
               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 (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 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 satis-
     fying 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 port:xz-devel

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

     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 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 back-
         slashes to escape characters that have meaning to the Tcl inter-
         preter, 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

     extract.mkdir
         Create the worksrcdir prior to extraction; useful for ports which
         extract directly into the current working directory instead of a sub-
         directory.
         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 depre-
     cated at some point. The following options are defined:

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

     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
         use the standard system compiler suites, llvm-gcc-4.2 clang use the
         newer, non-default compilers installed by Xcode, apple-gcc-3.3
         apple-gcc-4.0 apple-gcc-4.2 use Apple's gcc suite installed via Mac-
         Ports, macports-gcc-3.3 macports-gcc-3.4 macports-gcc-4.0
         macports-gcc-4.1 macports-gcc-4.2 macports-gcc-4.3 macports-gcc-4.4
         macports-gcc-4.5 use the vanilla gcc installed via MacPorts.
         Type: optional
         Values: gcc-3.3 gcc-4.0 gcc-4.2 llvm-gcc-4.2 clang apple-gcc-3.3
         apple-gcc-4.0 apple-gcc-4.2 macports-gcc-3.3 macports-gcc-3.4
         macports-gcc-4.0 macports-gcc-4.1 macports-gcc-4.2 macports-gcc-4.3
         macports-gcc-4.4 macports-gcc-4.5
         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 univer-
         sal.
         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 instruc-
     tions 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 pre-
         ferred 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 con-
         tain 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 star-
         tupitem.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 impor-
         tant 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 star-
         tupitem. 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 Port-
     files.
     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 freshmeat (uses the date_updated tag of the fresh-
         meat 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 set-
     tings.

     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 pro-
         vides 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 over-
         ridden 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 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 directo-
                 ries.

         -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, pass-
         word, real name, home directory and login shell. Note that it is usu-
         ally 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, pass-
         word, 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, recom-
         mended 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.

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

     rpm-vercomp versionA versionB
         Compare two RPM-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 compari-
         sions 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 ele-
         ment 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 seman-
         tics 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

Darwin                         February 13, 2007                        Darwin
Last modified 12 years ago Last modified on Nov 1, 2011, 3:28:53 PM