.\" 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 darwin ports 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
utiliziation of TCL's extensive functionality.
.Pp
The
.Nm Darwin Ports 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 provides.
.Sh TARGETS
.Tp
.Ss MAIN OPTIONS
Neccesary standard options
.Bl -tag -width lc
.It Ic prefix
Install prefix
.br
.Sy Type:
.Em optional
.Sy Default:
.Em /opt/local
.It Ic libpath
Locate of ports-specific TCL libraries
.br
.Sy Type:
.Em read-only
.It Ic workdir
Path to work directory relative to ${portpath}
.br
.Sy Type:
.Em read-only
.Sy Default:
.Em work
.It Ic workpath
Full path to work directory
.br
.Sy Type:
.Em read-only
.Sy Default:
.Em ${portpath}/${workdir}
.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 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:
.Dl long_description	The GNU Image Manipulation Program (GIMP) is a powerful tool for the preparation and manipulation of digital images.  The GIMP provides the user with a wide variety of image manipulation, painting, processing, and rendering tools.
.It Ic revision
Local revision number of portfile.
Increment for port revisions.
.br
.Sy Type:
.Em optional
.Sy Default:
.Em 0
.br
.Sy Example:
.Dl revision	1
.It Ic categories
Categories to which this port belongs
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl categories	spelling textproc
.It Ic maintainers
E-mail address(es) of port maintainer(s)
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl maintainers	landonf@opendarwin.org kevin@opendarwin.org
.It Ic platforms
Declares which platforms are supported by the port
.br
.Sy Type:
.Em required
.br
.Sy Values:
.Em darwin freebsd
.br
.Sy Example:
.Dl platforms	darwin
.It Ic worksrcdir
Path to source directory relative to ${workpath}
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${distname}
.br
.Sy Example:
.Dl worksrcdir	${distname}-src-${version}
.It Ic worksrcpath
Full path to working sources (where port has unpacked itself)
.br
.Sy Type:
.Em read-only
.Sy Default:
.Em ${workpath}/${worksrcdir}
.It Ic filesdir
Path to port files relative to ${portpath}
.br
.Sy Type:
.Em read-only
.Sy Default:
.Em files
.It Ic distname
Name of distibution file, minus extract suffix
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${name}-${version})
.br
.Sy Example:
.Dl distname	${name}-${version}-src
.It Ic distpath 
Location to store downloaded distfiles
.br
.Sy Type:
.Em read-only
.Sy Default:
.Em ${sysportpath}/distfiles/${portname}/
.It Ic os.arch
Identifies hardware type (ie, "powerpc")
.br
.Sy Type:
.Em read-only
.It Ic os.version
Version number of operating system (ie "6.0")
.br
.Sy Type:
.Em read-only
.El
.Ss DEPENDS OPTIONS
Checking and building of dependencies
.Bl -tag -width lc
.It Ic depends_fetch
List of dependencies to check before running fetch target
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl depends_fetch	bin:fetch:net/fetch bin:wget:wget
.It Ic depends_build
List of dependencies to check before build, destroot, install, and 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 destroot, install and package targets
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl depends_run	bin:bash:bash
.It Ic depends_extract
List of dependencies to check before extract target
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl depends_extract	bin:bzip2:bzip2
.It Ic depends_lib
List of dependencies to check before configure, build, destroot, install, and package targets
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl depends_lib	lib:libfetch.3:libfetch
.El
.Ss FETCH OPTIONS
Fetch all distribution files and patches
.Bl -tag -width lc
.It Ic master_sites
List of sites to fetch ${distfiles} from or a predefined mirror site list. If set to a predefined mirror site,
without a subdirectory being defined, the portname is used as the name of the subdirectory.
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl master_sites	ftp://ftp.cdrom.com/pub/magic \
			sourceforge
