第 12 章 该做什么和不该做什么

12.1. 介绍

这里是一些在移植软件时可能会遇到的常见问题。 您应按照这个列表检查自己的 port， 同样地， 您也可以帮助检查 PR 数据库 中由其它人提交的 port。 请按照在 问题报告和一般性注释 中介绍的方法提交您的看法。 帮助检查 PR 数据库中的 ports 即能够帮助我们更快地 commit 它们， 也能证明您清楚地了解如何完成这些工作。

12.2. WRKDIR (联编时使用的临时目录)

任何时候都不要在 WRKDIR 以外的位置写文件。 WRKDIR 是在 port 联编过程中唯一的一处一定可写的地方 (参见如何从 CDROM 安装 port 以了解从只读的目录中联编和安装 port 的例子)。 如果您需要改变 pkg-* 文件， 请按照 重新定义某个变量 介绍的方法， 而不是覆盖它们来实现。

12.3. WRKDIRPREFIX (用于联编的临时目录的父目录名)

一定要确保您的 port 尊重 WRKDIRPREFIX 的设置。 绝大多数 port 并不需要担心这个。 具体说来， 当引用其它 port 的 WRKDIR 时， 需要注意正确的位置应该是 WRKDIRPREFIXPORTSDIR/subdir/name/work 而不是 PORTSDIR/subdir/name/work 或 .CURDIR/../../subdir/name/work， 或别的什么。

另外， 如果您自行定义了 WRKDIR， 也要把 ${WRKDIRPREFIX}${.CURDIR} 放到前面。

12.4. 区分不同的操作系统， 以及 OS 的版本

在不同版本的 Unix 下可能需要对代码进行一些修改或增加少许编译选项， 才能够正确地编译和运行。 如果您需要根据一些条件来对代码进行修改， 请尽可能让这些修改通用， 这样， 我们就能够将这些代码移植回更早的 FreeBSD 系统， 并交叉移植到其它 BSD 系统， 例如来自 CSRG 的 4.4BSD， BSD/386， 386BSD， NetBSD 和 OpenBSD。

推荐的获得 4.3BSD/Reno (1990) 以及更新版本 BSD 代码版本号的方式， 是使用 sys/param.h 中所定义的 BSD 宏的值。 一般来说这个文件已经被引用了； 如果没有的话， 增加下述代码：

#if (defined(__unix__) || defined(unix)) && !defined(USG)
#include <sys/param.h>
#endif

到 .c 文件中合适的地方。 我们相信所有定义了这两个符号的系统中， 都提供了 sys/param.h。 如果您发现有不这样做的系统， 请通过致信 FreeBSD ports 邮件列表 让我们了解这一情况。

另一种方法是使用 GNU Autoconf 风格的方式：

#ifdef HAVE_SYS_PARAM_H
#include <sys/param.h>
#endif

采用这种方法时， 不要忘了把 -DHAVE_SYS_PARAM_H 加到 Makefile 中的 CFLAGS 里。

一旦引用了 sys/param.h， 您就可以使用：

#if (defined(BSD) && (BSD >= 199103))

来检测代码是否正在 4.3 Net2 代码基础， 或更新的系统上编译 (例如 FreeBSD 1.x， 4.3/Reno， NetBSD 0.9， 386BSD， BSD/386 1.1 以及更高版本)。

使用：

#if (defined(BSD) && (BSD >= 199306))

来检测代码是否正在 4.4 或更新的系统 (例如 FreeBSD 2.x， 4.4， NetBSD 1.0、 BSD/386 2.0 或更高版本)。

对于 4.4BSD-Lite2 代码系来说， BSD 宏的值应该是 199506。 这里只是作为信息提供， 您不应使用它来区分基于 4.4-Lite 的 FreeBSD 和基于 4.4-Lite2 的版本。 这些情况下， 您应使用 __FreeBSD__ 宏。

保守地使用：

• __FreeBSD__ 在所有版本的 FreeBSD 中皆有定义。 如果您正进行的修改 只 影响 FreeBSD， 则应使用这个宏。 类似 sys_errlist[] 之于 strerror() 这样的移植问题是伯克利代码系公用的， 而并非 FreeBSD 所专有。

