| |
 |
|
 |
 |
|
 |
FreeBSD Porter 手册
|
|
|
The FreeBSD Documentation Project
FreeBSD 中文计划
版权 © 2000, 2001, 2002, 2003, 2004, 2005 The FreeBSD Documentation Project
版权 © 2005 FreeBSD 中文计划
FreeBSD是FreeBSD基金会的注册商标。
UNIX是Open Group在美国和其它国家的注册商标。
Sun, Sun Microsystems, SunOS, Solaris, and Java是Sun Microsystems, Inc. 在美国和其它国家的商标或注册商标。
Apple and QuickTime是Apple Computer, Inc.的商标， 在美国和其它国家注册。
Macromedia and Flash是Macromedia, Inc. 在美国和/或其它国家的商标或注册商标。
Microsoft, Windows, and Windows Media是Microsoft Corporation 在美国和/或其它国家的商标或注册商标。
PartitionMagic是PowerQuest Corporation在美国和/或其它国家的注册商标。
许多制造商和经销商使用一些称为商标的图案或文字设计来彰显自己的产品。 本文档中出现的，为 FreeBSD Project 所知晓的商标，后面将以 '™' 或 '®' 符号来标注。
重要: 本文中许可证的非官方中文翻译仅供参考，不作为判定任何责任的依据。如与英文原文有出入，则以英文原文为准。
在满足下列许可条件的前提下， 允许再分发或以源代码 (SGML DocBook) 或 “编译” (SGML, HTML, PDF, PostScript, RTF 等) 的经过修改或未修改的形式：
-
再分发源代码 (SGML DocBook) 必须不加修改的保留上述版权告示、本条件清单和下述弃权书作为该文件的最先若干行。
-
再分发编译的形式 (转换为其它DTD、 PDF、 PostScript、 RTF 或其它形式)，必须将上述版权告示、本条件清单和下述弃权书复制到与分发品一同提供的文件，以及其它材料中。
重要: 本文档由 FREEBSD DOCUMENTATION PROJECT “按现状条件” 提供，并在此明示不提供任何明示或暗示的保障， 包括但不限于对商业适销性、对特定目的的适用性的暗示保障。 任何情况下， FREEBSD DOCUMENTATION PROJECT 均不对任何直接、 间接、 偶然、 特殊、 惩罚性的， 或必然的损失 (包括但不限于替代商品或服务的采购、 使用、 数据或利益的损失或营业中断) 负责，无论是如何导致的并以任何有责任逻辑的， 无论是否是在本文档使用以外以任何方式产生的契约、严格责任或是民事侵权行为(包括疏忽或其它)中的， 即使已被告知发生该损失的可能性。
Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.
-
Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
重要: THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
第1章 介绍
几乎每个人都是通过 FreeBSD Ports Collection 在 FreeBSD 上面装应用程序 (“ports”)的。 就像FreeBSD的其它部分一样， 它主要来自于志愿者的努力。所以在阅读这份文档的时候请务必记住这些。
在 FreeBSD 的世界里， 任何人都能提交新的 port， 或志愿地维护一个已有的 port，如果那个 port 没人维护的话 ── 不需要任何特殊的权限来做这件事情。
第2章 自行制作 port
那么， 您有兴趣创建自己的 port 或升级现有的 port？ 太好了。
下面的内容将会提供一些创建FreeBSD port的指导。 如果想升级一个现有的 port，那么您应该在看完这些内容并阅读 第 10 章。
因为这份文档不是十分详细， 您还应该再参考一下 /usr/ports/Mk/bsd.port.mk， 所有 port 的 Makefile 文件都会包含它。即使不是每天都去摆弄 Makefile， 您也会从那个文件里面获得很多知识， 里面的注释非常详细。还有要补充一下，如果您有其它的问题， 可以给FreeBSD ports 邮件列表 这个 mailing list 发信。
注意: 在这份文档里提到的大部分的变量 (VAR) 是不能修改的。 大多 (但不是全部) 都在 /usr/ports/Mk/bsd.port.mk 的开始部分进行了介绍；其它一些也应该可以在那里找到。 注意这些文件使用了非标准的制表符： Emacs 和 Vim 应该能在打开文件的时候自动识别它， 而 vi(1) 和 ex(1) 则需要在打开文件的时候通过 :set tabstop=4 来修正默认的设置。
第3章 简单的 port
这一章主要介绍如何快速创建一个简单的 port。 很多时候， 这点内容是不够的，您需要阅读这份文档中更深入的内容。
首先， 需要取得包含源代码的 tar包， 并把它放到 DISTDIR变量所指的地方。 默认的情况下， 这应该是 /usr/ports/distfiles。
注意: 下面的内容假定您不需要修改软件的源代码就能在 FreeBSD 上编译通过。如果需要修改代码， 就需要参考下一章的内容了。
最简单的 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那章找到更多的细节。
有 2 个描述文件对于任何一个 port 来说是必须的， 不论它是不是打算成为 package。它们是 pkg-descr 和 pkg-plist。这两个文件使用 pkg- 前缀以区别于其它文件。
这是 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/
这份文件列出了 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 如何处理 更复杂的任务。
只要键入 make makesum， port 便会自动创建 distinfo文件。
如果下载的文件的校验和经常变化， 而您又能确保它们的来源可靠 (比如，来自于CD制造商， 或每天构建生成的文档文件)， 就应该在 IGNOREFILES 里面标明这些文件。 这样， 再运行 make makesum 的时候便不会把这些标记 IGNORE 的文件计算在内了。
应当确定您的 port 确实做了您希望它们做的事情，包括打包。下面是需要重点检查的一些重要的工作。
推荐的测试顺序
-
make install
-
make package
-
make deinstall
-
pkg_add package-name
-
make deinstall
-
make reinstall
-
make package
确信在 package 和 deinstall 阶段没有任何警告。 第三步以后，检查是否所有新建的目录都被正确删除了。 在第四步以后， 试着运行一下所装的软件， 确保当它以 package 方式安装的时候也能正常工作。
首先， 确信您已经阅读了 该做什么和不该做什么 一节。
既然已经对所制作的 port 相当满意了， 剩下的工作， 便是将它放进 FreeBSD 的主 ports 树， 以便让更多的人从中受益。 我们并不需要您的 work 目录以及 pkgname.tgz 包， 因此现在可以删除它们了。 接下来， 只要把 shar `find port_dir` 的输出写到一份 bug 报告中， 并用 send-pr(1) 程序 (参见 Bug Reports and General Commentary 以了解关于 send-pr(1) 的进一步详情) 将其送出。 请务必将您的 bug 报告分类 (category) 为 ports 并把子分类 (class) 设置为 change-request (不要把报告表及为机密的， 即 confidential！)。 此外， 在 PR 的描述 (“Description”) 一栏中，应该填写您所移植的应用程序的简单介绍， 而 shar 则应放到修正 (“Fix”) 栏中。
注意: 在问题报告里面使用了一段好的描述， 能使我们的工作变得更容易。我们更倾向于这样的描述： 用 “New port: <category>/<portname> <short description of the port>” 来说明这是一个新的 port， 而用 “Update port: <category>/<portname> <short description of the update>” 来说明这是对一个已有的 port 的升级。 如果您坚持使用这样的方案，那么我们将更容易更方便地阅读您的 PR。
再次声明， 不要包含原始的distfile， work目录， 或者您用 make package 制作的包。
在您提交的您的 port 以后请耐心等待。 有时在一个 port 正式加入 FreeBSD 之前需要花费好几个月， 尽管也有可能是几天。 您可以查看 正等待被 commit 到 FreeBSD 的 port。
一旦我们看过了您的报告， 有必要的话我们会联系您， 并把它放到 ports 树里。您的名字也会出现在 Additional FreeBSD Contributors 和其它的文件。 不是很棒吗!? :-)
第4章 复杂的 Porting
好了， 也许工作没那么简单， port 需要做些修改才能够在 FreeBSD 上跑起来。在这一章里， 我们将会一步步举例来介绍应该如何修改来使您的 port 能在 FreeBSD 上面运行。
首先， 这一系列的动作是由用户在您的 port 目录里敲入 make 后发生的。 您也许会发现在另外的一个窗口里阅读一下 bsd.port.mk 将会有助于您的理解。
要是您不是非常明白 bsd.port.mk 是做什么的话，也不用太担心， 很多人都不知道的... :->
-
fetch 会首先被执行。 fetch 将检查在本地的 DISTDIR 目录里是否存在 tar 包。 如果 fetch 没有找到就会查找 Makefile 中定义的 MASTER_SITES URL， 还有我们的主 FTP 站点 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/，在那里我们备份了所有被认可的 distfile。 假设那个 MASTER_SITES 站点是直接连在 Internet 上的， 就会试着用 FETCH 指定的程序取回 distfile。 如果成功的话， 文件会被保存在DISTDIR 所指定的目录以备稍后使用。
-
接下来会执行 extract。 它会在 DISTDIR 中寻找您的 tar 包 (通常是用 gzip 压缩的 tar 包)，然后解压缩到由 WRKDIR 所指定的临时目录里 (默认为work目录)。
-
下一步是执行 patch。 首先任何在 PATCHFILES 中定义的补丁都会被打上。 然后， 在由 PATCHDIR 指定的目录 (默认为 files目录) 中发现的patch-*，它们将会以文件名的字母顺序被先后打上。
-
configure会被执行。 这一步骤可能会有以下几种情形。
-
如果存在 scripts/configure， 就会执行它
-
如果定义了 HAS_CONFIGURE 或者 GNU_CONFIGURE， 就会执行 WRKSRC/configure。
-
如果定义了USE_IMAGE， 就会执行 XMKMF (默认为: xmkmf -a)。
-
build会被执行。 这一步将会进入ports的工作目录 (WRKSRC) 然后进行编译。如果定义了USE_GMAKE，就会使用 GNU make， 反之， 则会使用系统默认的 make。
以上都是系统默认的步骤。 您也可以定义 pre-something 或者 post-something， 或者把以此命名的脚本放到 scripts 目录， 它们会在默认的动作之前或之后被执行。
举个例子， 如果您在您的 Makefile 里定义了post-extract， 并在 script 目录里放了一个 pre-build 脚本， 那么在 tar 包解开之后 post-extract 将被调用， pre-build 脚本会在默认的编译之前被执行。 我们推荐您在 Makefile 定义所有的动作， 如果不是十分复杂的话， 这样， 别人能更容易明白您的 port 需要执行哪些非默认的动作。
默认的行为都是由 bsd.port.mk 定义的 do-something 来表示的。例如， port 中用来解压缩的命令是由 do-extract 来定义的。如果您对默认的设置不满意， 可以通过在 Makefile 重新定义 do-someting 来做些改变。
注意: “主” 动作 (例如 extract、 configure， 等等) 仅仅是用来确定所有相应的阶段都完成了，以及调用真实的动作或脚本， 它们不应被修改。 如果您想要修改解压缩这个动作， 可以修改 do-extract， 但永远都不要改变 extract 的操作！
我们已经介绍了在用户敲入 make 之后会发生哪些事情了。接下来我们将进行进一步的学习， 来看一看如何创建一个理想的 port。
获取源代码的 tar 包 (通常是 foo.tar.gz 或者 foo.tar.Z) 并把它们放进 DISTDIR。 最好使用 主流 的版本。
您需要设置变量 MASTER_SITES 来指向原始 tar 包的获取位置。您可以在 bsd.sites.mk 里找到一些速度较快的主流站点。请使用这些站点 ── 和相关的定义 ── 如果可能的话，应尽量避免在同一个源代码树里出现大量重复的信息。 这些站点会随着时间而变化，如果每个人都随意加入的话会使维护变得非常困难。
如果您找不到一个有很好网络连接的 FTP/HTTP 站点， 或者它们使用了非标准的格式，您也许就会想在您自己的 FTP 或 HTTP 服务器上放上一份副本。
如果您找不到可靠的地方放置 distfiles， 我们也可以提供给您一些空间来保存它。我们自己的 ftp.FreeBSD.org； 然而这只是一个折衷的办法。 distfile 必须放进某人在 freefall 上的 ~/public_distfiles/ 目录中。 可以要求帮助您 commit port 的人来放这个 distfile， 而这个人也需要把 MASTER_SITES、 MASTER_SITE_LOCAL 以及 MASTER_SITE_SUBDIR 的设置， 改为在 freefall 上的用户名。
如果您的 port 的 distfile 一直在变化， 而作者拒绝改变其版本号， 您可以考虑把 distfiles 放在自己的主页， 并在 MASTER_SITES 里把原作者的列为首选位置。 如果可能， 试着与 port 的作者沟通一下让他不要这么做，这将有助于建立对源代码的控制。 在您的主页上放置您自己的 distfile 会避免用户得到 “checksum mismatch” 的错误， 而且能减轻我们 FTP 站点维护人员的工作量。 如果您的port只有一个主站点的话，我们建议您在自己的网站上做一份备份， 并他列为 MASTER_SITES的第2项。
如果您的 port 需要来自网络上的一些补丁， 请把它们放到 DISTDIR里。 不用担心它们跟源代码不是来自同一站点。 我们有办法处理 (参阅下面的 补丁文件)。
解开 tar 包， 对源代码做出合理的修改使得这个 port 能在最新版本的 FreeBSD 上面运行。 一定要 仔细记录 您所做的每处改动， 包括删除、添加、修改的文件等等， 这些修改以后会在您的 port 中以脚本或补丁的方式出现， 并且能通过运行它们来自动完成您对 port 的改动要求。
如果您的 port 要求用与用户交互/配置来完成编译或安装的话， 您可以看一下 Larry Wall 的经典的 Configure 脚本， 适当地模仿一下。 Port collection 的目的， 就是使每个 port 占用最少的空间， 并做到软件的 “即插即用”。
注意: 除非明确地声明， 否则您提交给 FreeBSD ports collection 的补丁，脚本和其它的文件都将被假定以标准的 BSD 版权发布。
在您制作 port 的过程中， 文件的添加或修改都可以用 diff(1) 做成补丁，使得今后的能够使用 patch(1) 在安装过程中自动对 port 做出相应的修改。 每一个您想要打的补丁应该以 patch-* 这样形式的文件名保存， * 表示将要被打补丁的文件名， 例如 patch-Imakefile 或 patch-src-config.h 这样。 这些文件应该被放在 PATCHDIR 里，这样这些补丁都会被自动打上。 所有的补丁必须相对于 WRKSRC 的 (port 会把 tarball 解压缩在那里， 并完成余下的其它动作)。 为了使修改和升级变得更容易，应避免使用多个 patch 去修改同一个文件 (比如， patch-file 和 patch-file2 都修改 WRKSRC/foobar.c 就应被避免)。
只有 [-+._a-zA-Z0-9] 这些字符，可以出现在补丁的文件名中， 请务必不要使用除这些字符以外的其它字符。 不要把您的补丁命名成 patch-aa 或 patch-ab 等这样的名字，最好能在补丁名中提到路径和文件名。
不要把 RCS 字符串放进补丁。 我们把文件放进 ports 树的时候， CVS 会损坏它们，当我们再 check out 出来的时候， 它们就会和原来的不一样， 从而导致打补丁失败。 RCS 字符串是由美元符号 ($) 围绕的， 通常由 $Id 或 $RCS 开头。
使用 diff(1) 的递归选项(-r) 很好， 但是请检查一下最后输出的 patch，确保没有任何的垃圾信息。 特别地， 有 2 种文件不需要 diff， 并且应该删除： 一种是 Makefile， 当您的port使用了Imake， 或者 GNU configure 等等的话。 如果您不得不编辑configure.in 以使 autoconf 去生成 configure， 不要使用 configure 来做 diff (这常常会有好几千行长!)； 请定义 USE_AUTOCONF_VER=213 并对应 configure.in 来制作 diff。
往往在移植某个软件的时候会遇到这样一种情况， 特别是这个软件是在 Windows® 上开发的时候，大多数的源代码都需要进行CR/LF的转换。 这也许会给以后打补丁， 编译警告、 脚本执行造成问题 ( /bin/sh^M not found) 等等。您能加入以下这行代码来快速地把那些文件从 CR/LF 转换到 LF： USE_REINPLACE= yes
post-extract:
@${FIND} -E ${WRKDIR} -type f -iregex ".*\.(c|cpp|h|txt)" -print0 | \
${XARGS} -0 ${REINPLACE_CMD} -e 's/[[:cntrl:]]*$$//'
当然， 如果您想要处理所有文件的话， 就可以省略上面的 -iregex 选项。请注意这段代码会从被处理文件的每一行里面剔除所有的控制字符。 (但不包括 \n)。
假如需要删除文件， 您可以在 post-extract 里面做这件事， 而不是在把它作为一个补丁。 一旦您对您所做修改的感觉比较满意，那么请把diff输出分成一个补丁对应一个源文件。
把任何附加的配置命令加进您的 configure 脚本并把它保存到 scripts 子目录。 如前面提到的那样， 您也能在 Makefile 和/或 使用 pre-configure 或 post-configure 的脚本来做同样的事情。
如果您的 port 要求用户的输入以便配置编译、 或安装配置过程， 就必须在 Makefile 里设置 IS_INTERACTIVE 变量。如果用户设置了 BATCH 的话， 这将让用户能跳过您的 port 来完成 “通宵编译” (如果用户设置了 INTERACTIVE的话， 那么 只有 那些要求互动的 port 才会被编译) 这将给那些不停编译 ports 的机器省下很多时间。
通常我们还建议， 如果对于那些问题能有合理的缺省答案的话， 应检查一下 PACKAGE_BUILDING 变量， 并根据其设置决定是否执行关闭交互脚本。这将允许我们为 CDROM 和 FTP 来编译 package。
第5章 配置 Makefile
配置 Makefile 是相当简单的，我们在此建议您在开始之前看一下现有的例子。 在这份手册里也有一个 Makefile例子， 照着里面变量的顺序来写能使得您的 port 更容易地被其它人看懂。
现在， 当您开始编写您新的Makefile 的时候，可以依次思考一下以下的问题：
放在 DISTDIR 中的是不是标准的用 gzip 压缩的 tar 包， 例如 foozolix-1.2.tar.gz？ 如果是， 可以先略过这一节。 如果不是，您应当看看是不是要覆盖这些变量： DISTVERSION、 DISTNAME、 EXTRACT_CMD、 EXTRACT_BEFORE_ARGS、 EXTRACT_AFTER_ARGS、 EXTRACT_SUFX， DISTFILES，取决于您 port 的 distfile 格式有多么怪异。 (最常见的一个例子便是 EXTRACT_SUFX=.tar.Z， 一般这是因为 tar 包是用 compress 而不是 gzip 压缩的时候。)
最糟的情况是， 您需要自己编写 do-extract 来覆盖默认的定义， 尽管这不常见， 但如果遇到了， 还是需要这么做。
Makefile 的第一部分便是 port 的名字、 版本号， 以及它所属的分类。
您应该把 PORTNAME 设置为您 port 的名字， PORTVERSION 则是 port 的版本号。
PORTERVISION 变量是一个单调递增的值， 如果不为 0，就会被加到包名的后面， 当 PORTVERSION 增加 的时候应被置 0 (也就是当官方有新版本发布的时候)。 PORTREVISION 会被自动化工具 (比如 pkg_version(1)) 用来检测是否存在可用的新版本。
每当 port 发生变化并对生成的 package 的内容或结构有显著影响时， 都应增加 PORTREVISION 值。
下面是一些应当修改 PORTREVISION 的情况：
-
有新的补丁用来修正安全漏洞、 错误， 或给 port 添加了新的功能。
-
修改了 Makefile 里编译时开启或禁用的选项。
-
修改了要安装文件的列表或安装时的行为 (例如， 修改了一个用来给 package 初始化数据的脚本， 如 ssh host keys)。
-
一个port依赖的共享库版本改变 (在这种情况下， 当安装了新版本的共享库，后再去安装较早的软件就会出错， 因为它们要依赖老的 libfoo.x 而不是libfoo.(x+1))。
-
原作者修改了 port distfile， 并且 distfile 的新老版本之间用 diff -ru 只能发现一些细微的变化， 这时我们只需要对 distinfo 做相应的修正， 而不需要修改 PORTVERSION。
不需要修改 PORTREVISION 的例子：
-
port 结构风格的改变， 但对于打成的包没有功能的上的变化。
-
MASTER_SITES 发生变化， 或进行了对 port 功能的修改，但不致影响最后打成的包。
-
对 distfiles 诸如修正拼写错误之类的补丁， 对用户而言没有升级上的麻烦。
-
对一个原本编译失败的包的修改， 使其可编译， 而没有加入新功能。 因为 PORTREVISION 表示包的内容发生了变化， 如果先前没有可编译的包，也就不需要修改 PORTREVISION 来表示变化。
一个修改并提交 port 的原则是： 使得别人能从中受益 (改进、 修改已有错误， 或使新的 package 能够运行)， 您还要权衡一下这是否应让那些经常更新 ports 树的人升级， 如果回答是 “是” 的话， PORTREVISION 就应该修改了。
有时软件商或 FreeBSD 的 porter 会使用比旧版的版本号小的数字做为新版本号的情况。举例来说， 从 foo-20000801 到 foo-1.0 (从形式上来说这是不对的， 因为 20000801 在数值上比1大很多)。
在这种情况下， PORTEPOCH 应当增加。 如果 PORTEPOCH 非 0， 就应当加到包名字的后面。 PORTEPOCH 永远不能被减少或清零， 因为那样会导致与前一时期的 package 比较版本时产生不正确的结果。 (就是说， 那个 package 就不会被检测到已经过时了。) 新的版本号 (比如前面在前面那个例子中的 1.0,1) 在数值上比前一个版本 (20000801) 小， 但多数自动化的工具会认为 ,1 后缀意味着比前一个包的后缀 ,0 大。
错误的去除或重置 PORTEPOCH 会导致很多不幸发生；如果您还不明白前面的讨论， 请多阅读几次直至明白为止， 或到邮件列表上来提问。
大多数 port 都不会用到 PORTEPOCH，并且如果某个软件的下一个版本改变了版本号结构的话， 用巧妙的方法来设定 PORTVERSION 也能避免使用 PORTEPOCH。 然而， FreeBSD porter 也需要注意， 当有新版本的软件发布， 但并非正式版本时 ── 比如 “snapshot” 版本， 原作者可能会使用当时的日期来命名， 这在新的 “官方” 版本发布的时候，就很容易引起前面提到的问题。
举个例子， 如果 snapshot 版本的发布日期是 20000917， 这个软件的上一个版本是1.2，那么这个版本的 PORTVERSIN 应该设为 1.2.20000917 或类似的样子，而不是20000917， 这样在 1.3 发布以后， 新版本就可以在数值上大于旧的版本了。
gtkmumble port，版本号 0.10，被提交到 ports collection: PORTNAME= gtkmumble
PORTVERSION= 0.10
PKGNAME 变成 gtkmumble-0.10。
然后有人发现了一个安全漏洞， 需要用一个FreeBSD的补丁。 PORTREVISION 就要相应的增加。 PORTNAME= gtkmumble
PORTVERSION= 0.10
PORTREVISION= 1
PKGNAME变成了 gtkmumble-0.10_1
软件的作者发布了新的版本， 版本为 0.2 (作者本来的意思是，用 0.10 表示 0.1.0，“而不是指 0.9 之后的那个版本” - 但是现在太迟了)。 因为现在的次版本号 2 在数值上比上一个版本 10 小， PORTEPOCH 必须增加， 以使新的 package 被认为是 “更新的”。 由于那是作者发布的一个新版本， 因此 PORTREVISION 应被置0 (或者从 Makefile 里面删除它)。 PORTNAME= gtkmumble
PORTVERSION= 0.2
PORTEPOCH= 1
PKGNAME 变成了 gtkmumble-0.2,1
下一个版本将会是 0.3。 由于 PORTEPOCH 从不减少，那么就无须改动： PORTNAME= gtkmumble
PORTVERSION= 0.3
PORTEPOCH= 1
PKGNAME 变成 gtkmumble-0.3,1
注意: 如果在这次升级中 PORTEPOCH 被置为了0， 那么在装了 gtkmumble-0.10_1 包的机器上就无法检测到 gtkmumble-0.3 包的更新， 因为 3 在数值上比 10 小。 记住， 这是 PORTEPOCH 最重要的地方。
2 个可选的变量， PKGNAMEPREFIX 和 PKGNAMESUFFIX 可以和 PORTNAME 还有 PORTVERSION 配合使用， 形成像这样的 PKGNAME： ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}。请确定符合我们的 包命名规则。 当然， 不 允许在 PORTVERSION 中使用连字符 (-)。 如果包名有 language- 或 -compiled.specifics 部分 (见下文)， 请分别用 PKGNAMEPREFIX 和 PKGNAMESUFFIX，不要直接加到 PORTNAME 中。
以下是您在命名您的包时应当遵守的规则。 这将使得我们放包的目录更利于浏览，因为我们已经有数以万计的包了， 如果用户觉得查看包名很困难的话， 他们会很快走开的。
一个包的名字应该看起来像这样： [language[_region]]-name[[-]compiled.specifics]-version.numbers。
要像这样来定义包的名字： ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}。确保所有的变量符合上面的格式。
-
FreeBSD 会尽力去支持用户当地的语言。 如果这个 port 是某种语言专用的， 那么 language- 部分应该是 由 ISO-639 定义的自然语言的 2 个字母缩写。 比如， ja是表示日本， ru 是表示俄罗斯， vi 表示越南， zh 表示中国， ko 表示韩国， de 表示德国。
如果是针对某种语言的某一地区的话， 再要加上2个字母的国家代码。 例如， en_US 表示美国英语， fr_CH 表示瑞士法语。
language- 部分应该在 PKGNAMEPREFIX 变量里设置。
-
name 部分的首字母应该 小写。 (余下的部分能包含大写字母，所以当您 要转换一个包含大写字母软件的名字时， 您需要 自己做出判断。) 对于perl 5 模块的命名， 有个传统的规则是， 在前面 加上 p5- 并把两个冒号的部分改为连字号， 如： Data::Dumper 模块变成 p5-Data-Dumper。如果软件的名字里还有数字、 连字号、 下划线， 您也可以把这些包括进来 (例如 kinput2)。
-
如果 port 可以使用不同的 硬编码默认配置 进行构建 (通常是一系列 port 的一部分目录名)， 则 -compiled.specifics 部分就应该明示编译进去的默认值 (此处连字号是可选的)。 通常的用例包括纸型和不同的字体尺寸。
-compiled.specifics 部分应该通过 PKGNAMESUFFIX 变量来设置。
-
版本号应该紧随在连字号 (-) 后面并由数字和字母组成。特别指出， 另外的连字号是不允许出现在版本号里的。 唯一例外的是字符串 pl (表示 “patchlevel”)， 只能 用在软件没有主版本号和次版本号的情况下。如果软件的版本号里出现了像 “alpha”， “beta”， “rc”， “pre”，取第一个字母把它放在小数点的后面。 如果在版本号里一直出现那些名字，那么在数字和字母之间不应有多余的小数点。
这个方法是为了更容易得凭版本号来排序 port。 特别注意的是，确保版本号之间的每部分都由小数点来分隔， 如果日期也是版本号的一部分， 就用这样的格式， yyyy.mm.dd 或者 dd.mm.yyyy 这样的格式， 而非 yy.mm.dd，因为后者不适合表示千年的格式。
这里是一些真实的例子， 我们藉此说明如何把软件作者对软件的命名，转换为适合我们包的命名方式：
如果在原始的代码里没有版本号， 或者原作者并不打算开发另外的版本， 就应把版本号设成 1.0 (就像前面 piewm 的例子那样)。否则， 要求原始的作者加上版本号或使用日期 (yyyy.mm.dd) 来作为版本号。
在包制作完成之后， 它会被放在 /usr/ports/packages/All，并建立一系列来自 /usr/ports/packages 下子目录的符号连接。这些子目录的名称是由 CATEGORIES 指定的。 这将方便于那些用户在 FTP 站点或 CDROM 的一大堆包里面寻找自己想要的包。 请查看一下 目前的分类表， 并找出一个适合您 port 的分类。
此列表也会决定您的 port 在 port 目录中的位置。 如果您在这里设定了 1 个以上的分类，则认为您 port 文件应放到以第一个分类命名的子目录中。 请参阅 后面 关于如何选择正确分类的更多讨论。
这是目前 port 中的分类。 那些用星号 (*) 标记的是 虚拟分类 ── 它们在ports树里没有相应的子目录， 因而只用来做为次要的分类， 用以方便搜索。
注意: 对于非虚拟的分类来说， 您会看到在相对应子目录中的 Makefile 里有写在 COMMENT 里的单行描述。
由于不少分类是重复的， 您通常在用哪个分类作为您 port 的主分类上做出选择。下面有几条规则能帮您解决这个问题。 这是一个带优先级的表， 按优先级降序罗列：
-
第一个分类必须是个物理的分类 (参阅 前面)。这对于制作包是必要的。 虚拟分类和物理分类可能在包制作完成后混合在一起。
-
对于特定语言的分类通常放在第一位。 例如， 如果您的 port 会安装一些 X11 的日文字体，那么 CATEGORIES那行 就应该是 japanese x11-fonts。
-
有特定意义的分类应当被列在无特定意义的前面。 例如， HTML 编辑器应该是这样的 www editors， 而不是其它的什么。 同样地， 您不应该列出 net， 如果 port 属于 irc、 mail、 mbone、 news、 security， 或是 www， 因为 net 可以表示它们的超集。
-
只有当主要的分类是一门自然语言的时候， x11 能被做为第二分类。 需要特别指出的是， 您不应把 X 的应用程序也归类为 x11。
-
Emacs 模式应当于相应的应用程序放在同一个分类里， 而不是 editors 分类。 举例来说， 一个用于编辑某种编程语言源代码的 Emacs 模式应该被归为 lang 一类。
-
misc 分类的 port 不能有其它非虚拟的分类。 如果您在您的 CATEGORIES 里设了 misc 和另外的分类，那意味着可以安全地删除 misc 并把 port 放到其它的子目录中了！
-
如果您的 port 确实不属于现有的分类， 才把它放到 misc。
如果您不能确定使用哪个分类， 请在您提交的 send-pr(1) 里加上一行注释， 这样我们就能在导入进 port 树之前讨论一下。 如果您是 committer，发一份备忘到 FreeBSD ports 邮件列表 先讨论一下。 很多情况是新的 port 被加到错误的分类里， 然后又立即被移走。这会造成源代码库不必要和不良的膨胀。
由于 Ports Collection 在持续增长， 已经引入了许多新的分类。 新的分类既可以是 虚拟的 分类 ── 这些分类在整个 ports 目录中没有属于自己的子目录 ── 或 物理的 分类 ── 它们有自己的子目录。接下来我们将讨论与建立新的物理分类有关的事项， 以便帮助您理解如何提议建立新的分类。
我们目前的做法是避免建立新的物理分类， 除非有非常多的 port 应被归入这一分类， 或者 port 属于某一特定的小团体 (例如， 与某种人类语言相关)， 或两者皆是。
这样做的原因是这类修改会让 committer 和用户都不得不进行 许多工作 来在 Ports Collection 进行或追踪修改。 此外，提议新的分类通常都会引起争论。 (可能这是因为关于某个分类是否 “太大” 一直没有非常一致的意见的缘故， 另一方面， 分类是否能够能够有助于浏览 (以及多少个分类是合适的)， 等等， 也都是问题。)
下面是具体的步骤：
-
在 FreeBSD ports 邮件列表 提议新的分类。 您应提供建立新分类的详细依据，包括为什么认为现有的分类不够， 以及希望移动位置的一系列 port 的名字。 (如果有尚在 GNATS 而未 commit 的 port， 也应一一列出。) 如果您是相关 port 的监护人或提交者， 说明这一情况可能有助于您的提议得到通过。
-
参与讨论。
-
如果有人支持您的建议， 应及时提交一个 PR， 其中包括提议 PR 的理由， 以及需要移动的 port 的列表。 理想情况下， 这个 PR 也应包含针对下列文件的补丁：
-
进行 repocopy 之后对 Makefile 进行的修改
-
新分类的 Makefile
-
旧分类的 Makefile
-
依赖于旧 port 的 port 的 Makefile
-
(此外， 作为一项加分因素， 您还可以按照 Committer 指南所介绍的流程，提供一些其它需要修改的文件。)
-
由于这是一项影响 ports 基础设施的变动， 它不仅涉及 repo-copy 的使用，而且也可能会影响构建集群的衰退测试操作， 因此这类 PR 应分派给 Ports 管理团队 <portmgr@FreeBSD.org>。
-
如果这一 PR 得到批准， 某个 committer 将按照在 Committer 指南 中所介绍的步骤来完成余下的工作。
提议新的虚拟分类和上述过程类似， 但会容易许多， 因为不需要实际地移动任何 port。这种情况下， PR 应附带的补丁， 就只需要修改影响到的 port 的 Makefile， 以便在其中的 CATEGORIES 中加入新的分类了。
| | | | |
