<commit_before>.\" 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 17, 2003
.Dt PORTFILE 7 "Apple Computer, Inc."
.Os
.Sh NAME
.Nm Portfile
.Nd Darwinports 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 Darwinports 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 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 <EMAIL> <EMAIL>
.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 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
.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 Darwinports 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/${portname}/
.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 x11prefix
Absolute path to X11 (eg
.Pa /usr/X11R6 )
.br
.Sy Type:
.Em read-only
.El
.Sh DEPENDENCY OPTIONS
Each dependency for the port is expressed in the format:
.Bl -tag -width lc
.It Ar type Ns : Ns Ao filename Ac Ns : Ns Ao port Ac
.El
.Pp
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. If the dependency is really on a whole port and not an
individual file, then the alternative syntax:
.Bl -tag -width ls
.It port: Ns Ao port Ac
.El
.Pp
should be used.
.Ao port Ac represents the name of an existing Darwinports
.Nm port .
.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 bin:autoconf: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 bin:bash: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 lib:libfetch.3: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 the actual 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.tag
CVS tag identifying the code to checkout.
.br
.Sy Type:
.Em optional
.It Ic cvs.date
Date identifying the code to checkout.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl cvs.date \*q12-April-2005\*q
.It Ic cvs.module
CVS module to check the code out from.
.br
.Sy Type:
.Em optional
.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 STARTUPITEMS OPTIONS
If a port needs to run on system startup, it can use the Darwinports
startup mechanism.
.Bl -tag -width lc
.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.type
Form of startup item to install.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em SystemStarter
.br
.Sy Values:
.Em SystemStarter RCng
.El
.Sh VARIANT OPTIONS
Darwinports 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
Darwinports 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 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 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.<commit_msg>Document the new curl command.<commit_after>.\" 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 17, 2003
.Dt PORTFILE 7 "Apple Computer, Inc."
.Os
.Sh NAME
.Nm Portfile
.Nd Darwinports 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 Darwinports 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 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 <EMAIL> <EMAIL>
.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 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
.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 Darwinports 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/${portname}/
.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 x11prefix
Absolute path to X11 (eg
.Pa /usr/X11R6 )
.br
.Sy Type:
.Em read-only
.El
.Sh DEPENDENCY OPTIONS
Each dependency for the port is expressed in the format:
.Bl -tag -width lc
.It Ar type Ns : Ns Ao filename Ac Ns : Ns Ao port Ac
.El
.Pp
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. If the dependency is really on a whole port and not an
individual file, then the alternative syntax:
.Bl -tag -width ls
.It port: Ns Ao port Ac
.El
.Pp
should be used.
.Ao port Ac represents the name of an existing Darwinports
.Nm port .
.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 bin:autoconf: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 bin:bash: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 lib:libfetch.3: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 the actual 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.tag
CVS tag identifying the code to checkout.
.br
.Sy Type:
.Em optional
.It Ic cvs.date
Date identifying the code to checkout.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl cvs.date \*q12-April-2005\*q
.It Ic cvs.module
CVS module to check the code out from.
.br
.Sy Type:
.Em optional
.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 STARTUPITEMS OPTIONS
If a port needs to run on system startup, it can use the Darwinports
startup mechanism.
.Bl -tag -width lc
.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.type
Form of startup item to install.
.br
.Sy Type:
.Em optional
.br
.Sy Default:
.Em SystemStarter
.br
.Sy Values:
.Em SystemStarter RCng
.El
.Sh VARIANT OPTIONS
Darwinports 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
Darwinports 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 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.
{'fraction_non_alphanumeric': 0.08935308266869224, 'fraction_numerical': 0.00997594632231928, 'mean_word_length': 3.2666090526088367, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '601301', 'n_tokens_mistral': 14504, 'n_tokens_neox': 13845, 'n_words': 6331}