• 在 FreeBSD 2.x 中， __FreeBSD__ 定义为 2。 更早版本中， 它曾经是 1。 新的版本都会在主要的版本号变化时变更它。

• 如果您需要区分 FreeBSD 1.x 系统和 FreeBSD 2.x 及更高版本的区别， 通常应使用前述的 BSD 宏来进行。 如果事实上需要一个 FreeBSD 专有的修改 (例如， 在使用 ld 时需要特殊的共享库选项)， 则可以用 __FreeBSD__ 和 #if __FreeBSD__ > 1 来检测 FreeBSD 2.x 和新系统上的变化。 如果需要更细粒度地检测 FreeBSD 2.0-RELEASE 之后版本的变化， 则可以使用：

  #if __FreeBSD__ >= 2
  #include <osreldate.h>
  #    if __FreeBSD_version >= 199504
  	 /* 适用于 2.0.5+ 版本的代码 */
  #    endif
  #endif

在已有的数百个 port 中， 只有一两个应该使用 __FreeBSD__。 早期的 port 在不适当的地方使用了它并引发问题， 并不意味着您也必定如此。

12.5. __FreeBSD_version 值

下面是在 sys/param.h __FreeBSD_version 中定义的值及其意义的列表， 这里给出以方便您查阅：

注意:

请注意， 2.2.5-RELEASE 之后有一段时间的 2.2-STABLE 会声称自己是 “2.2.5-STABLE”。 这种模式的版本号表示的是年月。 但随后， 我们决定， 从 2.2 开始， 将它改为更为简洁的 主/次 版本号的形式来命名版本。 这是因为并行地在多个分支上进行开发， 使得通过实际的发布日期来区分不同的版本变得不再现实。 如果您正在做新的 port， 应该不需要担心较早的 -CURRENT； 在此列出仅供参考。

12.6. 在 bsd.port.mk 之后写一些内容

不要在 .include <bsd.port.mk> 这行之后增加任何内容。 这通常可以通过在您的 Makefile 中间的某处引用 bsd.port.pre.mk， 并在结尾的地方引用 bsd.port.post.mk 来避免。

注意:

只能够采用 bsd.port.pre.mk/bsd.port.post.mk 或 bsd.port.mk 两种写法之一； 任何时候都不要同时使用两种写法。

bsd.port.pre.mk 只定义了很少的变量， 它们可以在 Makefile 中用于进行一些测试， 而 bsd.port.post.mk 则定义了所有其它的变量。

下面是一些由 bsd.port.pre.mk 定义的比较重要的变量 (这并不是一份完整的列表， 您可以阅读 bsd.port.mk 以获得全部变量的名字)。

注意:

如果您需要定义 USE_IMAKE， USE_X_PREFIX， 或 MASTERDIR 这些变量， 则应在引用 bsd.port.pre.mk 之前完成。

下面是一些在引用 bsd.port.pre.mk 之后可以进行的判断：

# 如果 perl5 已经在系统中提供， 则不必编译 lang/perl5
.if ${OSVERSION} > 300003
BROKEN= perl is in system
.endif

# ELF 只使用一个 shlib 版本
.if ${PORTOBJFORMAT} == "elf"
TCL_LIB_FILE=  ${TCL_LIB}.${SHLIB_MAJOR}
.else
TCL_LIB_FILE=  ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
.endif

# 软件会自动为 ELF 创建符号链接， 但 a.out 则需要另行创建
post-install:
.if ${PORTOBJFORMAT} == "aout"
       ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
.endif

您还记得应该在 BROKEN= 和 TCL_LIB_FILE= 后面使用制表符， 而不是空格， 对吧？ :-)

12.7. 在 wrapper 脚本中使用 exec 语句

如果 port 安装了用以启动其他程序的脚本， 并且运行其他程序是这些脚本的最后一项操作， 请务必使用 exec 语句来运行这些程序， 例如：

#!/bin/sh
exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"

使用 exec 语句表示执行指定的程序来取代 shell 进程。 如果省略了 exec， 则 shell 进程会一直在内存中， 从而不必要地消耗了额外的系统资源。

