portfile
introduction
maintainer
Quick StartGetting Stated With DarwinPortsThis document will provide a short guide to the basics of a
DarwinPorts Portfile. A
Portfile is actually a Tcl script run by the
port system. Despite this, the
Portfile syntax is very
straightforward.In order to work with DarwinPorts, you will need to download and
install it on your system. The
Obtaining and Installing
DarwinPorts sections of this guide describes the process in
detail. Since you're interested in writing a
Portfile, you should invoke the
port with the (verbose
output) and the (debugging option) switches.
This will display useful messages that are usually suppressed
while running DarwinPorts.Basic Topics and ExamplesFetching the SourcesThe first step is to choose a piece of software to port.
For this example, we'll be porting ircII, a popular Internet relay
chat client.We can start with a simple Portfile
describing the basic attributes of ircII, such as its name,
version, and the site where we can download the sources. Create a working directory named ircII
and inside it create a file named Portfile
with the following contents:ircII Portfile# $Id: $
PortSystem 1.0
name ircii
version 20020912
categories irc
maintainers kevin@opendarwin.org
description an IRC and ICB client
long_description The ircII program is a full screen, termcap based \
interface to Internet Relay Chat. It gives full access \
to all of the normal IRC functions, plus a variety of \
additional options.
homepage http://www.eterna.com.au/ircii/
master_sites ftp://ircftp.au.eterna.com.au/pub/ircII/A Portfile consists of key/value pairs.
This example uses the following keys:# $Id: $Every Portfile starts with
#$Id: $. This is a RCS
Id tag (commented out with the '#' character
so that DarwinPorts is not confused by the tag). PortSystemFollowing the RCS Id tag comes the
PortSystem version declaration. Currently the
only valid version declaration is PortSystem
1.0.name and
versionThe name and
version keys describe the name and
version of the software.categoriesThe categories key is a list of the
logical categories to which the software belongs; this is
used for organizational purposes. The first entry in
categories should match the directory
in which the port's directory resides in the ports
tree.maintainersThe maintainers key should contain
the email address of the person or persons maintaining the port.description and
long_descriptiondescription provides a short (one line)
description of the port, while
long_description holds a more detailed
description of the software.homepageTo refer to the main web site of the software, the
homepage key is used.master_sitesThe master_sites key should contain
a list of sites where the distribution sources may be
downloaded by the port system. DarwinPorts uses the terms 'keys' and 'options'
interchangeably since most keys are used as options of a
particular task in the porting process.At this point, the Portfile is complete
enough to download ircII. By default, DarwinPorts will append
the version to name and
assume sources are in a gzipped tar archive with the
.tar.gz suffix. From your working directory, execute the following command:port -d -v checksumThe port command (when used without an explicit
port name operates on the Portfile in the current
working directory. You should see the following output:DEBUG: Executing com.apple.main (ircii)
DEBUG: Executing com.apple.fetch (ircii)
---> ircii-20020912.tar.gz doesn't seem to exist in /opt/local/var/db/dports/distfiles
---> Attempting to fetch ircii-20020912.tar.gz from ftp://ircftp.au.eterna.com.au/pub/ircII/
DEBUG: Executing com.apple.checksum (ircii)
Error: No checksums statement in Portfile. File checksums are:
ircii-20020912.tar.gz md5 2ae68c015698f58763a113e9bc6852cc
Error: Target error: com.apple.checksum returned: No checksums statement in Portfile.
Verifying the Downloaded FileNotice that DarwinPorts first checks for a local copy of
ircii-20020912.tar.gz and doesn't find it,
so it then downloads from the remove site. The port doesn't
finish because of an error: No checksums
statement in Portfile.
Portfiles must contain an md5 checksum of all distribution
files--this allows DarwinPorts to verify the accuracy and
authenticity of the sources. For convenience, an md5 checksum
of the downloaded files is printed when the
checksums argument is not specified. Go back
and add the following to your
Portfile:checksums md5 2ae68c015698f58763a113e9bc6852ccIf you have more than one file being fetched you should
specify the checksum for each in the form:checksums foo md5 ... \
bar md5 ...Extracting the Sources into a Working DirectoryNow that we have a checksum and can verify our sources, we
can proceed to extracting the sources into our working
directory. Execute the following:port -d -v extractWhich should display the following output:DEBUG: Skipping completed com.apple.main (ircii)
DEBUG: Skipping completed com.apple.fetch (ircii)
DEBUG: Executing com.apple.checksum (ircii)
---> Checksum OK for ircii-20020912.tar.gz
DEBUG: Executing com.apple.extract (ircii)
---> Extracting for ircii-20020912
---> Extracting ircii-20020912.tar.gz ... DEBUG: Assembled command: 'cd
/Users/kevin/opendarwin/proj/darwinports/dports/irc/ircii/work && gzip -dc /opt/local/var/db/dports/distfiles/ircii-20020912.tar.gz | tar -xf -'
DoneRunning a configure ScriptNow that the sources have been extracted into a
work directory in the Portfile
directory, we can configure the sources to compile with the
desired options. By default DarwinPorts assumes the software
you're porting uses an autoconf configure
script and will pass the
argument to configure, specifying that the
software should be installed in the directory tree used by
DarwinPorts.ircII's standard set of options is fine for a base
install on Darwin, so we won't add anything to the
configure phase and instead just
move on to the build phase. Please look at the
later chapters in this Guide for more information about
the Configuration phase.Building the SourcesTo build, type the following:port build -v -dBy default, the build phase executes the system's
make(1) utility. (This can be changed with
the build.type option which accepts an
argument of bsd, gnu, or
pbx. Alternatively, the
build.cmd option may be used to specify an
arbitrary build command.) The above step has started
compiling the sources, when it finishes we'll be ready to
install the software.Installing the Finished Product on the SystemThe former method of including a
contents list has been made obsolete by the
destroot mechanism. With
destroot the software is installed into a
directory tree below in the work
directory. While some software (like ircII) does not require
any special tweaks to be installed into the destroot, others
(like ncftp) need the install.destroot
option in order to correctly install into the
destroot.install.destroot mandir=${destroot}${prefix}/man prefix=${destroot}${prefix}Take a look at some of our ports to see more examples on
how to use the install.destroot
option.Now we have a complete Portfile.
Run the installation step to add your port to your own
registry. sudo port -d -v installWhich should finish with the output:
---> Adding ircii to registry, this may take a moment...Advanced TopicsOverriding TargetsIt's possible to override the functionality of any build
target with Tcl code. A common example is the following which
might be useful for a script without a configure script.
configure script:configure {}In the Portfile, this will replace
the functionality of the configure target,
thus skipping that step. It is also possible to execute Tcl
code immediately before or after any of the standard targets.
This can be accomplished using pre--<target> or
post-<target> in the following manner:post-configure {
reinplace "s|change.this.to.a.server|irc.openprojects.net|g" \
"${workdir}/${worksrcdir}/config.h"
}This example replaces the occurrence of
change.this.to.a.server with
irc.freenode.net in the
config.h file that was generated during
the preceding configure phase. Note this
is a somewhat contrived example, since the same could have
been accomplished by specifying
--with-default-server=irc.freenode.net
in configure.args, but the approach is
generally useful when such configure arguments aren't
present.Portfile VariantsSince Darwin 6.0 has ipv6, it would be possible to
configure with the --with-ipv6 option.
This can be done by adding the following option to the
Portfile:configure.args --disable-ipv6
variant ipv6 {
configure.args-append --enable-ipv6
}Now the default build will not include ipv6 support, but
if the ipv6 variant is requested, ircII will have it. Options
by themselves should be thought of as an assignment operator.
Since variants may be used in combination with one another,
it's good practice to only append to options instead of
overwriting them. All options may be suffixed with
-append or -delete to
append or delete one term from the list. You can specify
building with the ipv6 variant in the following way:port build +ipv6Mirror Site ListsIt is possible to use predefined lists of mirror sites in
your Portfile, such as SourceForge or GNU
mirrors. A full list of mirror site types is available in
Chapter 3, 'Fetch phase'. The straight-forward usage is:master_sites sourceforge http://distfiles.opendarwin.org/
master_sites.mirror_subdir ${name}This will search all of the mirror sites for SourceForge and
then http://distfiles.opendarwin.org, appending
${name} to the end of each SoureForge mirror
site in the list, for example:http://us.dl.sourceforge.net/${name}
ftp://us.dl.sourceforge.net/pub/sourceforge/${name}You can also use the mirror site lists in
patch_sites and use
patch_sites.mirror_subdir to specify the
subdirectory. For more information and advanced usage of mirror
site lists (i.e. distfile tags, multiple lists with different
subdirectories), please see Chapter 3, 'Fetch Phase'.Additional OptionsThere are additional options that are commonly used in
Portfiles. The following are commonly
used options that may be useful:distfiledistfile is the name and version
combined with the extract_sufx (by
default ${name}-${version}.tar.gz)
by default, and is used by DarwinPorts to fetch the
distribution file. If the name of the file on the server
is not the same as ${name}-${version}.tar.gz
you can use this option to override the default
distfile name. depends_libdepends_lib is used if the port
needs other libraries or binaries to be installed in order
to configure and run. It takes three
terms, separated by colons. The first term is
bin or lib. This
defines the search path the port system will look for the
dependency in. If bin is specified,
$PATH is searched for the dependency.
If lib is specified, the library path
is searched instead. The second term is a regular
expression that is used to search the search path for the
dependency. Usually the name of the library is good
enough. The port system will append
.dylib to the reg-ex so only dynamic
libraries will be matched. The third term is the name of
the port that can provide the dependency if it is not
satisfied by something already installed on the
system.patchfilespatchfiles is a list of patches to
be applied to the port (needed for the software to
compile/run or install correctly). Patches are usually
provided in a files/ directory in the
same directory as the
Portfile.Please take a look at the other chapters in this
Guide for more detailed information about these and other
options.Common MistakesDon't quote or wrap items in '{}'. Frequently people submit ports with the description or
configure arguments quoted, or wrapped in curly brackets. In
general this is not correct. Testing Portfiles: Tips and HintsDebugging and Verbose MessagesYou should use the and
switches to port to
enable debugging and verbose messages, respectively.Use a Local Portfile Repository Enable a second local source
(Portfile) repository for your
uncommitted ports. Edit
/etc/ports/sources.conf and
add:file:///User/foo/dports-dev (or
wherever your local dport tree is). Create an index file from the local source repository
root. This will also perform a simple syntax check Portfiles
contained.portindexTesting DestrootFirst run port install without root privileges, this is a
good way to check that the port installs into the destroot and
not directly into the main prefix directory, or elsewhere in
the system. This should succeed up to the point darwinports
attempts to copy the port from the destroot into the
darwinports prefix. Once you are confident the port is
correctly destrooted install the port into the darwinports
prefix using root privileges. sudo port install foo Ensure the Port installs into the destroot and does not
install anything onto the system directly, most software that
uses autoconf should behave correctly automatically as
darwinports sets DESTDIR by default. If files are directly
installed to the system they will not be registered and
packaging will fail. Test Uninstall Uninstall the port sudo port uninstall fooTry the Port on a Clean Machine Make sure the port builds, installs and uninstalls on
a "clean machine". A clean machine should have a
clean install of the OS, to avoid missing dependencies.
Using a chrooted version of the OS to install and test ports
makes this much easier, see the chroot
HOWTO for more details on how to set up the chroot. Clean the Working Directory after an Error Clean the working source directory for a port. This will
allow a clean reinstall if an error was encountered earlier in
the build process. port clean foo Where can I ask for advice?Either on the darwinports@opendarwin.org
mailing list, or on the #opendarwin channel on irc.freenode.net.
Don't be afraid to ask questions! You should also look at the
later sections of the guideand the
portfile(7) and
portstyle(7) manpages for more information.How do I submit my PortsSee the submission chapter for
all the information on how to submit a port properly.More Example PortfilesExpat PortfileNeon PortfileFor more examples, you can browse the directory tree of
DarwinPorts' dports directory and have a look
at the Portfiles of your favorite
ports.For more information about some options used in these
Portfile examples that were not covered in
this chapter, please take a look at the following chapters of this
Guide.