Ticket #4905: portfile.7

.\" portfile.7
.\"
.\" Copyright (c) 2002 Apple Computer, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of Apple Computer, Inc. nor the names of its
.\"    contributors may be used to endorse or promote products derived from
.\"    this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 31, 2005
.Dt PORTFILE 7 "Apple Computer, Inc."
.Os
.Sh NAME
.Nm Portfile
.Nd MacPorts description file reference
.Sh DESCRIPTION
A complete reference of all available
.Nm
variables and example syntax.
.Nm Portfiles
consist of valid TCL, allowing for simple key/value pair syntax as well
as utilization of TCL's extensive functionality.
.Nm Portfiles
are encoded in UTF-8.
.Pp
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.
.Pp
A
.Nm
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.
.Sh PORTSYSTEM
Portfiles must begin with a PortSystem line that defines which version of the
Portfile interpreter should be used.
.br
.Sy Synopsis:
.Dl PortSystem 1.0
.Sh MAIN VARIABLES
All ports are required to set certain variables.
.Bl -tag -width lc
.It Ic name
Full name of port.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl name XFree86
.It Ic version
Upstream version of software.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl version 4.2.1
.It Ic epoch
If a port's version numbering changes such that a newer version looks
older than the previous version, the
.Ic epoch
should be increased. Often the
.Ic epoch
is formatted like a date.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em 0
.br
.Sy Example:
.Dl epoch 20041231
.It Ic description
One line description of the software and what it does.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl description Dictionary Server Protocol (RFC2229) client
.It Ic long_description
A verbose description of the software and what it does.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Bd -literal -offset indent -compact
long_description The GNU Image Manipulation Program \e\

    (GIMP) is a powerful tool for the preparation and \e\

    manipulation of digital images. The GIMP provides \e\

    the user with a wide variety of image manipulation, \e\

    painting, processing, and rendering tools.
.Ed
.It Ic revision
Local revision number of
.Nm .
Increment for port revisions which would change its installation in any way.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em 0
.br
.Sy Example:
.Dl revision 1
.It Ic categories
Categories to which this port belongs.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl categories spelling textproc
.It Ic maintainers
E-mail address(es) of port maintainer(s).
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl maintainers landonf@opendarwin.org kevin@opendarwin.org
.It Ic platforms
Declares which platforms are supported by the port.
.br
.Sy Type:
.Em required
.br
.Sy Values:
.Em darwin freebsd
.br
.Sy Example:
.Dl platforms darwin
.It Ic worksrcdir
Path to source directory relative to
.Ic workpath .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${distname}
.br
.Sy Example:
.Dl worksrcdir ${distname}-src-${version}
.It Ic distname
Name of distribution file, without the
.Cm extract.suffix .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${name}-${version}
.br
.Sy Example:
.Dl distname ${name}-${version}-src
.It Ic master_sites
List of sites to fetch
.Ic 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.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Bd -literal -offset indent -compact
master_sites ftp://ftp.cdrom.com/pub/magic \e\

    sourceforge
.Ed
.It Xo
.Ic checksums Ar filename Ar type Ar checksum
.Op Ar filename Ar type checksum ...
.Xc
List of checksums for the
.Ic distfiles .
The checksum
.Ar type
can currently be md5, rmd160 or sha1. The
.Ar filename
can be omitted if there is only one distfile.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Bd -literal -offset indent -compact
checksums dictd-1.7.1.tar.gz md5 81317b86ea0a5df0163900ad2e6bb12c \e\ 
        magic-words-1.7.1.tar.gz md5 897a005182928613eadd30c267ce9c5b
.Ed
.br
.Sy Example (ledit 1.11):
.Bd -literal -offset indent -compact
checksums md5 a2d38ba641682509c1e964ad699a9dd2 \e\ 
        sha1 1fb6443b5fdf3c83787953f06282d256477c1288