.It Ic patch_sites 
List of sites to fetch ${patchfiles} from or a predefined mirror site list
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${master_sites}
.br
.Sy Example:
.Dl patch_sites	ftp://ftp.patchcityrepo.com/pub/magic/patches
.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
.Sy Default:
.Em ${name}
.br
.Sy Example:
.Dl master_sites.mirror_subdir      magic
.It Ic patch_sites.mirror_subdir
Subdirectory to append to all mirror sites for any list specified in patch_sites.
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${name}
.br
.Sy Example:
.Dl patch_sites.mirror_subdir       magic
.It Ic extract.suffix
Suffix to append to ${distname}
.br
.Sy Type:
.Em optional
.Sy Default:
.Em .tar.gz
.br
.Sy Example:
.Dl extract.suffix	.tgz
.It Ic distfiles
List of distribution files to fetch from ${master_sites}
.br
.Sy Type:
.Em optional
.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 ${distpath} to store all fetched files.
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${name}
.br
.Sy Example:
.Dl dist_subdir	vim${version}
.El
.Ss CHECKSUM OPTIONS
Compare checksums of all fetched files
.Bl -tag -width lc
.It Ic checksums
List of checksums in the format:
.br
<file name> <checksum type> <checksum> [<checksum type> <checksum>] ...
.br
Checksum type currently can be md5 or sha1
.br
.Sy Type:
.Em required
.br
.Sy Example:
.Dl checksums dictd-1.7.1.tar.gz md5 81317b86ea0a5df0163900ad2e6bb12c
                magic-words-1.7.1.tar.gz md5 897a005182928613eadd30c267ce9c5b
.br
File name can be omitted if there is a single distfile.
.br
.Sy Example (ledit 1.11):
.Dl checksums  md5 a2d38ba641682509c1e964ad699a9dd2
                sha1 1fb6443b5fdf3c83787953f06282d256477c1288
