第 3 章简单的 port

This translation may be out of date. To help with the translations please access the FreeBSD translations instance.

这一章将介绍如何快速创建一个全新的 port。很多时候，这点内容是不够的，您需要阅读这份文档中更深入的内容。

首先，需要取得包含源代码的 tar包，并把它放到 DISTDIR变量所指的地方。默认的情况下，这应该是 /usr/ports/distfiles。

下面的内容假定您不需要修改软件的源代码就能在 FreeBSD 上编译通过。如果需要修改代码，就需要参考下一章的内容了。

3.1. 编写 Makefile

最简单的 Makefile 应该是这个样子的：

# New ports collection makefile for:   oneko
# Date created:        5 December 1994
# Whom:                asami
#
# $FreeBSD$
#

PORTNAME=      oneko
PORTVERSION=   1.1b
CATEGORIES=    games
MASTER_SITES=  ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/

MAINTAINER=    asami@FreeBSD.org
COMMENT=       A cat chasing a mouse all over the screen

MAN1=          oneko.1
MANCOMPRESSED= yes
USE_IMAKE=     yes

.include <bsd.port.mk>

看看您是否能够看懂。不必担心 $FreeBSD$ 那一行，当这个 port 被导入到 ports 树里的时候， CVS 会自动填写它。您可以在示范的 Makefile那章找到更多的细节。

3.2. 创建描述文件

有 2 个描述文件对于任何一个 port 来说是必须的，不论它是不是打算成为 package。它们是 pkg-descr 和 pkg-plist。这两个文件使用 pkg- 前缀以区别于其它文件。

3.2.1. pkg-descr (关于 port 的冗长描述文件)

这是 port 里一个较长的描述文件。使用一段或几段文件文字来简明的描述这个 ports 是用来做什么的。

这不是手册或者对如何深入使用/编译这个port的说明！ 要是您从 README 或者联机手册里面中复制文字的话，请务必小心；通常，它们不是对这个 port 简明扼要的描述，或者用了难以使用的格式 (比如，联机手册里有迫使两端对齐的空格)。如果要移植的软件有官方的WWW网页，您应该在这里列出来。使用 WWW: 作为前缀来表示一个网站，这样其它的自动工具就能正常工作了。

下面是一个简单的 pkg-descr 例子：

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 (port 的装箱单)

这份文件列出了 port 所要安装的所有文件。由于 package 也是据此进行打包，因此它也被称作 "装箱单(packing list)". 这个文件中，路径是相对于安装的路径的 (通常是 /usr/local 或 /usr/X11R6)。如果您使用 MANn 变量的话，请不要在这里列出任何联机手册。假如 port 在安装过程中会创建一些目录，请务必增加对应的 @dirrm 行，以便在 package 被卸载时予以自动删除。

下面是一个简单的例子：

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

参考 pkg_create(1) 的联机手册以获得更多有关装箱单的细节

建议您将这个文件里的所有的文件名按字母排序。这样，在升级这个port的时候就能够更方便地核实所做的修改。

手工创建这样一份列表可能是一件非常枯燥的事情。如果您的 port 需要安装大量的文件，自动创建装箱单会帮您省下不少时间。

只有一种情况可以不用 pkg-plist文件。如果这个 port 只安装很少量的一些文件或目录的话，这些文件和目录就可以分别列在 Makefile 的 PLIST_FILES和PLIST_DIRS 变量里。举个例子来说，我们可以在上面那个 oneko port 里面不用 pkg-plist，而把下面的这几行加到 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

当然，如果一个 port 不需要给它自己创建目录的话，就不用设置 PLIST_DIRS 变量了。

不过，如果用这种方式来列出 port 要安装的文件和目录的话，也就无法利用在 pkg_create(1) 里介绍的命令来制作 package 了。因此，这种方法只适用于那些简单的 port，使它们更为简化。同时，这种做法也有助于减少 ports collection 中的文件数量。在采用 pkg-plist 之前，请考虑一下使用这种方法。

