# 3.2.编写描述文件

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

## 3.2.1. **pkg-descr**

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

> **注意**
>
> 这不是手册，也不是如何使用或编译 Port 的详细描述！*请在复制自 **README** 或手册页时小心*。它们往往不是对 Port 的简洁描述，或者格式不合适。例如，手册页有对齐空格，这在等宽字体下看起来特别难看。
>
> 另一方面，**pkg-descr** 的内容必须比 [Makefile 中的 `COMMENT` 行](https://docs.freebsd.org/en/books/porters-handbook/makefiles/#makefile-comment) 更长。它必须更深入地解释该 Port 的功能。

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

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

## 3.2.2. **pkg-plist**

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

下面是个小示例：

```sh
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)](https://man.freebsd.org/cgi/man.cgi?query=pkg-create\&sektion=8\&format=html) 手册页。

> **注意**
>
> 推荐将此文件中的所有文件名按字母顺序排列。这样在升级 Port 时验证更改会更容易。排序应在变量展开后进行。框架在 [自动生成](https://docs.freebsd.org/en/books/porters-handbook/plist/#plist-autoplist) 包列表时会正确地进行排序。

> **技巧**
>
> 手动创建打包列表可能是一个非常繁琐的任务。如果 Port 安装了大量文件，[自动创建打包列表](https://docs.freebsd.org/en/books/porters-handbook/plist/#plist-autoplist) 可能会节省时间。

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

```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
```

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

> **技巧**
>
> 如果 Port 需要创建一个空目录，或者在安装过程中在 **${PREFIX}** 外部创建目录，请参考 [清理空目录](https://docs.freebsd.org/en/books/porters-handbook/plist/#plist-dir-cleaning) 以获取更多信息。

> **技巧**
>
> 由于 `PLIST_FILES` 是一个 [make(1)](https://man.freebsd.org/cgi/man.cgi?query=make\&sektion=1\&format=html) 变量，因此任何包含空格的条目都必须加上引号。例如，如果使用 [pkg-create(8)](https://man.freebsd.org/cgi/man.cgi?query=pkg-create\&sektion=8\&format=html) 和 [通过关键字扩展包列表](https://docs.freebsd.org/en/books/porters-handbook/plist/#plist-keywords) 中描述的关键字，条目必须加上引号。
>
> ```makefile
> PLIST_FILES=	"@sample ${ETCDIR}/oneko.conf.sample"
> ```

稍后我们将看到如何使用 **pkg-plist** 和 `PLIST_FILES` 来完成 [更复杂的任务](https://docs.freebsd.org/en/books/porters-handbook/plist/#plist)。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://porters-handbook.bsdcn.org/di-3-zhang-jian-dan-de-port/3.2.-bian-xie-miao-shu-wen-jian.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.