.El
.Ss EXTRACT OPTIONS
Extract all compressed/archived files
.Bl -tag -width lc
.It Ic extract.only
List of files to extract into ${workpath}
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${distfiles}
.br
.Sy Example:
.Dl extract.only	worksrc-1.4.4.tar.gz
.It Ic extract.cmd
Command to perform extract
.br
.Sy Type:
.Em optional
.Sy Default
.Em gzip
.br
.Sy Example:
.Dl extract.cmd	bzip2
.It Ic extract.pre_args
Arguments added to extract command before a file name
.br
.Sy Type:
.Em optional
.Sy Default:
.Em -dc
.br
.Sy Example:
.Dl extract.pre_args	-cd
.It Ic extract.args
Arguments to extract.cmd
.br
.Sy Type:
.Em read-only
.Sy Default:
.Em ${distpath}/${distfile}
.It Ic extract.post_args
Arguments added to extract command after a file name
.br
.Sy Type:
.Em optional
.Sy Default:
.Em "| tar -xf -"
.br
.Sy Example:
.Dl extract.post_args	| tar -x -s@bladeenc-0.94.2/other_makefiles/BladeEnc..@@p -f -
.El
.Ss PATCH OPTIONS
Apply all necessary patches to the extracted source
No options defined for patch. Move patchfiles here?
.Ss CONFIGURE OPTIONS
Execute necessary configuration steps
.Bl -tag -width lc
.It Ic configure.pre_args
Arguments added to configure command before ${configure.args}
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl configure.pre_args		--prefix=${prefix}/apache2
.It Ic configure.args
Arguments to pass to configure.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl configure.args		--etcdir=${prefix}/etc
.It Ic configure.dir
Directory in which to run ${configure.cmd}
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${workpath}/${worksrcdir}
.br
.Sy Example:
.Dl configure.dir		src
.It Ic configure.env
Environmental variables to set during configure command
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl configure.env       CFLAGS="-no-cpp-precomp"
.It Ic use_automake
If set to yes, use automake
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_automake	yes
.It Ic automake.env
Environmental variables to pass to automake
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl automake.env	CFLAGS=-I${prefix}/include/gtk12
.It Ic automake.args
Arguments to pass to automake.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl automake.args	--foreign
.It Ic automake.dir
Directory in which to run ${automake.cmd}
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${workpath}/${worksrcdir}
.br
.Sy Example:
.Dl automake.dir		src
.It Ic use_autoconf
If set to yes, run autoconf
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl use_autoconf	yes
.It Ic autoconf.env
Environmental variables to pass to autoconf
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl autoconf.env	CFLAGS=I${prefix}/include/gtk12
.It Ic autoconf.args
Arguments to pass to autoconf
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl autoconf.args	-l src/aclocaldir
.It Ic autoconf.dir
Directory in which to run ${autoconf.cmd}
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${autoconf.dir}
.br
.Sy Example:
.Dl autoconf.dir	src
.It Ic xmkmf
Does nothing
.It Ic libtool
Does nothing
.El
.Ss BUILD OPTIONS
Execute necessary build commands
.Bl -tag -width lc
.It Ic build.cmd
Make command to run relative to ${worksrcdir}
.br
.Sy Type:
.Em optional
.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 build.cmd to either 'gnumake' or 'bsdmake' accordingly
.br
.Sy Type:
.Em optional
.Sy Default:
.Em gnu
.br
.Sy Example:
.Dl build.type	bsd
.It Ic build.pre_args
Arguments to pass to ${build.cmd} before ${build.args}
.br
.Sy Type:
.Em read-only
.Sy Default:
.Em ${build.target}
.It Ic build.args
Arguments to pass to ${build.cmd}
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl build.args	-DNOWARN
.It Ic build.env
Environmental variables to set during build command
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl build.env       CPPFLAGS="-no-cpp-precomp"
.It Ic build.target
Target passed to ${build.cmd} 
.br
.Sy Type:
.Em optional
.Sy Default:
.Em all
.br
.Sy Example:
.Dl build.target all-src
.El
.Ss DESTROOT OPTIONS
Execute necessary commands to install into temporary destination root ("destroot") staging area.
.Bl -tag -width lc
.It Ic destroot.cmd
Install command to run relative to ${worksrcdir}
.br
.Sy Type:
.Em optional
.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 destroot.cmd to either 'gnumake' or 'bsdmake' accordingly
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${build.type}
.br
.Sy Example:
.Dl destroot.type	gnu
.It Ic destroot.pre_args
Arguments to pass to ${destroot.cmd} before ${destroot.args}
.br
.Sy Type:
.Em read-only
.Sy Default:
.Em ${destroot.target}
.It Ic destroot.args
Arguments to pass to ${destroot.cmd}
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl destroot.args	-DPREFIX=${prefix}
.It Ic destroot.destdir
Arguments passed to ${destroot.cmd} in order to install correctly
into the destroot.
.br
.Sy Type:
.Em optional
.Sy Default:
.Em DESTDIR=${destroot}
.br
.Sy Example:
.Dl destroot.destdir	prefix=${destroot}${prefix}
.It Ic build.target.install
.br
.Sy Deprecated:
.Dl Replaced by destroot.target
.It Ic destroot.target
Install target to pass to ${destroot.cmd}
.br
.Sy Type:
.Em optional
.Sy Default:
.Em install
.br
.Sy Example:
.Dl destroot.target install-src
.El
.Ss 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 ${worksrcdir}
.br
.Sy Type:
.Em optional
.Sy Default:
.Em ${build.cmd}
.br
.Sy Example:
.Dl test.cmd	checks.sh 
.It Ic test.target
Test target to pass to ${test.cmd}
.br
.Sy Type:
.Em optional
.Sy Default:
.Em test 
.br
.Sy Example:
.Dl test.target	checks
.It Ic test.dir
Directory in which to run ${test.cmd}
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl test.dir	${worksrcpath}/checks 
.El
.Ss VARIANT OPTIONS
DarwinPorts allows for conditional modification to be specified in a Portfile, allowing for handling of software's build-time settings.
.Bl -tag -width lc
.It Ic variant 
The key variant is used to begin the gnome variant as shown in the example.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl variant gnome {	configure.args-append	--with-gnome \
				depends_lib-append		lib:gnome-session:gnome-session }
.El
.Ss PLATFORM OPTIONS
DarwinPorts allows for platform-specific conditional modification to be specified in a Portfile, much like variants, for handling differences between platforms and versions of the same platform.
.Bl -tag -width lc
.It Ic platform
The platform key is used to begin the darwin platform definitions as shown in the example from the databases/db4 Portfile.
.br
.Sy Type:
.Em optional
.br
.Sy Example:
.Dl platform darwin 6 { configure.args-append   --enable-tcl \
                                --with-tcl=/System/Library/Tcl/8.3 }
.br
The platform version is optional, and an optional architecture can be specified after the version.
.El
.Sh AUTHORS
.An "Landon Fuller" Aq landonf@opendarwin.org
.An "Kevin Van Vechten" Aq kevin@opendarwin.org
.An "Jordan K. Hubbard" Aq jkh@opendarwin.org