3.2.编写描述文件

有两个描述文件是每个 Port 必需的，无论它是否实际打包。它们是 pkg-descr 和 pkg-plist。它们的 pkg- 前缀将它们与其他文件区分开来。

3.2.1. pkg-descr

这是 Port 的详细描述。简洁地用一到几段话解释该 Port 的功能即可。

注意

这不是手册，也不是如何使用或编译 Port 的详细描述！请在复制自 README 或手册页时小心。它们往往不是对 Port 的简洁描述，或者格式不合适。例如，手册页有对齐空格，这在等宽字体下看起来特别难看。

另一方面，pkg-descr 的内容必须比 Makefile 中的 COMMENT 行 更长。它必须更深入地解释该 Port 的功能。

编写得好的 pkg-descr 完全描述了 Port，使用户不必查阅文档或访问网站，就能理解该软件的功能、用途或特别的优点。提及一些要求，如图形工具包、较重的依赖关系、运行时环境或实现语言，有助于用户决定这个 Port 是否适合他们。

注意

以前在 pkg-descr 文件的最后一行包含的 URL 已经移到 Makefile 中。

3.2.2. pkg-plist

该文件列出了 Port 安装的所有文件。它也叫做“打包列表”，因为软件包是通过打包这里列出的文件生成的。路径名是相对于安装前缀（通常是 /usr/local）的。

下面是个小示例：

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

有关打包列表的详细信息，请参阅 pkg-create(8) 手册页。

注意

推荐将此文件中的所有文件名按字母顺序排列。这样在升级 Port 时验证更改会更容易。排序应在变量展开后进行。框架在 自动生成 包列表时会正确地进行排序。

技巧

手动创建打包列表可能是一个非常繁琐的任务。如果 Port 安装了大量文件，自动创建打包列表 可能会节省时间。

只有在一种情况下，pkg-plist 可以从 Port 中省略。如果 Port 仅安装少量文件，则可以在 Port 的 Makefile 中通过 PLIST_FILES 列出它们。例如，我们可以通过将以下行添加到 Makefile 中来省略上述 oneko Port 的 pkg-plist：

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

注意

不应滥用 PLIST_FILES。在寻找文件的来源时，人们通常会尝试在 Ports 树中的 pkg-plist 文件中查找。将文件列在 Makefile 中的 PLIST_FILES 会使得此类搜索更加困难。

技巧

如果 Port 需要创建一个空目录，或者在安装过程中在 ${PREFIX} 外部创建目录，请参考 清理空目录 以获取更多信息。

技巧

由于 PLIST_FILES 是一个 make(1) 变量，因此任何包含空格的条目都必须加上引号。例如，如果使用 pkg-create(8) 和 通过关键字扩展包列表 中描述的关键字，条目必须加上引号。

PLIST_FILES=	"@sample ${ETCDIR}/oneko.conf.sample"

稍后我们将看到如何使用 pkg-plist 和 PLIST_FILES 来完成 更复杂的任务。