FreeBSD Porter's Handbook
Prev	Chapter 2 Quick Porting	Next

2.2 Writing the description files

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

2.2.1 `pkg-comment`

This is the one-line description of the port. Please do not include the package name (or version number of the software) in the comment. The comment should begin with a capital, and end without a period. Here is an example:

    A cat chasing a mouse all over the screen

2.2.2 `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). If the ported software has an official WWW homepage, you should list it here. Prefix one of the websites with WWW: so that automated tools will work correctly.

It is recommended that you sign your name at the end of this file, as in:

    This is a port of oneko, in which a cat chases a poor mouse all over
    the screen.
     :
    (etc.)
    
    WWW: http://www.oneko.org/
    
    - Satoshi
    asami@cs.berkeley.edu

2.2.3 `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 or /usr/X11R6). If you are using the MANn variables (as you should be), do not list any manpages here.

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: You should list all the files, but not the name directories, in the list. Also, if the port creates directories for itself during installation, make sure to add @dirrm lines as necessary to remove them when the port is deleted.

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.

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.

2.2 Writing the description files

2.2.1 pkg-comment

2.2.2 pkg-descr

2.2.3 pkg-plist

2.2.1 `pkg-comment`

2.2.2 `pkg-descr`

2.2.3 `pkg-plist`