Part IV: Serving and System Management

15.5. Creating DarwinPorts Packages

As readily as you can create Fink packages, you also can create your own DarwinPorts packages (i.e., ports). To create a port in DarwinPorts, you must first identify a source archive and create a Portfile file in the appropriate subdirectory of the dports directory. For example, the Portfile for a game named foo would be placed in ~/darwinports/dports/games/foo, assuming that the DarwinPorts infrastructure has been installed in ~/darwinports. A Portfile is a actually a TCL script that is similar in purpose to a .info file in Fink. The remainder of this chapter is devoted to illustrating the process of creating a DarwinPorts package.

15.5.1. Creating and Publishing the Tarball

The process of creating a package in DarwinPorts begins just as it does when you create a package in Fink. That is, DarwinPorts also needs a tarball that can be downloaded with the curl utility. We'll illustrate how to create a DarwinPorts package with the same program, hellow-1.0, that we used to illustrate how to create a Fink package earlier in this chapter. As in Fink, you should begin by creating a tarball named hellow-1.0.tar.gz with the following contents, and move it to the /Users/Shared/hellow/src directory:

     hellow-1.0/     hellow-1.0/hellow.1     hellow-1.0/hellow.c     hellow-1.0/Makefile 

The curl utility can download this file with the following URL: file:///Users/Shared/hellow/srcs/hellow-1.0.tar.gz. (As noted in our Fink example earlier, you could also host your own files on a public web server or FTP server. Hosting the tarball on your local system, however, is useful for testing your port.)

15.5.2. Creating the Portfile File

Once the tarball has been placed in file:///Users/Shared/hellow/src/, you need to create a file named Portfile in ~/darwinports/dports/games/hellow. The Portfile lists the attributes of the package needed by DarwinPorts, for example, name, version, maintainer(s), where to download the package and how to install it. DarwinPorts uses this information to download, extract, and compile the source code. Information on patchfiles, special configure or compilation flags, and installation or post installation configuration instructions could be included in a Portfile. Example 15-6 shows a Portfile for the hellow port.

Example 15-6. The hellow-1.0 Portfile

 # $ID:  $ PortSystem 1.0 name            hellow version         1.0 categories      games maintainers     [e-mail] description     "hello program" long_description "Classic hello program.  Prints: Hello,\                  World." master_sites     file:///Users/Shared/hellow/src homepage         file:///Users/Shared/hellow distname         ${portname}-${portversion} platforms        darwin checksums        md5 4ca04528f976641d458f65591da7985c configure {} set instprog     "/usr/bin/install -m 755" set instman      "/usr/bin/install -m 644" destroot         {    system "${instprog} -d ${destroot}${prefix}/bin"    system "${instprog} -d ${destroot}${prefix}/man/man1"    system "${instprog} ${worksrcpath}/hellow ${destroot}${prefix}/bin"    system "${instprog} ${worksrcpath}/*.1 ${destroot}${prefix}/man/man1" } 

The Portfile file includes several items, described in the following list, which includes a few additional items that weren't needed in our simple example. See Michael A. Maibaum's DarwinPorts User Guide (http://darwinports.opendarwin.org/docs/), a sample Portfile in ~/darwinports/base/doc/exampleport and the portfile manpage for more details. (You must spell portfile in lower case to view the manpage.)

# $ID: $

All Portfiles begin with this string, which is a commented out RCS Id tag.

Portsystem 1.0

The Portsystem version declaration.

name

The package name.

categories

Used for organization of packages into categories, e.g., mail, editors, games, etc.

maintainers

Email addresses of folks maintaining the port.

description

A short description of the package.

long_description

A more detailed description of the package.

master_sites

The URL of the software's source distribution.

homepage

The URL of the software's web site.

distname

The name of the distribution, e.g., hellow-1.0.

platform

Specifies the platform on which the port is to be built.

checksums

This required command verifies the MD5 checksum.

extract.suffix

This is used if the source file does not have the default suffix .tar.gz.

distfile

The combination of name, version, and extract.suffix. The default is ${name}-${version}.tar.gz. This option can be used to override the default if the name of the source file on the server if not in the default form.

depends_lib

This is used to specify additional libraries or binaries required by the port.

patchfiles

A list of patch files needed for the package to compile or run. Patch files are placed in a files/ subdirectory of the directory, which contains the Portfile.

configure{}

The brackets are left empty if there is no autoconf configure script to run, as in this simple example. If there is a configure script, the argument -prefix=${prefix} is passed to it by DarwinPorts. After the configure{} line in the above Portfile, there are installation instructions to ensure that the program and its manpage get installed into the correct directory.

The variables instprog and instman are used to specify exactly which commands are to be used to install the binary and manpage, respectively. The destroot key is included to specify exactly what the system should do when the destroot option is used with the port command.

15.5.3. Building and Installing a Port

Once the Portfile file is ready, you can build the port. This involves a sequence of port commands, each invoked with the -v (verbose) and -d (debug) options. To begin this process, you must change to the the directory which contains the hellow-related Portfile and verify the MD5 checksum of the tarball:

     $ ch ~/darwinports/dports/games/hellow     $ port -d -v checksum 

Since no explicit port name was provided in the preceding command, DarwinPorts obtains, from any Portfile in the current directory, the information that is needed to download and verify the MD5 checksum of the source file. The source tarball file hellow-1.0.tar.gz is downloaded into /opt/local/var/db/dports/distfiles/hellow, and a work directory is created in ~/darwinports/dports/games/hellow.

Next, extract the source with the following command:

     $ port -d -v extract 

This command unpacks hellow-1.0.tar.gz, creating the ~/darwinports/dports/games/hellow/work/hellow-1.0 directory. Once the source code has been unpacked, you can build the package with the following command:

     $ port -d -v build 

If the build goes well, you can test the installation by first installing the port in the destroot directory:

     $ port -d -v destroot 

This produces a large number of warning messages, but in the end, if all goes well, both the binary hellow and the manpage hellow.1 will be installed in the ~/darwinports/dports/games/hellow/work/destroot/opt/local directory. After you've tested the binary and manpage in this destroot directory, you can install the hellow port system-wide that is, in /opt/local. To do this enter the following command:

     $ sudo port -d -v install 

This command installs the hellow port in /opt/local/var/db/dports/software/hellow/1.0_0/opt/local and activates it by creating hard links to the installed files in /opt/local. It also removes the work directory ~/darwinports/dports/games/hellow/work. You can check that hellow has been installed properly by entering the port installed command, and by trying to run hellow and viewing its manpage. Finally, you should enter the portindex command from ~/darwinport/dports to make your DarwinPorts installation completely aware of the newly installed hellow port. Once you've done this, you can uninstall hellow as you would uninstall any other port. That is, you could uninstall hellow with the following command:

     $ sudo port uninstall hellow 

This example shows only a small portion of DarwinPorts' capabilities. For more information, see the sources noted earlier, which contain detailed instructions on how to build and contribute a package to the DarwinPorts distribution.