Portfile details
This Chapter describes in detail how each part of a portfile is
works and is used.
General syntax
A Portfile is a TCL script, so the syntax used must be valid
TCL or the Portfile will not work. The basic syntax of the Portfile
has been designed so most tasks are performed using key value(s)
combinations. Many people don't realise it is TCL until they want to do
something more advanced and realise all that power is there.
All key value pairs in a Portfile are single lines so line breaks
must be escaped with a back slash ('\').
Variables syntax is ${foo} for the foo variant.
Special characters
As the Portfile is a TCL script certain charachters are
"special". These have a special meaning in TCL and if you dont
want that special meaning, they must be escaped. In general a
character is escaped using the back slash ('\'). The main
characters you need to be careful with are
$
}
}
[
]
Required keys
There is a small set of required key/value pairs without
which a Portfile cannot be correct.
The required keys are
PortSystem
name
version
platforms
maintainers
categories
description
master_sites
checksums
homepage
long_description
Each of these keys is described in the following pages of
the guide.
Useful preset variables
prefix
Installation prefix, set in the systemwide
configuration file /etc/ports/ports.conf. Can be
overridden on a per port basis. For example XFree86
needs to install in the /usr tree, or aqua applications
are installed in /Applications/Ports
libpath
Path to the DarwinPorts TCL libraries. Read
only.
portpath
Path to the directory containing the downloaded
Portfiles. Read Only.
filedir
Path to port files relative to ${portpath}.
Read Only.
workdir
Path to work directory relative to ${portpath}.
Read Only
workpath
Full path to work directory. Read only.
distpath
Location to store downloaded distfiles. Read
Only
os_arch
Identifies hardware type (ie, "Power Macintosh").
Read Only
os_version
Version number of operating system (ie "6.0").
Read Only.
Initialization phase
The first part of a Portfile deals with initialisation. Most
of the keys (or options) in the initialisation phase are required
for all Portfiles.
PortSystem
Determines which version of the portsystem the
Portfile is compatible with. DarwinPorts supports
versioning of the PortSystem so if new, backwards
incompatible changes are introduced older Portfiles
can continue to use the older version of the system.
The PortSystem line wraps the loading of TCL libraries
appropriate for that version of DarwinPorts. If you
don't load the libraries, nothing else in the Portfile
will work. Thus, the PortSystem should be the top line
in the Portfile.
Currently DarwinPorts only has version 1.0 so you
should put: PortSystem 1.0 in your
Portfile.
name
The name of the Port. By default this is used to
build the url from which the Port is fetched. The name
should be lowercase.
name foo
version
The version of the Port. By default this is used to
build the url from which the Port is fetched.
version 1.23.45
platforms
The platforms on which the port has been
tested.
platforms darwin freebsd
categories
The type of Port. The first category should be the
same as the directory in which the Portfile is stored
and therefore should be chosen with care. A Port may have
more that one category but is not required to.
categories foo bar
description
One sentence describing what the port is, use
long_description for more detail. If you use
long_description you must still use description.
description foo performs the
transformation of bar into xml
long_description
Description of what the port is/does. Long lines
can be broken with escaped newlines.
long_description foo
performs the transformation of bar into xml \
This allows users to rapidly transform documentation into multiple \
formats.
maintainers
List the email address or addresses of the
Portfile maintainer(s)
maintainers
joeblogs@somerandom.domain.com
revision
Local revision number of portfile. Increment
for port revisions. The default for this is 0. It
should be incremented for revisions that change the
installed port.
revision 1.1
distname
By default distname is ${name}-${version}.
Specifying distname is optional, only use it if the
file that contains the port is not ${name}-${version}
(without the extract.suffix).
distname ${name}_${version}
distfiles
Defaults to ${distname}.${extract.suffix}. Specifying
distfiles is optional, only use it if the file that
contains the port is not ${distname}.${extract.suffix}
or more than one file needs to be retirieved.
distfiles stable.${extract.suffix}
installer.sh
Some ports require multiple items to be fetched
from different sites, this can be achieved using tags.
The tags are then used to identify which of the
master_sites to fetch the file from.see master_sites
below for more information. As with long_description,
long lines should be broken up with escaped
newlines.
distfiles
stable.${extract.suffix}:source
installer.sh:install
use_zip
Specifying use_zip is optional, only use it if
the file downloades is zipped rather than tarred and
gziped. use_zip set ${extract.suffix} to .zip and
extract.cmd to unzip, extract.pre_args to -q and
extract.post_args to "-d $portpath/$workdir".
use_zip yes
use_bzip2
Specifying use_bzip2 is optional, only use it
if the file downloades is bzipped rather than tarred
and gziped. use_bzip2 set ${extract.suffix} to .bzip2
and extract.cmd to bzip2.
use_bzip2 yes
Fetch phase
master_sites
A whitespace delimited list of urls from which the
source of the port can be retrieved. The URL should not
include the name of the file being retrieved.
If you have multiple sites you should break up
long lines with escapend newlines.
master_sites http://www.somesite.org/files/ \
http://www.somemirror.org/somesite_org/files/
Always put the trailing forward slash at the
end of a url, and remember to not include the filename
itself.
If you need to retrieve files from different
sites you can label the urls with tags.
master_sites http://www.somesite.org/files/:source \
http://www.someothersite.org/somesite_extras/:extras
master_sites.mirror_subdir
Subdirectory to add to mirror sites taken from a
mirror sites list. Please see the section below on
Mirror Site Lists for more details.
patch_sites
List sites from which to download patchfiles
from, syntax is the same as master_sites. See the
Patch phase below for more information.
patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches
patch_sites.mirror_subdir
Subdirectory to add to mirror sites taken from a
mirror sites list. Please see the section below on
Mirror Site Lists for more details.
Mirror Site Lists
Mirror site lists are, as one might guess, predefined
lists of mirror sites for use in
master_sites or
patch_sites. The basic usage of mirror
site lists in a Portfile is:
master_sites sourceforge http://distfiles.opendarwin.org/
master_sites.mirror_subdir ${name}
Where 'sourceforge' is the name of
the mirror list which specifies SourceForge mirrors.
master_sites.mirror_subdir is used to
specify the subdirectory of all sites
in in any mirror lists in which the file is found. The
above example is equivalent to:
master_sites http://us.dl.sourceforge.net/${name}/ \
http://eu.dl.sourceforge.net/${name}/ \
ftp://us.dl.sourceforge.net/pub/sourceforge/${name}/ \
...
http://distfiles.opendarwin.org/
There are two potential problems when using mirror
site lists as described above. First, if you are using
multiple mirror site lists, such as
sourceforge and gnu,
the subdirectory might not always be the same. Second, if
you have multiple distfiles and are using distfile tags to
specify which site in master_sites to
download which file from.
Fortunately DarwinPorts also provides a much more
powerful and flexible syntax for mirror site lists.
distfiles file_one.tar.gz:tagone file_two.tar.gz:tagtwo file_three.tar.gz
master_sites sourceforge::tagone gnu:directory:tagtwo \
http://distfiles.opendarwin.org/
master_sites.mirror_subdir ${name}
At first glance, this example is probably quite
confusing. Basically, the advanced syntax is
list:subdirectory:tag. The above
example shows the many ways this can be used. The above
example will:
Look for file_one.tar.gz
in:
http://us.dl.sourceforge.net/${name}/
http://eu.dl.sourceforge.net/${name}/
ftp://us.dl.sourceforge.net/pub/sourceforge/${name}/
...
Look for file_two.tar.gz
in:
ftp://ftp.gnu.org/gnu/directory/${name}/
ftp://gatekeeper.dec.com/pub/GNU/directory/${name}/
ftp://ftp.uu.net/archive/systems/gnu/directory/${name}/
...
Look for file_three.tar.gz
in:
http://distfiles.opendarwin.org/
There are a few important points to remember when
using this syntax. The subdirectory specified with the
list
(gnu:directory) is
appended to all of the mirror sites in that list
before the
master_sites.mirror_subdir, and
master_sites.mirror_subdir is
always appended to the end of the
mirror site. When using tags, you are not required to
specify a subdirectory
(sourceforge::tagone).
master_sites.mirror_subdir is also not
required when specifying a subdirectory with the
list.
The original example could also be have been written
using this syntax without the need of
master_sites.mirror_subdir like
this:
master_sites sourceforge:${name} http://distfiles.opendarwin.org/
The mirror site lists functionality also works exactly
the same for patch_sites and
patch_sites.mirror_subdir.
Below is a list of the mirror site lists that can be
used.
apache
gnome
gnu
isc
kde
perl_cpan
ruby
sourceforge
sunsite
tcltk
xcontrib
xfree
Integrity checking phase
Each file downloaded is integrity checked using a checksum.
This is used to help prevent trojaned sources being downloaded.
If you do not include the checksums line, the file will be
downloaded and the checksum reported as a conenience to the Portfile
author.
checksums
Currently only the md5 checksum is supported.
Specify the filename, the checksum type and the
checksum.
${distname}-${extract.suffix} md5 65b89365a65dcad71d4402b48 \
foo.tar.gz md5 65b89365a65dcad71d4402b44
If you only have one file being fetched the
filename can be omitted.
md5 65b89365a65dcad71d4402b48
Extract phase
Patch phase
patchfiles
List of patch files to apply to source. Patch
files can be supplied in a port in a directory named
files (based on the value of ${filepath}) within the
port directory or fetched from ${patchsites}. Each
patchfile supplied by the Portfile author should
patch a single file. The standard convention is to
name the patch file 'patch-<filename>.diff,
with one diff file per file altered in the source.
If the filename is ambiguous because there are
multiple files with that name in the distribution,
supply the path components to uniquely identify the
file being patched. Diffs should be created with
diff -u file1
file2 >../../files/patch-file.diff.
Patches downloaded from patchsites must have
checksumes.
patchfiles patch-Makefile.in
patch-source.c
Configuration phase
Automake and autoconf
use_automake
If set to yes, use automake
use_automake yes
automake.env
Environmental variables to pass
to automake
CFLAGS="-I'${prefix}/include'"
automake.args
Arguments to pass to automake.
automake.args --foreign
automake.dir
Directory in which to run ${automake.cmd}.
Defaults to ${worksrcpath}
automake.dir
use_autoconf
If set to yes, run autoconf.
use_autoconf yes
autoconf.env
Environmental variables to pass to
autoconf
autoconf.env
CFLAGS=-I'${prefix}/include/gtk12'
autoconf.args
Arguments to pass to autoconf.
autoconf.args -l
src/aclocaldir
autoconf.dir
Directory in which to run
${autoconf.cmd}.
autoconf.dir
src
configure
configure.env
Set environment variables for
configure.
configure.env
CFLAGS="-I'${prefix}/include'"
configure.pre_args
Arguments added to configure command
before ${configure.args}. Defaults to
--prefix=${prefix}.
configure.pre_args
--prefix="${prefix}/apache2"
configure.args
Arguments to pass to configure.
configure.args
--etcdir="${prefix}/etc"
Build phase
build.cmd
Make command to run relative to ${worksrcdir}.
Defaults to make.
build.cmd pbxbuild
build.type
Defines which 'make' is required, either 'gnu'
or 'bsd' Sets build.cmd to either
'gnumake' or 'bsdmake' accordingly
build.type gnu
build.pre_args
Arguments to pass to ${build.cmd} before
${build.args}. Read only. Set to
${build.target.current}
build.args
Arguments to pass to ${build.cmd}
build.args
-DNOWARN
build.target
Target to pass to make for building everything.
Defaults to all.
build.target.all all-src
Install phase
install.cmd
Install command to run relative to ${worksrcdir}.
Defaults to ${build.cmd}.
install.cmd pbxbuild
install.type
Defines which 'make' is required, either 'gnu' or
'bsd' Sets install.cmd to either
'gnumake' or 'bsdmake' accordingly
install.type gnu
install.pre_args
Arguments to pass to ${install.cmd} before
${install.args}. Read only. Set to ${install.target}
install.args
Arguments to pass to ${install.cmd}
install.args -DNOWARN
install.target
Install target to pass to ${install.cmd}.
install.target all-src
install.destroot
Arguments passed to ${install.cmd} in order to
install correctly into the destroot.
All ports must install via the 'destroot' so
that the DarwinPorts infrastructure can register each
file and directory a port installs. Most autoconf based
build systems will behave correctly and respect DESTDIR,
however some will not. Most of those that do not respect
DESTDIR will install correctly if you use 'prefix', as
in the example below. If your port doesn't respect either
of these, you'll have to figure out what to do yourself.
Some ports use another term, others require you to patch
the Makefile (or other build related script).
install.destroot prefix=${destroot}${prefix}
Dependencies
Principles
Dependency tests
depends_fetch
depends_extract
depends_lib
depends_build
depends_run
TCL primitives
reinplace
system
file
Other
Pre and post phase steps
Pre-*
Post-*
Overriding a phase