.Ed
.br
.Sy Example (ssldump 0.9b3):
.Bd -literal -offset indent -compact
checksums md5 ac8c28fe87508d6bfb06344ec496b1dd \e\ 
        sha1 a633a9a811a138eac5ed440d583473b644135ef5 \e\ 
        rmd160 941cf8f2ef8459ec4f9ce65772e134505d46566
.Ed
.It Ic use_automake
If set to yes, run the
.Cm automake
target to build any
.Pa Makefile.in
files for use by
.Pa configure .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.Sy Example:
.Dl use_automake yes
.It Ic use_autoconf
If set to yes, run the
.Cm autoconf
target to build any
.Pa configure
script required.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.Sy Example:
.Dl use_autoconf yes
.It Ic use_configure
If set to yes, run the
.Cm configure
target to configure the build.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em yes
.br
.Sy Example:
.Dl use_configure no
.El
.Sh TARGET HOOKS
A number of hooks are available for customizing many of the standard
targets that
.Xr port 1
executes. The targets supporting these hooks are
.Cm fetch ,
.Cm automake ,
.Cm autoconf ,
.Cm configure ,
.Cm build ,
.Cm destroot ,
and
.Cm test .
The hooks are:
.Bl -tag -width lc
.It Va target Ns Ic .dir
Directory in which to run the
.Va target .
.br
.Sy Example:
.Dl automake.dir src
.It Va target Ns Ic .env
Change the environment the
.Va target
is run in. This is often overridden on a per
.Nm
basis.
.br
.Sy Example:
.Dl configure.env CFLAGS=-O
.It Va target Ns Ic .pre_args
Additional arguments passed before the main arguments.
.br
.Sy Example:
.Dl extract.pre_args -cd
.It Va target Ns Ic .args
Main arguments to pass to the
.Va target .
This is often overridden on a per
.Nm
basis.
.br
.Sy Example:
.Dl configure.args --enable-fooble
.It Va target Ns Ic .post_args
Additional arguments passed after the main arguments.
.br
.Sy Example:
.Dl extract.post_args | tar xf -
.El
.Sh RUNTIME VARIABLES
Read-only access to the MacPorts configuration is provided.
.Bl -tag -width lc
.It Ic prefix
Install prefix
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em /opt/local
.It Ic libpath
Location of ports-specific TCL libraries.
.br
.Sy Type:
.Em read-only
.It Ic workdir
Path to work directory relative to
.Ic portpath .
Where possible use
.Ic workpath
instead.
.br
.Sy Type:
.Em read-only
.br
.Sy Default:
.Em work
.It Ic workpath
Full path to work directory.
.br
.Sy Type:
.Em read-only
.br
.Sy Default:
.Em ${portpath}/${workdir}
.It Ic worksrcpath
Full path to working sources (where port has unpacked itself).
.br
.Sy Type:
.Em read-only
.br
.Sy Default:
.Em ${workpath}/${worksrcdir}
.It Ic filesdir
Path to port files relative to
.Ic portpath .
.br
.Sy Type:
.Em read-only
.br
.Sy Default:
.Em files
.It Ic distpath
Location to store downloaded distfiles.
.br
.Sy Type:
.Em read-only
.br
.Sy Default:
.Em ${sysportpath}/distfiles/${dist_subdir}/
.It Ic os.arch
Identifies hardware type (eg "powerpc").
.br
.Sy Type:
.Em read-only
.It Ic os.version
Version number of operating system (eg "7.0").
.br
.Sy Type:
.Em read-only
.It Ic os.endian
Endianness of the processor (eg "bigEndian").
.br
.Sy Type:
.Em read-only
.It Ic os.platform
Operating system name (eg "darwin").
.br
.Sy Type:
.Em read-only
.It Ic install.user
User for MacPorts installation (eg
.Pa root )
.br
.Sy Type:
.Em read-only
.It Ic install.group
Group for MacPorts installation (eg
.Pa wheel )
.br
.Sy Type:
.Em read-only
.It Ic x11prefix
Absolute path to X11 (eg
.Pa /usr/X11R6 )
.br
.Sy Type:
.Em read-only
.El
.Sh DEPENDENCY OPTIONS
Port dependencies should refer to other MacPort ports
whenever possible, therefore each dependency should be
expressed in the format:
.Bl -tag -width ls
.It port: Ns Ao port Ac
.El
.Pp
Where 
.Ao port Ac represents the name of an existing MacPorts
.Nm 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:
.Bl -tag -width lc
.It Ar type Ns : Ns Ao filename Ac Ns : Ns Ao port Ac
.El
.Pp
may be used. Where
.Ar type
is "bin" if
.Ao filename Ac
is a program, "lib" if it is a library, or "path" if it is a path to an
installed file.
.br
.Sy Example:
.Dl lib:libX11.6:XFree86

