portfile
introduction
maintainer
Quick Start
Introduction to a Portfile
This document will provide a short guide to the basics of the darwinports Portfile. A Portfile is actually a TCL script run by the port system, despite this the Portfile Syntax is very straightforward. To begin with we are going to look at a simple example Portfile and then explain the syntax that is used.
Basic Portfile
This is the first example, Expat.
Example Portfile 1
Expat Portfile
The Portfile uses key value pairs to define how it is executed. Below is a list of some of the simple terms. Line up each of the values with tabs in a “table” type of format.
Portfile Keys 1
PortSystem
The version of darwinports that the port depends on. If a later release introduces a function that isn't in version 1.0, you can specify the version of darwinports that the Port requires. The PortSystem value is 1.0 (at the moment there is no "higher" version of darwinports.
categories
Each port must have at least one category and may have more than one. The primary category should be listed first. (The primary category is also the directory under which the port is stored).
maintainers
The email address of the maintainer (or maintainers) of the port.
name
version
name is the name of the port, usually also the name of the distribution file (distfile). In the example port the name is expat.
version
version is the version of the distribution being ported. In the example port the version is 1.95.5.
distfile
The name and version are combined with the extract_sufx (by default .tar.gz) this is used by default as the "distfile" name and used by darwinports to fetch the distribution file. If the name of the file on the server is not the same as the name-version.tar.gz you can override the default behavior by defining the distfile name.
master_sites
A list of URLs from which to fetch the distfile. The URLs must be separated by spaces and on one line (or with new lines escaped with '\').
checksums
The md5 checksum of the distfiles. If you have more than one file being fetched you should specify the checksum for each in the form:
foo md5 ....
bar md5 ....
contents
A list of all the files installed by the port. The files should be on a single line, newlines escaped with '\'. The contents list should not include the prefix into which the port will be installed (for example /opt/local/) and must not include directories that will contain things installed by other ports.
prefix
This variable is the filesystem location relative to which files are installed by the ports system. The prefix is '/opt/local' by default but Portfile authors should always refer to it by the variable name ${prefix}.
Example Portfile 2
A second example Portfile will give you an idea of how to deal with slightly more complicated ports.
Neon Portfile
Many of the components of this port are the same as those in the first example. This port is more complicated as it requires something else to be installed, needs certain environmental variables to be set prior to configuring and the configure script is being passed arguments.
Portfile Keys 2
depends_lib
This is probably the most common kind of dependency. The port depends on libraries or binaries to be installed during configuration and to run. depends_lib 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 path defined in the first term for the dependency. Usually the name of the library is a good enough. The port system will append .dylib to the regex so only dynamic libraries will be matched. The third term is the name of the port that can provide the dependency. If the dependency is not satisfied by something already installed on the system the port listed here will installed before the port.
configure.env
You may have to set environment variables for the configure script to set library paths, compiler settings or some other configuration variable.
configure.args
If you need to specify additional configure arguments you should place them on a single line. As with other settings, newlines may be escaped to break up long lines. Note the continuing lines are indented two spaces.
By default the configure script is passed --prefix=${prefix} where ${prefix} is replaced with the prefix darwinports is configured to install into.
In general you should quote variables like {prefix} in case the path has a space in it.
Include
In this Portfile there is not contents directive, the contents are included from a separate file. This is the preferred method if the contents list is more than a few items.
The contents file has precisely the same format as the contents section of the first example Portfile.
Common Mistakes
Don'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.
How to test
Enable debugging and verbose messages from the darwinports engine. Edit /etc/ports/ports.conf and set:debug yes and verbose yes .
Enable a local source repository and comment out the remote repository. Edit /etc/ports/sources.conf and set:file:///usr/dports (or wherever your copy of the dport tree is).
From the local source repository root, create an index file. This will also syntax check portfiles contained.
portindex
Sync the index
port sync
Install port
sudo port install foo
Uninstall the port
sudo port uninstall foo
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.
Make sure the contents list is correct. Ensure all the files installed are listed and directories are listed after their contents, so they are empty when the port system attempts to remove them.
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 to submit
Email your submission to darwinports@opendarwin.org mailing list. In general the Portfile should be inlined in the email, rather than as an attatchment. This allows people to view and give feedback on the Portfile more easily. If there is a large contents list and/or patchfiles these may be attatched to the email as a tarred and gzipped archive.
Where can I ask for Advice?
Either on the darwinports@opendarwin.org mailing list, or on the #opendarwin channel on irc.openprojects.net. Don't be afraid to ask questions!