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.
This is a longer description of the port. One to a few paragraphs concisely explaining what the port does is sufficient.
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.
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 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 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:
Refer to the pkg_create(1) manual page for details on the packing list.
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.
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
:
Of course, PLIST_DIRS
should be left
unset if a port installs no directories of its own.
Several ports can share a common directory. In that
case, PLIST_DIRS
should be replaced by
PLIST_DIRSTRY
so that the directory is
removed only if empty, otherwise it is silently ignored.
PLIST_DIRS
and
PLIST_DIRSTRY
are equivalent to using
@dirrm
and @dirrmtry
in pkg-plist
, as described in
Section 7.2.1, “Cleaning Up Empty Directories”.
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.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.