macports-base/doc/portfile.7

.\" portfile.7
.\"
.\" Copyright (c) 2004-2015, 2017-2018 The MacPorts Project
.\" Copyright (c) 2002-2003 Apple 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 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 February 13, 2007
.Dt PORTFILE 7 "MacPorts"
.Os Darwin
.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.
Some
.Nm Portfile
authors have used large
.Ic epoch
values that look like a date, but there is no reason to do so.
The
.Ic epoch
is simply an unsigned integer, and the only requirement is that it never be
decreased.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em 0
.br
.Sy Example:
.Dl epoch 1
.It Ic 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
.Ql \e[ ,
.Ql \e]
and
.Ql \e; ) .
The escape sequences listed in
.Xr re_syntax n
may also be used, with the exception of
.Ql \en ,
.Ql \er
and
.Ql \ef .
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl description IMAP email checker
.It Ic 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
.Ql \e[ ,
.Ql \e]
and
.Ql \e; ) .
The escape sequences listed in
.Xr re_syntax n
may also be used, with the exception of
.Ql \en ,
.Ql \er
and
.Ql \ef .
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Bd -literal -offset indent -compact
long_description The GNU Image Manipulation \e
    Program (GIMP) is a powerful tool for the \e
    preparation and manipulation of digital \e
    images. The GIMP provides the user with a \e
    wide variety of image manipulation, painting, \e
    processing, and rendering tools.
.Ed
.It Ic notes
Notes for setup and use of the port.
This is shown after the port is activated and anytime the
.Ic notes
command is used; for example:
.Pp
.Dl "port notes python26"
.Pp
The advantage to using
.Ic notes
instead of
.Ic ui_msg
is that it can be queried after a port is installed but
.Ic ui_msg
is only printed during an install.
Therefore
.Ic notes
is good for any information which may be needed anytime after an install.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Bd -literal -offset indent -compact
notes "
To fully complete your installation and make\e
python ${branch} the default, please run:

  sudo port install python_select
  sudo python_select ${name}
"
.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@macports.org
.It Ic platforms
Declares which platforms are supported by the port.
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em darwin freebsd
.br
.Sy Default:
.Em darwin
.br
.Sy Example:
.Dl platforms darwin freebsd
.It Ic supported_archs
The CPU architectures for which this port can be built.
Archs currently supported by macOS are:
.Em i386 ,
.Em ppc ,
.Em ppc64 ,
and
.Em 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.
.br
If the building architecture isn't among
.Ic supported_archs ,
port fails with an error message except when building on
.Em x86_64
(or
.Em ppc64 )
and
.Ic supported_archs
contains
.Em i386
(or
.Em ppc ) .
In this case, the port will be built in 32-bit mode.
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em i386 x86_64 ppc ppc64 noarch
.br
.Sy Default:
.Em i386 x86_64 ppc ppc64
.br
.Sy Examples:
.Dl supported_archs i386 x86_64
.Dl supported_archs noarch
.It Ic homepage
Project homepage for the port.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl http://wireshark.org
.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 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 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, sha1, rmd160, sha256, blake3 or size.
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 macosx_deployment_target
Value for
.Ev MACOSX_DEPLOYMENT_TARGET
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em (current OS version)
.br
.Sy Example:
.Dl macosx_deployment_target 10.8
.It Ic use_parallel_build
If set to yes (and the user has enabled buildmakejobs in
.Pa macports.conf ) ,
the port can be built using more than one job.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em yes
.br
.Sy Example:
.Dl use_parallel_build no
.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_autoreconf
If set to yes, run the
.Cm autoreconf
target to generate GNU build system files.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.Sy Example:
.Dl use_autoreconf 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
.It Ic copy_log_files Ar path/to/logfile1 Ar path/to/logfile2 Ar ...
Copy specific log files from the workdir to the main MacPorts log dir.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl copy_log_files config.log
.It Ic conflicts
Used to list ports which conflict with the one containing the
.Cm conflicts
declaration.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none (empty)
.br
.Sy Example:
.Dl conflicts cdrtools
.It Ic replaced_by
When a particular port is deprecated in favor of another, use
.Cm replaced_by
in the deprecated port and list the new one to be used.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none (empty)
.br
.Sy Example:
.Dl replaced_by xorg-renderproto
.It Ic 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.
.Pp
Applicable options are: group, gid (may be used instead of group), passwd,
realname, home, and shell.
.Pp
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none (empty)
.br
.Sy Examples:
.Bd -literal -offset indent -compact
add_users squid group=squid realname=Squid\e Proxy \e
    home=${prefix}/var/squid