12.8. 理性行事

任何 Makefile 都应该简单并理性地行事。 如果您能让其中的条目更为简单和易读， 一定要这样做。 例如， 使用 make 提供的 .if 结构， 而不要使用 shell 的 if， 只要能重定义 EXTRACT* 就不要重载 do-extract， 尽量使用 GNU_CONFIGURE 而不是 CONFIGURE_ARGS += --prefix=${PREFIX}。

如果您在尝试做什么事情的时候发现不得不写大量的代码， 请回过头来复审一下 bsd.port.mk， 看看是否有您正打算做的事情的现成实现。 尽管读起来可能很费劲， 但有很多貌似很难的问题， 在 bsd.port.mk 中都给出了十分简便的解决方案。

12.9. 遵循 CC 和 CXX 设置

port 应遵循 CC 和 CXX 变量的设置。 这也就是说， port 不应使用绝对的方式来设置这个变量的值， 而罔顾已经存在的设置； 与此相反， 它应该在其值后加入需要的其它值。 这样， 就可以设置全局的联编选项， 令其影响所有的 port 联编过程了。

如果实在无法这样做， 请在 Makefile 中加入 NO_PACKAGE=ignores cflags。

下面的 Makefile 实例给出了如何遵循 CC 和 CXX 变量的设置。 注意这里用到的 ?=：

CC?= gcc

CXX?= g++

下面则是没有遵循 CC 和 CXX 的例子：

CC= gcc

CXX= g++

在 FreeBSD 系统中， CC 和 CXX 这两个变量都可以在 /etc/make.conf 中自行定义。 第一个例子只有在 /etc/make.conf 中没有定义时才对这两个变量进行定义， 从而保持了系统范围的配置。 而第二个例子则会覆盖任何现有的配置。

12.10. 遵循 CFLAGS

您的 port 应遵循 CFLAGS 变量的设置。 这也就是说， port 不应使用绝对的方式来设置这个变量的值， 而罔顾已经存在的设置； 与此相反， 它应该在其值后加入需要的其它值， 这样， 就可以设置全局的联编选项， 令其影响所有的 port 联编过程了。

如果实在无法这样做， 请在 Makefile 中加入 NO_PACKAGE=ignores cflags。

下面的 Makefile 例子， 可以帮助我们理解如何遵循 CFLAGS 的设置。 注意所用的 +=：

CFLAGS+= -Wall -Werror

下面是一个未能遵循 CFLAGS 设置的例子：

CFLAGS= -Wall -Werror

一般来说， CFLAGS 在 FreeBSD 系统中是在 /etc/make.conf 里配置的。 第一个例子在 CFLAGS 变量中增加了一些参数， 并保持了所有系统预定义的标志。 而第二个例子， 则会覆盖掉任何先前定义的参数。

您应从第三方软件的 Makefile 中去掉特殊的优化设置。 系统的 CFLAGS 给出了全系统范围内的优化设置参数。 下面是一个未经修改的 Makefile 实例：

CFLAGS= -O3 -funroll-loops -DHAVE_SOUND

如果使用系统的优化参数， 则 Makefile 中的设置应该类似下面这样：

CFLAGS+= -DHAVE_SOUND

12.11. 线程库

在 FreeBSD 上， 线程库必须通过特殊的连接器参数 -pthread 连接到可执行文件。 如果 port 一定要直接连接 -lpthread 或 -lc_r， 则应将其改为使用由 ports 框架提供的 PTHREAD_LIBS。 这个变量的值通常是 -pthread， 但在某些特定平台上的 FreeBSD 版本中， 它可能是其它值， 因此， 不要将 -pthread 硬编码到您的补丁中， 而应使用 PTHREAD_LIBS 变量。

注意:

如果设置了 PTHREAD_LIBS， 而在联编时出现 unrecognized option '-pthread' 这样的错误， 可能需要通过将 CONFIGURE_ENV 设为 LD=${CC} 来使用 gcc 作为连接器。 -pthread 这一选项并不为 ld 所直接支持。

12.12. 反馈

如果进行了一些很好的修改和补丁， 一定要把它们发回给原作者， 或维护者， 以便在下一版本的代码中包含它们。 这会让您在软件发布新版本的时候变得轻松一些。

