第 3 章. 快速移植

目录

本节介绍如何快速创建一个新的端口。对于此快速方法不适用的应用程序，完整的“缓慢移植”过程在缓慢移植中进行了描述。

首先，获取原始的 tarball 并将其放入 DISTDIR，默认为 /usr/ports/distfiles。

以下步骤假设软件能够开箱即用地编译。换句话说，应用程序在 FreeBSD 系统上运行不需要任何更改。如果需要进行任何更改，请参考缓慢移植。

建议在进行移植之前，在/etc/make.conf中设置DEVELOPER make(1) 变量。

# echo DEVELOPER=yes >> /etc/make.conf

此设置启用“开发者模式”，该模式显示弃用警告并在调用make时激活一些进一步的质量检查。

3.1. 编写 Makefile

最小的Makefile看起来像这样

PORTNAME=	oneko
DISTVERSION=	1.1b
CATEGORIES=	games
MASTER_SITES=	ftp://ftp.rediris.es/sites/ftp.freebsd.org/pub/FreeBSD/

MAINTAINER=	[email protected]
COMMENT=	Cat chasing a mouse all over the screen
WWW=		http://www.daidouji.com/oneko/

.include <bsd.port.mk>

尝试理解它。在示例 Makefile部分中显示了一个更详细的示例。

3.2. 编写描述文件

任何端口都需要两个描述文件，无论它们是否实际打包。它们是pkg-descr 和 pkg-plist。它们的 pkg- 前缀将它们与其他文件区分开来。

3.2.1. pkg-descr

这是对端口的更详细的描述。一到几段简明扼要地解释端口的功能就足够了。

这不是手册或关于如何使用或编译端口的深入描述！从README或手册页复制内容时请谨慎。它们往往不是对端口的简洁描述，或者格式很糟糕。例如，手册页具有对齐的间距，这在使用等宽字体时看起来特别糟糕。

另一方面，pkg-descr 的内容必须比Makefile 中的COMMENT行更长。它必须更深入地解释端口的用途。

一篇写得好的pkg-descr 可以完整地描述端口，以便用户无需查阅文档或访问网站即可了解软件的功能、如何使用以及它有哪些特别好的特性。提及某些需求，例如图形工具包、重大依赖项、运行时环境或实现语言，可以帮助用户决定此端口是否适合他们。

以前作为pkg-descr文件最后一行包含的 URL 已移至Makefile。

3.2.2. pkg-plist

此文件列出了端口安装的所有文件。它也称为“打包列表”，因为包是通过打包此处列出的文件生成的。路径名相对于安装前缀（通常为/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)手册页。

建议将此文件中的所有文件名按字母顺序排序。这将使在升级端口时验证更改变得更加容易。排序应在变量扩展后进行。当包列表自动生成时，框架会正确执行此操作。

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

只有一种情况可以从端口中省略pkg-plist。如果端口仅安装少量文件，请将它们列在端口的Makefile中的PLIST_FILES中。例如，通过在Makefile中添加以下几行，我们可以在上面的oneko端口中省略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。在查找文件来源时，人们通常会尝试在端口树中的pkg-plist文件中进行 grep 搜索。在Makefile中列出PLIST_FILES中的文件使该搜索变得更加困难。

如果端口需要创建空目录，或在安装过程中在${PREFIX}之外创建目录，请参阅清理空目录以获取更多信息。

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

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

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

3.3. 创建校验和文件

只需键入make makesum。端口框架将自动生成distinfo。不要尝试手动生成文件。

3.4. 测试端口

确保端口规则完全按照预期执行，包括打包端口。以下是需要验证的重要事项

  • pkg-plist不包含端口未安装的任何内容。

  • pkg-plist包含端口安装的所有内容。

  • 可以使用install目标安装端口。这将验证安装脚本是否正常工作。

  • 可以使用deinstall目标正确卸载端口。这将验证卸载脚本是否正常工作。

  • 端口仅在fetch目标阶段才能访问网络资源。这对包构建器（例如ports-mgmt/poudriere）很重要。

  • 确保可以以普通用户（即不是以root身份）运行make package。如果失败，可能需要修补软件。另请参阅fakeroot和uidfix。

步骤：推荐的测试顺序

  1. make stage

  2. make stage-qa

  3. make package

  4. make install

  5. make deinstall

  6. make package（作为用户）

确保在任何阶段都没有显示警告。

可以使用 Ports 集合中的ports-mgmt/poudriere进行彻底的自动化测试，有关更多信息，请参阅poudriere。它维护着jails，可以在其中测试上述所有步骤，而不会影响主机系统的状态。

3.5. 使用portlint检查端口

请使用portlint查看端口是否符合我们的指南。 ports-mgmt/portlint程序是端口集合的一部分。特别是，检查Makefile是否处于正确的状态，以及包是否被正确命名。

不要盲目遵循portlint的输出。它是一个静态 lint 工具，有时会出错。

3.6. 提交新端口

在提交新端口之前，请阅读注意事项部分。

对端口满意后，剩下的唯一事情就是将其放入主要的 FreeBSD 端口树中，并让其他每个人也对此感到满意。

我们不需要work目录或pkgname.txz包，因此现在将其删除。

接下来，创建一个patch(1)文件。假设端口名为oneko，位于games类别中。

示例 1. 为新端口创建.diff

使用git add .添加所有文件，然后使用git diff查看 diff。例如

% git add .
% git diff --staged

确保包含所有必需的文件，然后将更改提交到您的本地分支，并使用git format-patch生成补丁

% git commit
% git format-patch origin/main

使用git format-patch生成的补丁将包含作者身份和电子邮件地址，使开发人员更容易应用（使用git am）并给予适当的认可。

为了使提交者更容易在其工作副本的端口树上应用补丁，请从端口树的根目录生成.diff。

使用问题提交表单提交oneko.diff。使用产品“端口和包”，组件“单个端口”，并遵循那里显示的指南。在 PR 的“描述”字段中添加程序的简短描述（可能是COMMENT的简短版本），并记住添加oneko.diff作为附件。

在问题报告摘要中提供良好的描述可以使端口提交者和分类者的工作更加轻松。新端口的预期格式为“[NEW PORT] 类别/端口名称 端口的简短描述”。使用此方案可以更容易、更快地开始提交新端口的工作。

提交端口后，请耐心等待。将新端口包含在 FreeBSD 中所需的时间可能从几天到几个月不等。可以在https://bugs.freebsd.org/bugzilla/query.cgi中搜索问题报告数据库的简单搜索表单。

要获取打开的端口 PR 列表，请在搜索表单中选择打开和端口和包，然后单击搜索。

查看新端口后，如有必要，我们将回复并将其提交到树中。提交者的姓名也将添加到其他 FreeBSD 贡献者和其他文件中。

以前，可以使用 shar(1) 文件提交新端口的补丁；随着 git(1) 的发展，这种情况不再适用。提交者不再接受 shar(1) 文件，因为它们容易出错，并且不会在该类别的 Makefile 中添加相关的条目。

最后修改时间：2024年3月9日，作者 Danilo G. Baio

首页