add_users user1 group=mygroup user2 group=mygroup
.Ed
.It Ic 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
.Cm installs_libs
to
.Em 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.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none
.br
.Sy Example:
.Dl installs_libs no
.It Ic 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.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none
.br
.Sy Example:
.Dl license_noconflict openssl
.Dl license_noconflict readline gdbm
.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 .asroot
Run the
.Va target
with root privileges.
.br
.Sy Example:
.Dl install.asroot yes
.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:
.Bd -literal -offset indent -compact
build.env CC="${configure.cc} [get_canonical_archflags]"
.Ed
.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 portpath
Full path to the Portfile location.
.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 ${portbuildpath}/work
.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 filespath
Full path to the port files location.
.br
.Sy Type:
.Em read-only
.br
.Sy Default:
.Em ${portpath}/${filesdir}
.It Ic distpath
Location to store downloaded distfiles.
.br
.Sy Type:
.Em read-only
.br
.Sy Default:
.Em ${portdbpath}/distfiles/${dist_subdir}/
.It Ic os.arch
Identifies hardware type (e.g.,
.Dq powerpc ) .
.br
.Sy Type:
.Em read-only
.It Ic os.version
Version number of operating system (e.g.,
.Dq 7.0 ) .
.br
.Sy Type:
.Em read-only
.It Ic os.major
Major version number of operating system (e.g.,
.Dq 7 ) .
.br
.Sy Type:
.Em read-only
.It Ic os.endian
Endianness of the processor (e.g.,
.Dq big ) .
.br
.Sy Type:
.Em read-only
.It Ic os.platform
Operating system name (e.g.,
.Dq darwin ) .
.br
.Sy Type:
.Em read-only
.It Ic os.subplatform
Name of specific operating system variant (e.g.,
.Dq macosx ) .
.br
.Sy Type:
.Em read-only
.It Ic install.user
User for MacPorts installation (e.g.,
.Dq root ) .
.br
.Sy Type:
.Em read-only
.It Ic install.group
Group for MacPorts installation (e.g.,
.Dq wheel ) .
.br
.Sy Type:
.Em read-only
.It Ic applications_dir
Absolute path to the final location to install macOS application bundles
.Pf ( Pa .app
directories).
.br
.Sy Type:
.Em read-only
.br
.Sy Default:
.Em /Applications/MacPorts
.It Ic frameworks_dir
Absolute path to the final location to install macOS framework bundles
.Pf ( Pa .framework
directories).
.br
.Sy Type:
.Em read-only
.br
.Sy Default:
.Em ${prefix}/Library/Frameworks
.El
.Sh DEPENDENCY OPTIONS
Port dependencies should refer to other MacPorts ports
whenever possible, therefore each dependency should be
expressed in the format:
.Bl -tag -width ls -offset indent
.It Li port: Ns Aq port
.El
.Pp
Where
.Aq port
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 -offset indent
.It Ar type Ns Li \&: Ns Ao filename Ac Ns Li \&: Ns Aq port
.El
.Pp
may be used.
Where
.Ar type
is
.Dq bin
if
.Aq filename
is a program,
.Dq lib
if it is a library, or
.Dq 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_fetch
List of dependencies to check before
.Cm fetch ,
.Cm checksum ,
.Cm extract ,
.Cm patch ,
.Cm configure ,
.Cm build ,
.Cm destroot ,
.Cm install ,
and
.Cm package
targets.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl depends_fetch port:mercurial
.It Ic depends_extract
List of dependencies to check before
.Cm extract ,
.Cm patch ,
.Cm configure ,
.Cm build ,
.Cm destroot ,
.Cm install ,
and
.Cm package
targets.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl depends_extract path:bin/xz:xz
.It Ic depends_build
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_build port:autoconf
.It Ic depends_run
List of dependencies to check before
.Cm destroot ,
.Cm install
and
.Cm package
targets.
Will be recorded in the registry as being required by the dependent port when
it is installed.
.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.
Will be recorded in the registry as being required by the dependent port when
it is installed.
.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
.Ic 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:
.Bd -literal -offset indent -compact
patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches
.Ed
.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 ${distname}${extract.suffix}
.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 patch-Makefile.in.diff patch-main.c.diff
.It Ic use_zip
Use zip.
.br
Sets
.Ic extract.suffix
to
.Dq .zip .
.br
Sets
.Ic extract.cmd
to
.Dq unzip .
.br
Sets
.Ic extract.pre_args
to
.Dq -q .
.br
Sets
.Ic extract.post_args
to
.Dq -d ${workpath} .
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_zip yes
.It Ic use_bzip2
Use bzip2.
.br
Sets
.Ic extract.suffix
to
.Dq .tar.bz2 .
.br
Sets
.Ic extract.cmd
to
.Dq bzip2 .
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_bzip2 yes
.It Ic use_lzip
Use lzip.
.br
Sets
.Ic extract.suffix
to
.Dq .tar.lz .
.br
Sets
.Ic extract.cmd
to
.Dq lzip .
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_lzip yes
.It Ic use_lzma
Use lzma.
.br
Sets
.Ic extract.suffix
to
.Dq .tar.lzma .
.br
Sets
.Ic extract.cmd
to
.Dq lzma .
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_lzma yes
.It Ic use_tar
Use an uncompressed tar archive.
.br
Sets
.Ic extract.suffix
to
.Dq .tar .
.br
Sets
.Ic extract.cmd
to
.Dq tar .
.br
Sets
.Ic extract.pre_args
to
.Dq -xf .
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_tar yes
.It Ic use_xz
Use xz.
.br
Sets
.Ic extract.suffix
to
.Dq .tar.xz .
.br
Sets
.Ic extract.cmd
to
.Dq xz .
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_xz yes
.It Ic use_7z
Use 7z (7zip).
.br
Sets
.Ic extract.suffix
to
.Dq .7z .
.br
Sets
.Ic extract.cmd
to
.Dq 7za .
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_7z yes
.It Ic use_dmg
Use a disk image (dmg).
Note that the arguments passed to 'hdiutil' are extensive, and can vary based
on the Darwin release, other options, etc.
As such, ports should not attempt to manipulate 'extract.post_args'.
.br
Sets
.Ic extract.suffix
to
.Dq .dmg .
.br
Sets
.Ic extract.cmd
to
.Dq hdiutil .
.br
Sets
.Ic extract.pre_args
to
.Dq attach .
.br
Sets
.Ic extract.post_args
to
.Dq -private -readonly -nobrowse -mountpoint ...etc... .
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_dmg 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
.Li EPSV
command for FTP transfers.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em yes
.br
.It Ic fetch.ignore_sslcert
Whether to ignore the host SSL certificate (for HTTPS).
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.It Ic fetch.user_agent
HTTP User-Agent to use when fetching the resource.
Useful for servers that block requests from the default curl user agent.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em \&""
.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:
.Bd -literal -offset indent -compact
cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs
.Ed
.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 Examples:
.Bd -literal -offset indent -compact
svn.url https://www.example.com/svn/project/tags/1.2.3
svn.url svn://www.example.com/svn/project/tags/1.2.3
.Ed
.It Ic svn.revision
Specify a tag from which svn should fetch files.
This
corresponds to the
.Fl 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.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none
.br
.Sy Examples:
.Bd -literal -offset indent -compact
svn.revision 37192
svn.revision {"2006-02-17 15:30 +0230"}
.Ed
.El
.Ss 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.
.Bl -tag -width lc
.It Ic git.url
Specify the url from which to fetch files.
.br
.Sy Type:
.Em required
.br
.Sy Default:
.Em none
.br
.Sy Examples:
.Bd -literal -offset indent -compact
git.url git://git.kernel.org/pub/scm/git/git.git
git.url http://www.kernel.org/pub/scm/git/git.git
.Ed
.It Ic git.branch
Specify a branch (or other commit-ish) that git should checkout.
Note that any branch besides HEAD should be prefixed by
.Pa origin/ .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none
.br
.Sy Examples:
.Bd -literal -offset indent -compact
git.branch 72bf1c8
git.branch origin/next
.Ed
.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
.It Xo
.Ic extract.methods Ar filename Ar method
.Op Ar filename Ar method ...
.Xc
Override extract method for some distfiles. By default, the extract
command and arguments are chosen based on the filename suffix. This
option can override that choice in case of unusually named files.
.br
.Sy Type:
.Em optional
.br
.Sy Method values:
.Em 7z bzip2 dmg gzip lzip lzma tar xz zip zstd
.br
If a method not in the above list is specified, it is assumed to refer
to a procedure defined in the Portfile which takes a single argument
containing the path to a distfile, which will extract it when called.
.br
.Sy Default:
.Em none (empty)
.br
.Sy Example:
.Bd -literal -offset indent -compact
extract.methods worksrc-1.4.4.tar.gz lzma \e
                extrafile-1.0.unusualsuffix gzip