12.13. README.html

不要包含 README.html 文件。 这个文件并非 CVS 代码库中的一部分， 它是由 make readme 命令生成的。

12.14. 使用 BROKEN、 FORBIDDEN 或 IGNORE 阻止用户安装 port

某些时候会需要阻止用户安装某个 port。 想要告诉用户某个 port 不应被安装， 有许多可以在 port 的 Makefile 中使用的 make 变量。 下列 make 的值， 将是在用户试图安装时得到的提示信息。 务请使用正确的 make 变量， 因为每一个都表达了截然不同的意义， 而且许多自动化系统， 例如 port 联编集群、 FreshPorts， 以及 portsmon， 都依赖于 Makefile 的正确性。

12.14.1. 变量

• BROKEN 专门用于表达目前无法正确编译、 安装或卸载这类问题。 如果是临时性的问题， 则可以使用它。

  如果进行了相关的配置， 则联编集群仍将尝试联编它， 以确认导致问题的深层问题是否已被解决。 (不过， 一般情况下， 联编集群并不会这样做。)

  举例来说， 当 port 发生下述情况时， 应使用 BROKEN：

  • 无法编译 (does not compile)

  • 无法正确进行配置或安装操作

  • 在 ${LOCALBASE} 以外的地方安装文件

  • 卸载时无法删除所安装的全部文件 (不过， 留下用户改过的文件可接受的， 因为可能希望这样作)

• FORBIDDEN 用于表示 ports 中包含安全漏洞， 或者可能会给安装了这个 port 的 FreeBSD 系统带来严重的安全隐患 (例如： 一个很不安全的程序， 或包含了能够被轻易攻陷的服务的软件)。 如果发现了安全漏洞， 而其作者没有发布升级版本， 则应立即把那个 port 标记为 FORBIDDEN。 理想情况下， 包含安全漏洞的 port 应被尽快升级， 以便减少包含漏洞的 FreeBSD 主机的数量 (我们希望保持良好的安全记录)， 然而， 有时在安全漏洞的披露和软件更新之间可能会有一个间隔， 此时应予以说明。 除了安全之外， 请不要以任何其它理由将 port 标记为 FORBIDDEN。

• IGNORE 用来表示 port 由于某些其它原因不应予以联编。 如果认为发生了结构性的问题， 则应使用它。 任何情况下， 联编集群都不会联编标记为 IGNORE 的 port。 以下是使用 IGNORE 的一些例子：

  • 能够编译但无法正常运行

  • 无法与运行的 FreeBSD 版本一同工作

  • 联编时需要 FreeBSD 内核的源代码， 但用户没有安装它们

  • 由于授权原因， 必须手工下载 distfile

  • 无法与的某个已安装的 port 一同工作 (例如， port 依赖于 www/apache21 而安装的则是 www/apache13)

  注意:

  如果 port 与某个已经安装的 port 冲突 (例如， 它们在同一位置安装同名但功能不同的文件)， 则应 使用 CONFLICTS 来标记它。 CONFLICTS 将自动地设置 IGNORE。

• 如果 port 只应在某些平台上标记为 IGNORE， 还有另外两个方便使用的 IGNORE 变量可供选择： ONLY_FOR_ARCHS 和 NOT_FOR_ARCHS。 例如：

  ONLY_FOR_ARCHS= i386 amd64

  NOT_FOR_ARCHS= alpha ia64 sparc64

  可以使用 ONLY_FOR_ARCHS_REASON 和 NOT_FOR_ARCHS_REASON 来配置定制的 IGNORE 消息。 此外， 还可以使用 ONLY_FOR_ARCHS_REASON_ARCH 和 NOT_FOR_ARCHS_REASON_ARCH 来分别指定与具体平台有关的信息。

• 如果 port 会下载并安装用于 i386 的预编译二进制文件， 则应设置 IA32_BINARY_PORT。 如果设置了这个变量， 则系统会检查是否已经在 /usr/lib32 目录中安装了 IA32 版本的函数库， 以及内核是否提供了 IA32 兼容支持。 如果这些依赖条件不满足， 则会自动设置 IGNORE。