.Bl -tag -width lc
.It Ic depends_build
List of dependencies to check before
.Cm build ,
.Cm destroot ,
.Cm install ,
and
.Cm package
targets.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl depends_build port:autoconf
.It Ic depends_run
List of dependencies to check before
.Cm destroot ,
.Cm install
and
.Cm package
targets.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl depends_run port:bash
.It Ic depends_lib
List of dependencies to check before
.Cm configure ,
.Cm build ,
.Cm destroot ,
.Cm install ,
and
.Cm package
targets.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl depends_lib port:libfetch
.El
.Sh FETCH OPTIONS
Fetch all distribution files and patches.
.Bl -tag -width lc
.It Ic master_sites.mirror_subdir
Subdirectory to append to all mirror sites for any list specified in
master_sites.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${name}
.br
.Sy Example:
.Dl master_sites.mirror_subdir      magic
.It Ic patch_sites
List of sites to fetch
.Ic patchfiles
from or a predefined mirror site list.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${master_sites}
.br
.Sy Example:
.Dl patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches
.It Ic patch_sites.mirror_subdir
Subdirectory to append to all mirror sites for any list specified in
.Ic patch_sites .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${name}
.br
.Sy Example:
.Dl patch_sites.mirror_subdir       magic
.It Ic extract.suffix
Suffix to append to
.Ic distname .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em .tar.gz
.br
.Sy Example:
.Dl extract.suffix .tgz
.It Ic distfiles
List of distribution files to fetch from
.Ic master_sites .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em [suffix ${distname}]
.br
.Sy Example:
.Dl distfiles magicsource.tar.gz cluebat.tar.bz2
.It Ic patchfiles
List of patches to fetch and apply.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl patchfiles japanese-widechar-fix.diff japanese-localization.diff
.It Ic use_zip
Use zip.
.br
Sets extract.suffix to: .zip
.br
Sets extract.cmd to: unzip
.br
Sets extract.pre_args to: -q
.br
Sets extract.post_args to: "-d $portpath/$workdir"
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_zip yes
.It Ic use_bzip2
Use bzip2.
.br
Sets extract.suffix to: .bzip2
.br
Sets extract.cmd to: bzip2
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_bzip2 yes
.It Ic dist_subdir
Create a sub-directory in
.Ic distpath
to store all fetched files.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${name}
.br
.Sy Example:
.Dl dist_subdir vim${version}
.El
.Ss ADVANCED FETCH OPTIONS
Some mirrors require special options for a resource to be properly
fetched.
.Bl -tag -width lc
.It Ic fetch.user
HTTP or FTP user to fetch the resource.
.br
.Sy Type:
.Em optional
.It Ic fetch.password
HTTP or FTP password to fetch the resource.
.br
.Sy Type:
.Em optional
.It Ic fetch.use_epsv
Whether to use EPSV command for FTP transfers.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em yes
.br
.El
.Ss 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.
.Bl -tag -width lc
.It Ic cvs.root
Specify the address to a CVS repository from which to checkout files.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none
.br
.Sy Example:
.Dl cvs.root :pserver:anonymous cvs.sv.gnu.org:/sources/emacs
.It Ic cvs.tag
Specify a CVS tag identifying the code to checkout.
.br
.Sy Type:
.Em optional
.br
.Sy Default
.Em none
.br
.Sy Example:
.Dl cvs.tag HEAD
.It Ic cvs.date
A date that identifies the CVS code set to checkout.
.br
.Sy Type:
.Em optional
.br
.Sy Default
.Em none
.br
.Sy Example:
.Dl cvs.date \*q12-April-2005\*q
.It Ic cvs.module
A CVS module from which to check out the code.
.br
.Sy Type:
.Em optional
.br
.Sy Default
.Em none
.br
.Sy Example:
.Dl cvs.module Sources
.El
.Ss 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.
.Bl -tag -width lc
.It Ic svn.url
Specify the url from which to fetch files.
.br
.Sy Type:
.Em required
.br
.Sy Default:
.Em none
.br
.Sy Example:
.Dl svn.url http://www.domain.com/svn-repo/mydirectory
      svn.url svn://www.domain.com/svn-repo/mydirectory
