FreeBSD Porter's Handbook
Prev | Chapter 3 Quick Porting | Next

# 3.2 Writing the Description Files

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 if you are copying from the `README` or manpage; too often they are not a concise description of the port or are in an awkward format (e.g., manpages have justified spacing, as it 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 should 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.

The following example shows how your `pkg-descr` should look:

    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`. If you are using the `MAN`n`` variables (as you should be), do not list any manpages here. If the port creates directories during installation, make sure to add `@dirrm` lines to remove them when the package is deleted.

Here is a small example:

    bin/oneko
    lib/X11/app-defaults/Oneko
    lib/X11/oneko/cat1.xpm
    lib/X11/oneko/cat2.xpm
    lib/X11/oneko/mouse.xpm
    @dirrm lib/X11/oneko

Refer to the pkg_create(1) manual page for details on the packing list.

> Note: It is recommended that you keep all the filenames in this file sorted alphabetically. It will make verifying the changes when you upgrade the port much easier.

> Note: 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, and perhaps directories, the files and directories may be listed in the variables `PLIST_FILES` and `PLIST_DIRS`, respectively, within the port's `Makefile`. For instance, we could get along without `pkg-plist` in the above `oneko` port by adding the following lines to the `Makefile`:

    PLIST_FILES=	bin/oneko \
    		lib/X11/app-defaults/Oneko \
    		lib/X11/oneko/cat1.xpm \
    		lib/X11/oneko/cat2.xpm \
    		lib/X11/oneko/mouse.xpm
    PLIST_DIRS=	lib/X11/oneko

Of course, `PLIST_DIRS` should be left unset if a port installs no directories of its own.

The price for this way of listing port's files and directories is that you cannot use command sequences described in pkg_create(1). 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 you resort to `pkg-plist`.

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

Prev | Home | Next
Quick Porting | Up | Creating the Checksum File

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.