12.14.2. 实现说明

这些字串不应使用引号括起来。 此外， 由于显示给用户的方式不同， 这些字串的措辞也应有所不同。 例如：

BROKEN= this port is unsupported on FreeBSD 5.x

IGNORE= is unsupported on FreeBSD 5.x

它们分别会在 make describe 时产生下面的输出：

===>  foobar-0.1 is marked as broken: this port is unsupported on FreeBSD 5.x.

===>  foobar-0.1 is unsupported on FreeBSD 5.x.

12.15. 使用 DEPRECATED 或 EXPIRATION_DATE 表示某个 port 将被删除

一定要记得 BROKEN 和 FORBIDDEN 只应作为当某个 port 无法正常工作时的临时解决方案。 永久性地坏掉了的 port 应被从 ports tree 中完全删除。

需要时还可以使用 DEPRECATED 和 EXPIRATION_DATE 来通知用户某个 port 不应被使用， 并即将被删除。 前一个变量用来表达为什么计划删除 port； 而后一个是则是一个 ISO 8601 格式的日期 (YYYY-MM-DD)。 两者都会向用户呈现。

也可以设置 DEPRECATED 而不给出 EXPIRATION_DATE (例如， 建议使用某个新版本的 port)， 但反之则没有意义。

目前还没有确切的关于需要给出多少通知的政策。 当前的实践是， 对于与安全有关的问题为一个月， 而与联编有关的问题则为两个月。 这也让有兴趣的 committer 能够有一点时间来修正问题。

12.16. 避免使用 .error 结构

在 Makefile 中给出信号， 表示由于某种外界因素 (例如， 用户指定了无效的联编选项) 而无法安装的方法是将变量 IGNORE 设为一非空值。 这个值将被格式化， 并在用户执行 make install 是给出提示。

用 .error 实现这一目的是一种常见的误用。 这样做的问题是， 许多在 ports 树上运行的自动化工具会因此而失败。 最常见的情况见于联编 /usr/ports/INDEX 的过程 (参见 第 9.1 节 “运行 make describe”)。 然而， 即使十分普通的命令， 例如 make maintainer， 在这种情况下也会失败。 这是不可接受的。

考虑有人在 make.conf 中设置了

USE_POINTYHAT=yes

的情形。 接下来的例子中， 第一个 Makefile 中的问题将导致 make index 失败， 而第二个则不会：

.if USE_POINTYHAT
.error "POINTYHAT is not supported"
.endif

.if USE_POINTYHAT
IGNORE=POINTYHAT is not supported
.endif

12.17. 对于 sysctl 的使用

除了在 target 中之外， 是不鼓励使用 sysctl 的。 这是因为计算 makevar， 例如在 make index 中所进行的那种， 都不得不运行一条命令， 这会使这一操作变得更慢。

在使用 sysctl(8) 时， 务必通过 SYSCTL 变量来进行， 因为此变量将展开成命令的完整路径， 并且用户可以根据需要另行指定。

12.18. 重新发布的 distfiles

有时， 一些软件的作者会修改业已发布的 distfile 的内容， 而并不修改文件名。 这种情况下， 您需要验证这些变动是来自软件作者的官方改动。 在过去， 曾经发生过下载服务器上的 distfile 被悄悄换成注入过恶意代码的版本， 并给用户安全造成威胁或损害的事情。

您应保留一份旧的 distfile， 并下载一份新的， 分别展开， 用 diff(1) 来对比其内容。 如果没有发现可疑的变动， 就可以更新 distinfo 了。 请务必在您的 PR 或 commit log 中对这些差异进行描述， 以便让别人了解您已经仔细对比过差异， 并确认没有问题了。

除此之外， 也可以联系软件的作者， 以确认这些修改是否是他们做的。

12.19. 杂记

需要仔细地反复检查 pkg-descr 和 pkg-plist 这两个文件。 如果您正在复审一个 port， 并认为这两个文件应该改进， 请一定要这样做。

请不要在系统中复制多份 GNU General Public License。

一定要非常小心地处理法律问题！ 不要让我们发布没有得到合法授权的软件！