.It Ic svn.tag
Specify the a tag from which svn should fetch files. This
corresponds to the -r option to the svn cli.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none
.br
.Sy Example:
.Dl svn.url http://www.domain.com/svn-repo/mydirectory
      svn.url svn://www.domain.com/svn-repo/mydirectory
.El
.Sh EXTRACT OPTIONS
Extract all compressed/archived files.
.Bl -tag -width lc
.It Ic extract.only
List of files to extract into
.Ic workpath .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${distfiles}
.br
.Sy Example:
.Dl extract.only worksrc-1.4.4.tar.gz
.It Ic extract.cmd
Command to perform the extraction.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em gzip
.br
.Sy Example:
.Dl extract.cmd bzip2
.El
.Sh BUILD OPTIONS
Execute necessary build commands.
.Bl -tag -width lc
.It Ic build.cmd
Make command to run relative to
.Ic worksrcdir .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em make
.br
.Sy Example:
.Dl build.cmd pbxbuild
.It Ic build.type
Defines which 'make' is required, either 'gnu' or 'bsd'.
Sets
.Ic build.cmd
to either
.Pa gnumake
or
.Pa bsdmake
accordingly.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em gnu
.br
.Sy Example:
.Dl build.type bsd
.It Ic build.target
Target passed to
.Ic build.cmd .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em all
.br
.Sy Example:
.Dl build.target all-src
.El
.Sh DESTROOT OPTIONS
Execute necessary commands to install into a temporary destination root
("destroot") staging area.
.Bl -tag -width lc
.It Ic destroot.cmd
Install command to run relative to
.Ic worksrcdir .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${build.cmd}
.br
.Sy Example:
.Dl destroot.cmd pbxbuild
.It Ic destroot.type
Defines which 'make' is required, either 'gnu' or 'bsd'.
Sets
.Ic destroot.cmd
to either
.Pa gnumake
or
.Pa bsdmake
accordingly.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${build.type}
.br
.Sy Example:
.Dl destroot.type gnu
.It Ic destroot.destdir
Arguments passed to
.Ic destroot.cmd
in order to install correctly
into the destroot.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em DESTDIR=${destroot}
.br
.Sy Example:
.Dl destroot.destdir prefix=${destroot}${prefix}
.It Ic destroot.target
Install target to pass to
.Ic destroot.cmd .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em install
.br
.Sy Example:
.Dl destroot.target install-src
.It Ic destroot.umask
Umask to use during destroot.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em 022
.br
.Sy Example:
.Dl destroot.umask 002
.It Ic destroot.keepdirs
List of directories that should not be pruned if empty upon
.Cm destroot
completion.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl destroot.keepdirs ${destroot}${prefix}/var/log/mysql
.El
.Sh TEST OPTIONS
Execute commands to run test suites bundled with a port.
.Bl -tag -width lc
.It Ic test.run
Enable running test suites bundled with a port.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl test.run     yes
.It Ic test.cmd
Test command to run relative to
.Ic worksrcdir .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${build.cmd}
.br
.Sy Example:
.Dl test.cmd checks.sh
.It Ic test.target
Test target to pass to
.Ic test.cmd .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em test
.br
.Sy Example:
.Dl test.target checks
.El
.Sh 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.
.Bl -tag -width lc
.It Ic startupitem.create
Choose whether or not to generate a startup item.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.Sy Values:
.Em yes no
.br
.Sy Example:
.Dl startupitem.create yes
.It Ic 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.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em default
.br
.Sy Values:
.Em SystemStarter launchd default rcNG
.br
.Sy Example
.Dl startupitem.type launchd
.It Ic startupitem.name
Displayed name of the startup item.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl startupitem.name OpenSSH
.It Ic 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.
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em /path/to/executable <args>
.br
.Sy Example:
.Dl startupitem.executable $prefix/bin/wonka
.It Ic startupitem.init
Shell code that will be executed prior to any of the options
startupitem.start, startupitem.stop and startupitem.restart.
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em sh code
.br
.Sy Example:
.Dl startupitem.init FOO=start
.It Ic startupitem.start
Shell code executed to start the daemon.
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em sh code
.br
.Sy Example:
.Dl startupitem.start $prefix/share/mysql/mysql.server start
.It Ic startupitem.stop
Shell code executed to stop the daemon.
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em sh code
.br
.Sy Example:
.Dl startupitem.stop $prefix/share/mysql/mysql.server stop
.It Ic 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.
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em sh code
.br
.Sy Example:
.Dl startupitem.restart $prefix/share/mysql/mysql.server restart
.It Ic 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).
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none "${prefix}/var/run/${name}.pid"
.br
.Sy Values:
.Em none|auto|manual|clean [/path/to/pidfile]
.br
.Sy Example:
.Dl startupitem.pidfile auto $prefix/var/run/${name}.pidfile
.It Ic 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.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em /dev/null
.br
.Sy Values:
.Em path
.br
.Sy Example:
.Dl startupitem.logfile $prefix/var/log/mydaemon.log
.It Ic 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.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.Sy Values:
.Em yes|no
.br
.Sy Example:
.Dl startupitem.logevents yes
.El
.Sh 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.
.br
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.
.Bl -tag -width lc
.It Ic distcheck.check
This option can be used to disable distcheck. It specifies what kind
of check should be performed on distfiles:
.Em moddate
(check if the Portfile is older than the distfile) or
.Em none
(no check).
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em moddate
.br
.Sy Values:
.Em moddate none
.It Ic livecheck.check
What kind of check to perform to figure out if the software has been updated.
Can be
.Em freshmeat
(uses the date_updated tag of the freshmeat XML file),
.Em sourceforge
(uses the version of the latest file release of the project),
.Em moddate
(uses the modification date of some URL resource),
.Em regex
(retrieve the version by applying a regex to some URL resource),
.Em regexm
(retrieve the version by applying a multi-line regex to some URL resource),
.Em md5
(compares the md5 sum of some URL resource) or
.Em none
(no check).
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em freshmeat
or
.Em sourceforge
if the master_sites is sourceforge.
.br
.Sy Values:
.Em freshmeat sourceforge moddate regex regexm md5 none
.It Ic livecheck.name
Name of the project for live checks (used for freshmeat and sourceforge checks).
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${name}
or the sourceforge project name if it can be guessed by looking at the master_sites.
.It Ic livecheck.version
Version of the project for live checks (used for regex-based checks).
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${version}
.It Ic livecheck.url
URL to query for the check.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${homepage}
or
.Em http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml
or
.Em http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}
.It Ic livecheck.regex
Regular expression to parse the resource for regex checks.
.br
.Sy Type:
.Em optional
.It Ic livecheck.md5
md5 sum to use for md5 comparison.
.br
.Sy Type:
.Em optional
.El
.Sh VARIANT OPTIONS
MacPorts allows for conditional modification to be specified in a
.Nm ,
allowing for user-customization of a software's build-time settings.
.Bl -tag -width lc
.It Xo
.Ic variant
.Op Cm requires Ar variant
.Op Cm conflicts Ar variant
.Xc
The value is usually a TCL script which modifies other port's
.Nm
variables. Dependencies and conflicts with other variants in the same
port can be expressed with
.Cm requires
and
.Cm conflicts .
The example adds a "gnome" variant to a port.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Bd -literal -offset indent -compact
variant gnome requires glib { configure.args-append --with-gnome \e\

    depends_lib-append lib:gnome-session:gnome-session }