稍后我们将看到 pkg-plist 以及 PLIST_FILES 如何处理更复杂的任务。

3.3. 创建校验和文件

只要键入 make makesum， port 便会自动创建 distinfo文件。

如果下载的文件的校验和经常变化，而您又能确保它们的来源可靠 (比如，来自于CD制造商，或每天联编生成的文档文件)，就应该在 IGNOREFILES 里面标明这些文件。这样，再运行 make makesum 的时候便不会把这些标记 IGNORE 的文件计算在内了。

3.4. 测试 port

应当确定您的 port 确实做了您希望它们做的事情，包括打包。下面是需要重点检查的一些重要的工作。

pkg-plist 中没有包括任何不想安装的文件
pkg-plist 包含了所有应该安装的文件
您的 port 能够使用 reinstall 多次安装。
您的 port 能在卸载 (deinstall) 时，自动完成清理

Procedure: 推荐的测试顺序

make install
make package
make deinstall
pkg_add package-name
make deinstall
make reinstall
make package

确信在 package 和 deinstall 阶段没有任何警告。第三步以后，检查是否所有新建的目录都被正确删除了。在第四步以后，试着运行一下所装的软件，确保当它以 package 方式安装的时候也能正常工作。

自动化这些步骤最简单的方法是通过 ports tinderbox 来进行测试。它可以维护 jails 并在其中完成全部测试工作，而不会破坏正在运行的系统的状态。请参见 ports/ports-mgmt/tinderbox 以了解更多的信息。

3.5. 用 `portlint` 来检查 port

请使用 portlint 命令来检查您的 port 是否符合我们的规范。 ports-mgmt/portlint 程序是 ports 套件的一部分。这个程序的主要功能是帮助您检查 Makefile 的样式是否符合规范，以及 package 的命名是否得体。

3.6. 提交新 port

在提交新 port 之前，应先阅读该做什么和不该做什么一节。

既然已经对所制作的 port 相当满意了，剩下的工作，便是将它放进 FreeBSD 的主 ports 树，以便让更多的人从中受益。我们并不需要您的 work 目录以及 pkgname.tgz 包，因此现在可以删除它们了。假定您的 port 的名字是 oneko，接下来要做的是 cd 到 oneko 所在的目录，然后输入命令： shar find oneko > oneko.shar

将这个 oneko.shar 文件作为附件，使用 send-pr(1) 程序提交 (请参阅 Bug Reports and General Commentary 以了解关于 send-pr(1) 的进一步详情) 将其送出。请务必将您的 bug 报告分类 (category) 为 ports 并把子分类 (class) 设置为 change-request (不要把报告表及为机密的，即 confidential！)。此外，在 PR 的描述 ("Description") 一栏中的内容应该是 port 的简要介绍 (例如 COMMENT 内容的简化版本)，而 shar 文件则应填入修正 ("Fix") 栏中。

在问题报告里面使用了一段好的描述，能使我们的工作变得更容易。习惯上，我们会使用类似： "New port: <category>/<portname> <short description of the port>" 这样的标题来说明这是新的 port。如果您也使用这样的习惯，那么我们将更容易更方便地阅读您的 PR，从而加快处理速度。

再次声明， 不要包含原始的distfile， work目录，或者您用 make package 制作的包；此外，对于新的 port 请务必使用 shar(1) 而不是 diff(1)。

在您提交的您的 port 以后请耐心等待。有时在一个 port 正式加入 FreeBSD 之前需要花费好几个月，尽管也有可能是几天。您可以查看正等待被 commit 到 FreeBSD 的 port PR。

一旦我们看过了您的报告，有必要的话我们会联系您，并把它放到 ports 树里。您的名字也会出现在 Additional FreeBSD Contributors 和其它的文件。不是很棒吗!? :-)

Last modified on: March 9, 2024 by Danilo G. Baio

Home

第 3 章 简单的 port

Table of Contents