.Ed
.It Ic extract.mkdir
Create the
.Ic worksrcdir
prior to extraction; useful for ports which extract directly into the current
working directory instead of a subdirectory.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.Sy Example:
.Dl extract.mkdir yes
.El
.Sh 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
.Ic configure.env )
may become deprecated at some point.
The following options are defined:
.Bl -tag -width lc
.It Ic configure.optflags
Flags to use for optimization.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em -Os
.br
.Sy Example:
.Dl configure.optflags -O3
.It Ic configure.cflags
Flags to put in the
.Ev CFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${configure.optflags}
.br
.Sy Example:
.Dl configure.cflags-append -DHAS_LRINTF
.It Ic configure.cppflags
Flags to put in the
.Ev CPPFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em -I${prefix}/include
.It Ic configure.cxxflags
Flags to put in the
.Ev CXXFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${configure.optflags}
.It Ic configure.objcflags
Flags to put in the
.Ev OBJCFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${configure.optflags}
.It Ic configure.ldflags
Flags to put in the
.Ev LDFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em -L${prefix}/lib -Wl,-headerpad_max_install_names
.It Ic configure.fflags
Flags to put in the
.Ev FFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${configure.optflags}
.It Ic configure.f90flags
Flags to put in the
.Ev F90FLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${configure.optflags}
.It Ic configure.fcflags
Flags to put in the
.Ev FCFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${configure.optflags}
.It Ic configure.classpath
Flags to put in the
.Ev CLASSPATH
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.It Ic configure.cc
C\~compiler to put in the
.Ev CC
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl configure.cc /usr/bin/gcc
.It Ic configure.cpp
C\~preprocessor to put in the
.Ev CPP
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.It Ic configure.cxx
C++ compiler to put in the
.Ev CXX
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.It Ic configure.objc
Objective\~C compiler to put in the
.Ev OBJC
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl configure.objc ${prefix}/bin/gcc-mp-4.1
.It Ic configure.fc
Fortran compiler to put in the
.Ev FC
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.It Ic configure.f77
Fortran\~77 compiler to put in the
.Ev F77
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.It Ic configure.f90
Fortran\~90 compiler to put in the
.Ev F90
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.It Ic configure.javac
Java compiler to put in the
.Ev JAVAC
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.It Ic 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!
.Em gcc-3.3 ,
.Em gcc-4.0 ,
.Em gcc-4.2 ,
.Em llvm-gcc-4.2 ,
and
.Em clang
use the standard Xcode compiler suites,
.Em apple-gcc-4.0
and
.Em apple-gcc-4.2
use Apple's gcc suite installed via MacPorts,
.Em macports-gcc-4.2 ,
.Em macports-gcc-4.3 ,
.Em macports-gcc-4.4 ,
.Em macports-gcc-4.5 ,
.Em macports-gcc-4.6 ,
.Em macports-gcc-4.7 ,
.Em macports-gcc-4.8 ,
and
.Em macports-llvm-gcc-4.2
use the vanilla compiler suites installed via MacPorts.
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em gcc-3.3
.Em gcc-4.0
.Em gcc-4.2
.Em llvm-gcc-4.2
.Em clang
.Em apple-gcc-4.0
.Em apple-gcc-4.2
.Em macports-gcc-4.2
.Em macports-gcc-4.3
.Em macports-gcc-4.4
.Em macports-gcc-4.5
.Em macports-gcc-4.6
.Em macports-gcc-4.7
.Em macports-gcc-4.8
.Em macports-llvm-gcc-4.2
.br
.Sy Example:
.Dl configure.compiler llvm-gcc-4.2
.It Ic configure.sdk_version
macOS SDK version to build against.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em (current OS version)
.br
.Sy Example:
.Dl configure.sdk_version 10.8
.It Ic configure.sdkroot
The path to the macOS SDK to build against.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em Automatically set by MacPorts; varies by macOS release, whether Xcode installed, etc.
.br
.Sy Example:
.Dl configure.sdkroot /Library/Developer/CommandLineTools/SDKs/MacOSX10.15.sdk
.\" FOOBAR
.El
.Ss 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.
.Bl -tag -width lc
.It Ic configure.universal_args
Arguments appended to the configure script to build the port universal.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em --disable-dependency-tracking
.It Ic configure.universal_cflags
Additional flags to put in the
.Ev CFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em -isysroot/Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc
.It Ic configure.universal_cppflags
Additional flags to put in the
.Ev CPPFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.It Ic configure.universal_cxxflags
Additional flags to put in the
.Ev CXXFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em -isysroot/Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc
.It Ic configure.universal_ldflags
Additional flags to put in the
.Ev LDFLAGS
environment variable when invoking the configure script.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em -arch i386 -arch ppc
.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 scons
.It Ic build.type
Defines which
.Xr make 1
program is required, either
.Dq gnu
or
.Dq bsd .
Can also choose
.Dq xcode
(or the deprecated synonym
.Dq pbx ) ,
however you should generally use the xcode PortGroup rather than setting this
directly.
Sets
.Ic build.cmd
to either
.Pa gnumake ,
.Pa bsdmake
or
.Pa xcodebuild
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
.It Ic use_xcode
Specifies dependency on Xcode compilers. Restricts Xcode compilers on trace
mode when set to no. The default changes to yes when build.type is set to
Xcode (e.g., xcode 1.0 PortGroup).
.br
.Sy Type:
.Em yes no
.br
.Sy Default:
.Em no
.br
.Sy Example:
.Dl use_xcode yes
.El
.Sh DESTROOT OPTIONS
Execute necessary commands to install into a temporary destination root
.Pf ( Dq 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 scons
.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
.It Ic 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
.Xr porthier 7 .
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em yes no
.br
.Sy Default:
.Em no
.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 macOS 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 macOS this is always
.Pa launchd .
A global default may be specified with the
.Ic startupitem_type
preference in
.Pa macports.conf .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em default
.br
.Sy Values:
.Em launchd default none
.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.autostart
Whether to automatically load the startupitem after activating the port.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.Sy Values:
.Em yes|no
.br
.Sy Example:
.Dl startupitem.autostart yes
.It Ic startupitem.debug
Enable additional debug logging.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.Sy Values:
.Em yes|no
.br
.Sy Example:
.Dl startupitem.debug yes
.It Ic startupitem.executable
The name of the daemon to be run in the background.
This is the preferred type of startupitem rather than any of
.Ic startupitem.init ,
.Ic startupitem.start ,
.Ic startupitem.stop ,
or
.Ic 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
.Li 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
.Ic startupitem.start ,
.Ic startupitem.stop
and
.Ic startupitem.restart .
.br
.Sy Type:
.Em optional
.br
.Sy Values:
.Em sh code
.br
.Sy Example:
.Dl startupitem.init FOO=start
.It Ic startupitem.install
Whether to install a link to the startupitem in the appropriate subdirectory
of
.Pa /Library .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em yes
.br
.Sy Values:
.Em yes|no
.br
.Sy Example:
.Dl startupitem.install no
.It Ic startupitem.location
Chooses the subdirectory in which to install the startupitem.
Also affects how it will be loaded:
.Li LaunchDaemons
must be loaded as root, and only one instance will run for the whole system.
.Li LaunchAgents
are loaded as a normal user, and one instance per user can run.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em LaunchDaemons
.br
.Sy Values:
.Em LaunchDaemons
.Em LaunchAgents
.br
.Sy Example:
.Dl startupitem.location LaunchAgents
.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:
.Bd -literal -offset indent -compact
startupitem.start ${prefix}/share/mysql/mysql.server start
.Ed
.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:
.Bd -literal -offset indent -compact
startupitem.stop ${prefix}/share/mysql/mysql.server stop
.Ed
.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:
.Bd -literal -offset indent -compact
startupitem.restart ${prefix}/share/mysql/mysql.server restart
.Ed
.It Ic startupitem.pidfile
Specification for pidfile handling.
This is particularly useful in conjunction with the
.Ic startupitem.executable
key, because it is important that the startupitem knows how to track the
executable.
This specifies whether the daemon generates its own pidfile
.Pf ( Dq auto ) ,
whether it generates its own but forgets to delete it, so that the startupitem
should delete it
.Pf ( Dq clean ) ,
or whether it never generates one, in which case the startupitem should manage
the pidfile on its own
.Pf ( Dq manual ) ,
or whether no pidfile should be used at all
.Pf  ( Dq none ) .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none "${prefix}/var/run/${name}.pid"
.br
.Sy Values:
.Po
.Em none
|
.Em auto
|
.Em manual
|
.Em clean
.Pc
.Bq Pa /path/to/pidfile
.br
.Sy Example:
.Bd -literal -offset indent -compact
startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile
.Ed
.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.logfile.stderr
Path to a logfile for capturing standard error output from the daemon.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em startupitem.logfile
.br
.Sy Values:
.Em path
.br
.Sy Example:
.Dl startupitem.logfile.stderr ${prefix}/var/log/mydaemon.log
.It Ic startupitem.logevents
Control whether or not to log events to the log file.
If this option 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
.It Ic startupitem.netchange
Control whether the startupitem should be restarted when a change in the
machine's network state is detected.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em no
.br
.Sy Values:
.Em yes|no
.br
.Sy Example:
.Dl startupitem.netchange yes
.It Ic startupitem.user
Run the daemon via the specified user.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none
.br
.Sy Values:
.Em username
.br
.Sy Example:
.Dl startupitem.user my_daemon_username
.It Ic startupitem.group
Run the daemon via the specified group.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none
.br
.Sy Values:
.Em groupname
.br
.Sy Example:
.Dl startupitem.group my_daemon_groupname
.It Ic startupitems
Used when a port needs to install more than one startupitem, this option
consists of a list where alternating elements represent keys and values.
Each key corresponds to one of the
.Ic startupitem.*
options, and the following value is associated with it.
Each startupitem defined in the list must specify at least a name.
Each other key/value pair is associated with the startupitem named most
recently in the list.
Any keys that are not defined for a given startupitem will use the value of
the corresponding
.Ic startupitem.*
option.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em none (empty)
.br
.Sy Values:
.Em List of keys and values
.br
.Sy Example:
.Bd -literal -offset indent -compact
startupitems name        myport-system \e
             location    LaunchDaemons \e
             executable  ${prefix}/sbin/myportd \e
             name        myport-session \e
             location    LaunchAgents \e
             executable  ${prefix}/bin/myport-agent
.Ed
.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.
.Pp
Two checks are available.
With
.Dq distcheck ,
MacPorts can check that the distfile(s) are still downloadable and did not
change since the Portfile was modified.
With
.Dq 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.type
What kind of check to perform to figure out if the software has been updated.
Can be
.Em freecode
(uses the
.Li date_updated
tag of the freecode XML file),
.Em sourceforge
(uses the version of the latest file release of the project),
.Em googlecode
(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 git
(retrieve the commit from a remote git branch),
.Em md5
(compares the md5 sum of some URL resource) or
.Em none
(no check).
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em sourceforge
or
.Em googlecode
if the
.Ic master_sites
is one of these, else
.Em freecode
.br
.Sy Values:
.Em freecode sourceforge googlecode moddate regex regexm git md5 none
.It Ic livecheck.name
Name of the project for live checks (used for freecode, sourceforge, and googlecode checks).
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${name}
or the sourceforge/freecode/googlecode project name if it can be guessed by
looking at
.Ic master_sites .
.It Ic 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
.Dq Li (.*) .
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em ${livecheck.name}
for sourceforge projects or the first entry in
.Em ${distfiles}
for googlecode projects
.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://freecode.com/projects/${livecheck.name}/releases.atom
or
.Em http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}
or
.Em http://code.google.com/p/${livecheck.name}/downloads/list
.It Ic livecheck.regex
Regular expression to parse the resource for regex checks.
Be sure to use a regular expression grouping around the version component.
.br
.Sy Type:
.Em optional
.It Ic livecheck.branch
git branch to use for getting latest commit.
.br
.Sy Type:
.Em optional
.It Ic livecheck.md5
md5 sum to use for md5 comparison.
.br
.Sy Type:
.Em optional
.It Ic livecheck.user_agent
HTTP User-Agent to use when fetching the livecheck resource.
Useful for servers that block requests from the default curl user agent.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em \&""
.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
.Op Cm description Ar "description"
.Xc
The value is usually a TCL script which modifies one or more
.Nm
variables.
Dependencies and conflicts with other variants in the same port can be
expressed with
.Cm requires
and
.Cm conflicts .
.Cm description
provides a means to supply a description of the variant for the user.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
Add a
.Dq gnome
variant to a port.
.Bd -literal -offset indent -compact
variant gnome requires glib \e
    { configure.args-append --with-gnome \e
      depends_lib-append port: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
.It Ic universal_variant
When using MacPorts on macOS, a universal variant is defined and
the default behavior is to configure ports with universal flags
(see the
.Ic 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
.Ic universal_variant
option.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em yes
.br
.Sy Example:
.Dl universal_variant no
.El
.Sh PLATFORM OPTIONS
MacPorts allows for platform-specific conditional code to be
specified in a
.Nm ,
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
.Ar body
.Xc
The body is executed if the given platform/version/arch combination matches
.Ic os.platform
or
.Ic os.subplatform
and/or
.Ic os.major
and/or
.Ic os.arch .
The following examples are from the
.Pa lang/php5 ,
.Pa audio/flac
and
.Pa sysutils/getopt
.Nm Portfiles ,
respectively.
.br
.Sy Type:
.Em optional
.br
.Sy Examples:
.Bd -literal -offset indent -compact
platform darwin 10 \e
    { configure.env-append LIBS=-lresolv }
platform darwin i386 \e
    { configure.args-append --disable-asm-optimizations }
platform darwin 8 powerpc \e
    { configure.universal_ldflags-append -liconv }
.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
.Nm 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 details.
.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 fs-traverse
.Op Fl depth
.Op Fl ignoreErrors
.Op Fl tails
.Op Fl -
.Ar varname
.Ar target-list
.Ar body
.Xc
Traverse the filesystem hierarchy rooted in each element of
.Ar target-list
and execute
.Ar body
for each found file/directory.
.Va target-list
should always be specified as a list even if contains only one item.
.Va varname
is set to the path of the file/directory.
If
.Ic break
is called during execution, the filesystem traversal is stopped.
If
.Ic continue
is called during execution, the current file and any children are skipped
and traversal continues with the next file/directory.
.Bl -tag -width indent
.It Fl depth
Equivalent to the
.Fl d
switch to
.Xr find 1 .
Please note that using
.Fl depth
means you cannot prune a directory with
.Ic continue
as it will be processed after its children.
.It Fl ignoreErrors
Causes
.Ic fs-traverse
to ignore any permissions/read errors encountered during processing.
.It Fl tails
Returns paths relative to the top-level directory being traversed, as opposed to
absolute paths. When
.Fl tails
is used
.Va target-list
can contain only one item.
.It Fl --
Ignores any further flags and interprets the next parameter as
.Va varname
even if it begins with a dash.
.El
.Pp
If
.Nm fs-traverse
is called directly on a symbolic link, the link will be followed.
All other links encountered during traversal will not be followed.
.Pp
.Nm fs-traverse
will not descend into directories that have a different device number than
the root of the descent.
.Pp
If you remove the current directory during traversal, be aware that you must call
.Nm continue
to inform
.Nm fs-traverse
that the directory should not be descended into.
.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 Ar uid
.Op Cm gid Ns = Ns Ar gid
.Op Cm passwd Ns = Ns Ar passwd
.Op Cm realname Ns = Ns Ar realname
.Op Cm home Ns = Ns Ar home
.Op Cm shell Ns = Ns Ar shell
.Xc
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
.Ic 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).
.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 Ar gid
.Op Cm passwd Ns = Ns Ar passwd
.Op Cm realname Ns = Ns Ar realname
.Op Cm users Ns = Ns Ar users
.Xc
Add a new local group to the system, with the specified gid, password,
real name, 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
.Ic adduser :
.Dl addgroup foo
.Dl adduser foo gid=[existsgroup foo]
.It Ic nextgid
Returns the highest used gid plus one.
.It Xo
.Ic reinplace
.Op Fl E
.Ar regex
.Ar
.Xc
Provide in-place
.Xr sed 1
like editing of a file.
The
.Fl E
flag does the same thing as in
.Xr sed 1 .
.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.
Use
.Nm xinstall
to also preserve Extended Attributes (i.e., Access Control Lists).
See
.Xr file n
for more information on this command.
.It Ic copy
Built-in shorthand alternative to
.Dq file copy .
.It Ic move
Built-in shorthand alternative to
.Dq file rename .
.It Ic delete Ar
Deletes each of the given files/directories.
Behaves identically to
.Ic file delete -force .
.It Ic touch
Built-in command mimicking the BSD touch command.
.It Ic ln
.br
Built-in command mimicking the BSD ln command.
.It Xo
.Ic system
.Op Fl W Ar dir
.Ar commandline
.Xc
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 the built-in commands or
.Nm file
if they don't meet your requirements.
.Bl -tag -width indent
.It Fl W
Change to
.Ar dir
before working.
.El
.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 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 Va variable Ns - Ns Ic replace Ar old_item new_item
Replace
.Ar old_item
with
.Ar new_item
in the
.Va variable .
.br
.Sy Example:
.Dl configure.args-replace --with-gnomedb --without-gnomedb
.It Ic readdir Ar directory
Return the list of elements in a
.Ar directory ,
excluding
.Dq Pa \&.
and
.Dq 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 mkdtemp Ar template
Create a temporary directory using a
.Ar template .
See
.Xr mkdtemp 3 .
.It Ic md5 Ar
Compute the MD5 hashes of the file(s).
.It Ic vercmp Ar versionA Ar versionB
Compare two EVR-format versions for equality.
The return value is like
.Xr strcmp 3 ,
returning -1, 0, or\~1 when
.Ar versionA
is earlier, equal to, or
later than
.Ar 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).
.It Xo
.Ic lpush
.Ar varName
.Op Ar value \&...
.Xc
Treats the variable given by
.Ar varName
as a list and appends each of the
.Ar value
arguments to that list as a separate element.
If
.Ar varName
doesn't exist, it is created as a list with elements
given by the
.Ar value
arguments.
Really just an alias for
.Xr lappend n .
.It Ic lpop Ar varName
Removes the last element from the list given by
.Ar varName
and returns it.
If there are no elements in the list, the empty string is returned.
If
.Ar varName
doesn't exist, an exception is raised.
.It Xo
.Ic lunshift
.Ar varName
.Op Ar value \&...
.Xc
Treats the variable given by
.Ar varName
as a list and prepends each of the
.Ar value
arguments to that list as a separate element.
If
.Ar varName
doesn't exist, it is created as a list with elements
given by the
.Ar value
arguments.
.It Ic lshift Ar varName
Removes the first element from the list given by
.Ar varName
and returns it.
If there are no elements in the list, the empty string is returned.
If
.Ar varName
doesn't exist, an exception is raised.
.It Xo
.Ic ldindex
.Ar varName
.Op Ar index \&...
.Xc
Treats the variable given by
.Ar varName
as a list and removes the element pointed to by the sequence of
.Ar index
arguments and returns it.
If no
.Ar index
arguments are provided,
.Ar varName
is set to the empty string and the entire former value is returned.
Has the same usage semantics as
.Xr lindex n .
.It Xo
.Ic macports_try
.Op Ar -pass_signal
.Ar body
.Oo
.Ar handler Ar \&...
.Oc
.Op Nm finally Ar script
.Xc
Tcl try block with optional signal pass-thru. When signal pass-thru is not required, use the native try.
.br
.Sy Example:
Basic try-finally construct with signal passing.
.Bd -literal -offset indent -compact
macports_try -pass_signal {
    set fd [open $file r]
    # do stuff here
} finally {
    close $fd
}
.Ed
.Sy Example:
Basic try-on error construct
.Bd -literal -offset indent -compact
macports_try -pass_signal {
    set result [expr $num / $div]
} trap {ARITH DIVZERO} {eMessage eOptions} {
    set result -1
}
.Ed
.Sy Example:
Basic try with multiple handlers construct
.Bd -literal -offset indent -compact
macports_try -pass_signal {
    set fd [open $file r]
    # do stuff here
} trap {POSIX ENOENT} {eMessage eOptions} {
    puts stderr $eMessage
} on error {_ eOptions} {
    puts stderr "An error occurred while processing the file"
    close $fd
    throw [dict get $eOptions -errorcode] [dict get $eOptions -errorinfo]
}
.Ed
.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 \*qThis build may take a very long time\*q
.El
.Sh SEE ALSO
.Xr port 1 ,
.Xr macports.conf 5 ,
.Xr portgroup 7 ,
.Xr portstyle 7 ,
.Xr porthier 7 ,
.Xr file n
.Sh AUTHORS
.An "Landon Fuller" Aq landonf@macports.org
.An "Juan Manuel Palacios" Aq jmpp@macports.org
.An "Mark Duling" Aq markd@macports.org
.An "Kevin Van Vechten" Aq kevin@opendarwin.org
.An "Jordan K. Hubbard" Aq jkh@macports.org
.An "Chris Ridd" Aq cjr@opendarwin.org
.An "Kevin Ballard" Aq eridius@macports.org
.An "Markus W. Weissmann" Aq mww@macports.org