3.2. Writing the Description Files

3.2. Writing the Description Files
Prev	Chapter 3. Quick Porting	Next

There are two description files that are required for any port, whether they actually package or not. They are pkg-descr and pkg-plist. Their pkg- prefix distinguishes them from other files.

3.2.1. `pkg-descr`

This is a longer description of the port. One to a few paragraphs concisely explaining what the port does is sufficient.

Note:

This is not a manual or an in-depth description on how to use or compile the port! Please be careful when copying from the README or manpage. Too often they are not a concise description of the port or are in an awkward format. For example, manpages have justified spacing, which looks particularly bad with monospaced fonts.

A well-written pkg-descr describes the port completely enough that users would not have to consult the documentation or visit the website to understand what the software does, how it can be useful, or what particularly nice features it has. Mentioning certain requirements like a graphical toolkit, heavy dependencies, runtime environment, or implementation languages help users decide whether this port will work for them.

Include a URL to the official WWW homepage. Prepend one of the websites (pick the most common one) with WWW: (followed by single space) so that automated tools will work correctly. If the URI is the root of the website or directory, it must be terminated with a slash.

Note:

If the listed webpage for a port is not available, try to search the Internet first to see if the official site moved, was renamed, or is hosted elsewhere.

This example shows how pkg-descr looks:

This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
 :
(etc.)

WWW: http://www.oneko.org/

3.2.2. `pkg-plist`

This file lists all the files installed by the port. It is also called the “packing list” because the package is generated by packing the files listed here. The pathnames are relative to the installation prefix (usually /usr/local).

Here is a small example:

bin/oneko
man/man1/oneko.1.gz
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm

Refer to the pkg-create(8) manual page for details on the packing list.

Note:

It is recommended to keep all the filenames in this file sorted alphabetically. It will make verifying changes when upgrading the port much easier.

Tip:

Creating a packing list manually can be a very tedious task. If the port installs a large numbers of files, creating the packing list automatically might save time.

There is only one case when pkg-plist can be omitted from a port. If the port installs just a handful of files, list them in PLIST_FILES, within the port's Makefile. For instance, we could get along without pkg-plist in the above oneko port by adding these lines to the Makefile:

PLIST_FILES=	bin/oneko \
		man/man1/oneko.1.gz \
		lib/X11/app-defaults/Oneko \
		lib/X11/oneko/cat1.xpm \
		lib/X11/oneko/cat2.xpm \
		lib/X11/oneko/mouse.xpm

Note:

Usage of PLIST_FILES should not be abused. When looking for the origin of a file, people usually try to grep through the pkg-plist files in the ports tree. Listing files in PLIST_FILES in the Makefile makes that search more difficult.

Tip:

If a port needs to create an empty directory, or creates directories outside of ${PREFIX} during installation, refer to Section 7.2.1, “Cleaning Up Empty Directories” for more information.

The price for this way of listing a port's files and directories is that the keywords described in pkg-create(8) and Section 7.6, “Expanding Package List with Keywords” cannot be used. Therefore, it is suitable only for simple ports and makes them even simpler. At the same time, it has the advantage of reducing the number of files in the ports collection. Please consider using this technique before resorting to pkg-plist.

Later we will see how pkg-plist and PLIST_FILES can be used to fulfill more sophisticated tasks.