第 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-descrpkg-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 只安装很少量的一些文件或目录的话, 这些文件和目录就可以分别列在 MakefilePLIST_FILESPLIST_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: 推荐的测试顺序

  1. make install

  2. make package

  3. make deinstall

  4. pkg_add package-name

  5. make deinstall

  6. make reinstall

  7. make package

确信在 packagedeinstall 阶段没有任何警告。 第三步以后, 检查是否所有新建的目录都被正确删除了。 在第四步以后, 试着运行一下所装的软件, 确保当它以 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, 接下来要做的是 cdoneko 所在的目录, 然后输入命令: 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: December 11, 2021 by Sergio Carlavilla Delgado