.Ed
.It Ic default_variants
If variants are defined, then the
.Ic default_variants
value lists which variants are enabled by default.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl default_variants +ssl +tcpd
.El
.Sh PLATFORM OPTIONS
MacPorts allows for platform-specific conditional modification to be
specified in a
.Nm ,
much like variants, for handling differences between platforms and
versions of the same platform.
.Bl -tag -width lc
.It Xo
.Ic platform
.Ar platform
.Op Ar version
.Op Ar arch
.Xc
The platform key is used to begin the darwin platform definitions as
shown in the examples from the databases/db4 and devel/libidl1
.Nm Portfiles
respectively.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Bd -literal -offset indent -compact
platform darwin 6 { configure.args-append   --enable-tcl \e\

        --with-tcl=/System/Library/Tcl/8.3 }
.Ed
.br
.Sy Example:
.Bd -literal -offset indent -compact
platform darwin powerpc { configure.args-append \e\

        --host=${os.arch}-apple-rhapsody${os.version} }
platform darwin i386 { configure.args-append \e\

        --host=i386-gnu-rhapsody${os.version} }
.Ed
.El
.Sh PORTGROUP
To factorize the work with similar ports, MacPorts provides the notion of
.Nm PortGroup
that can be used to load definitions for a given class or group of ports. See
.Xr portgroup 7
for more details on the various PortGroup classes.
.Sh TCL EXTENSIONS
A number of TCL extensions are available for use in
.Nm Portfiles .
.Pp
.Bl -tag -width lc
.Bl -tag -width lc -compact
.It Xo
.Ic xinstall
.Op Fl c
.Op Fl B Ar suffix
.Op Fl b
.Op Fl C
.Op Fl f Ar flags
.Op Fl g Ar group
.Op Fl M
.Op Fl m Ar mode
.Op Fl o Ar owner
.Op Fl p
.Op Fl S
.Op Fl s
.Op Fl W Ar dir
.Op Ar
.Ar destination
.Xc
.It Xo
.Ic xinstall
.Fl d
.Op Fl B Ar suffix
.Op Fl b
.Op Fl C
.Op Fl f Ar flags
.Op Fl g Ar group
.Op Fl M
.Op Fl m Ar mode
.Op Fl o Ar owner
.Op Fl p
.Op Fl S
.Op Fl s
.Op Fl W Ar dir
.Ar directory
.Xc
Install file(s) to a target file or directory. The options are
intended to be compatible with
.Xr install 1 :
.Bl -tag -width indent
.It Fl b
Backup any existing files with an
.Pa .old
extension.
.It Fl B
Specify a different backup suffix for the
.Fl b
flag.
.It Fl c
Install files (this is the default).
.It Fl C
Only copy a file if it is different.
.It Fl d
Create directories, including (if necessary) parent directories.
.It Fl f
Specify target flags, see
.Xr chflags 1
for details.
.It Fl g
Specify the group.
.It Fl M
Disable use of
.Xr mmap 2 .
.It Fl m
Specify an alternate mode. The default is 0755. See
.Xr chmod 1
for defails.
.It Fl p
Preserve the modification time.
.It Fl S
Copy safely, using a temporary file.
.It Fl s
Strip binaries using
.Xr strip 1 .
.It Fl W
Change to
.Ar dir
before working.
.El
.El
.It Xo
.Ic curl fetch
.Ar url
.Ar file
.Xc
Fetch a resource at
.Ar url
and save it to
.Ar file .
.It Xo
.Ic curl isnewer
.Ar url
.Ar date
.Xc
Determine if resource at
.Ar url
is newer than
.Ar date
(expressed in seconds since epoch).
.It Xo
.Ic adduser
.Ar username
.Op Cm uid Ns = Ns uid
.Op Cm gid Ns = Ns gid
.Op Cm passwd Ns = Ns passwd
.Op Cm realname Ns = Ns realname
.Op Cm home Ns = Ns home
.Op Cm shell Ns = Ns shell
.Xc
Add a new local user to the system with the specified uid, gid,
password, real name, home directory and login shell.
.It Ic existsuser Ar username
Check if a local user exists.
.It Ic nextuid
Returns the highest used uid plus one.
.It Xo
.Ic addgroup
.Ar group
.Op Cm gid Ns = Ns gid
.Op Cm passwd Ns = Ns passwd
.Op Cm users Ns = Ns users
.Xc
Add a new local group to the system, with the specified gid, password
and with a list users as members.
.It Ic existsgroup Ar group
Check if a local group exists and return the corresponding gid. This can be used
with adduser:
.Dl addgroup foo 
.Dl adduser foo gid=[existsgroup foo]
.It Ic nextgid
Returns the highest used gid plus one.
.It Ic reinplace Ar regex Ar filename
Provide in-place sed like editing of a file.
.br
.Sy Example:
.Dl reinplace \*qs|/usr/local|${prefix}|g\*q doc/manpage.1
.It Ic 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
.Nm xinstall
to also preserve Extended Attributes (i.e. Access Control Lists). See
.Xr file n .
.It Ic system Ar commandline
Execute a program. See
.Xr system 3 .
For calls to
.Xr install 1
please use
.Nm xinstall .
For calls to 
.Xr mv 1 ,
.Xr cp 1 ,
.Xr rm 1
or similar, please use
.Nm file .
.It Ic variant_isset Ar variant
Checks if the given
.Ar variant
is being built.
.It Ic variant_set Ar variant
Set the given
.Ar variant .
.It Ic variant_unset Ar variant
Unset the given
.Ar variant .
.It Va variable Ns - Ns Ic append Ar item
Append
.Ar item
to the
.Va variable .
.br
.Sy Example:
.Dl configure.args-append --with-gnomedb
.It Va variable Ns - Ns Ic delete Ar item
Delete
.Ar item
from the
.Va variable .
.br
.Sy Example:
.Dl configure.args-delete --with-gnomedb
.It Ic readdir Ar directory
Return the list of elements in a
.Ar directory ,
excluding
.Pa \&.
and
.Pa \&.. .
.It Ic strsed Ar string Ar pattern
Perform
.Xr ed 1 Ns / Ns
.Xr tr 1 Ns -like
search, replace, and transliteration on a string.
.It Ic mktemp Ar template
Create a temporary file using a
.Ar template .
See
.Xr mktemp 3 .
.It Ic mkstemp Ar template
Create a temporary file securely using a
.Ar template .
See
.Xr mkstemp 3 .
.It Ic md5 Ar
Compute the MD5 hashes of the file(s).
.It Ic rpm-vercomp Ar versionA Ar versionB
Compare two RPM-format versions for equality.
.It Ic sudo Ar password Ar command Ar \&...
Execute
.Ar command
using
.Cm sudo
with the provided password.
.El
.Pp
.Bl -tag -width lc -compact
.It Ic ui_debug Ar message
.It Ic ui_error Ar message
.It Ic ui_info Ar message
.It Ic ui_msg Ar message
.It Ic ui_warn Ar message
Display a
.Ar message
to the user, at various different levels.
.br
.Sy Example:
.Dl ui_msg \*qAdd each user to the system using the clamav command\*q
.El
.Sh SEE ALSO
.Xr port 1 ,
.Xr ports.conf 5 ,
.Xr portgroup 7 ,
.Xr portstyle 7 ,
.Xr porthier 7 ,
.Xr file n
.Sh AUTHORS
.An "Landon Fuller" Aq landonf@opendarwin.org
.An "Kevin Van Vechten" Aq kevin@opendarwin.org
.An "Jordan K. Hubbard" Aq jkh@opendarwin.org
.An "Chris Ridd" Aq cjr@opendarwin.org
.An "Juan Manuel Palacios" Aq jmpp@opendarwin.org