5.2.命名

Port 的 Makefile 的第一部分命名 Port，描述其版本号，并将其列入正确的类别。

5.2.1. PORTNAME

将 PORTNAME 设置为软件的基础名称。它作为 FreeBSD 包的基础名称，并用于 DISTNAME。

重要

包名称必须在整个 Ports 树中唯一。确保 PORTNAME 不被现有的 Port 使用，并且没有其他 Port 使用相同的 PKGBASE。如果该名称已被使用，可以添加 PKGNAMEPREFIX 或 PKGNAMESUFFIX。

5.2.2. 版本，DISTVERSION 或 PORTVERSION

将 DISTVERSION 设置为软件的版本号。

PORTVERSION 是用于 FreeBSD 包的版本。它将自动从 DISTVERSION 推导出来，以便与 FreeBSD 的包版本方案兼容。如果版本中包含字母，可能需要设置 PORTVERSION 而不是 DISTVERSION。

重要

一次只能设置 PORTVERSION 和 DISTVERSION 其中一个。

有时，某些软件使用的版本方案与 DISTVERSION 在 PORTVERSION 中的转换方式不兼容。

技巧

在更新 Port 时，可以使用 pkg-version(8) 的 -t 参数检查新版本是否大于或小于之前的版本。请参阅下文了解如何使用 pkg-version(8) 比较版本。

示例 1. 使用 pkg-version(8) 比较版本

pkg version -t 接受两个版本作为参数，如果第一个版本小于、等于或大于第二个版本，它会分别返回 <、= 或 >。

% pkg version -t 1.2 1.3
< ①
% pkg version -t 1.2 1.2
= ②
% pkg version -t 1.2 1.2.0
= ③
% pkg version -t 1.2 1.2.p1
> ④
% pkg version -t 1.2.a1 1.2.b1
< ⑤
% pkg version -t 1.2 1.2p1
< ⑥

• ① 1.2 在 1.3 之前。
• ② 1.2 和 1.2 相等，因为它们版本相同。
• ③ 1.2 和 1.2.0 相等，因为零等同于没有。
• ④ 1.2 在 1.2.p1 之后，因为 .p1，可以理解为“预发布 1”。
• ⑤ 1.2.a1 在 1.2.b1 之前，可以理解为“alpha”和“beta”，a 在 b 之前。
• ⑥ 1.2 在 1.2p1 之前，可以理解为“2，修补级别 1”，它是任何 2.X 后但在 3 之前的版本。

在这里，a、b 和 p 被用作“alpha”、“beta”或“预发布”和“修补级别”的缩写，但它们只是字母，按字母顺序排序，因此可以使用任何字母，它们将按适当的顺序排序。

表 1. DISTVERSION 和派生的 PORTVERSION 示例

DISTVERSION	PORTVERSION
0.7.1d	0.7.1.d
10Alpha3	10.a3
3Beta7-pre2	3.b7.p2
8:f_17	8f.17

示例 2. 使用 DISTVERSION

当版本号仅包含由点、破折号或下划线分隔的数字时，使用 DISTVERSION。

PORTNAME=   nekoto
DISTVERSION=	1.2-4

这将生成 PORTVERSION 为 1.2.4。

示例 3. 使用 DISTVERSION 当版本以字母或前缀开始

当版本以字母、前缀或后缀（这些不是版本的一部分）开始或结束时，使用 DISTVERSIONPREFIX、DISTVERSION 和 DISTVERSIONSUFFIX。

如果版本是 v1.2-4：

PORTNAME=   nekoto
DISTVERSIONPREFIX=  v
DISTVERSION=	1_2_4

有时，使用 GitHub 的项目会将其名称包含在版本中。例如，版本可能是 nekoto-1.2-4：

PORTNAME=   nekoto
DISTVERSIONPREFIX=  nekoto-
DISTVERSION=	1.2_4

这些项目有时还会在版本末尾使用某些字符串，例如 1.2-4_RELEASE：

PORTNAME=   nekoto
DISTVERSION=	1.2-4
DISTVERSIONSUFFIX=  _RELEASE

或者同时使用这两者，例如 nekoto-1.2-4_RELEASE：

PORTNAME=   nekoto
DISTVERSIONPREFIX=  nekoto-
DISTVERSION=	1.2-4
DISTVERSIONSUFFIX=  _RELEASE

DISTVERSIONPREFIX 和 DISTVERSIONSUFFIX 在构建 PORTVERSION 时不会使用，只会用于 DISTNAME。

所有这些都会生成 PORTVERSION 为 1.2.4。

示例 4. 使用 DISTVERSION 当版本包含字母表示 “alpha”、“beta” 或 “pre-release”

当版本包含由点、破折号或下划线分隔的数字，且字母表示“alpha”、“beta” 或 “pre-release”（即，在没有字母的版本之前），使用 DISTVERSION。

PORTNAME=   nekoto
DISTVERSION=	1.2-pre4

PORTNAME=   nekoto
DISTVERSION=	1.2p4

这两者都会生成 PORTVERSION 为 1.2.p4，它在 1.2 之前。pkg-version(8) 可用于验证这一点：

% pkg version -t 1.2.p4 1.2
<

示例 5. 不使用 DISTVERSION 当版本包含字母表示 “Patch Level”

当版本包含字母，但这些字母不是表示“alpha”、“beta” 或 “pre”（而是表示“修补级别”），且表示的是在没有字母的版本之后，使用 PORTVERSION。

PORTNAME=   nekoto
PORTVERSION=	1.2p4

在这种情况下，使用 DISTVERSION 是不可行的，因为它会生成 1.2.p4 的版本，这将排在 1.2 之前，而不是之后。pkg-version(8) 将验证这一点：

% pkg version -t 1.2 1.2.p4
> ①
% pkg version -t 1.2 1.2p4
< ②

• ① 1.2 在 1.2.p4 之后，这在这种情况下是 错误的。
• ② 1.2 在 1.2p4 之前，这是所需的。

对于一些更高级的设置 PORTVERSION 示例，当软件的版本管理方式与 FreeBSD 的版本方案不兼容，或者当分发文件本身不包含版本时，参见 DISTNAME。

5.2.3. PORTREVISION 和 PORTEPOCH

5.2.3.1. PORTREVISION

PORTREVISION 是一个单调递增的值，每次 DISTVERSION 增加时都会重置为 0，通常是在有新的官方供应商发布版本时。如果 PORTREVISION 非零，则该值会附加到包名中。PORTREVISION 的更改会被自动化工具（如 pkg-version(8)）用于确定新包是否可用。

每次对 Port 进行更改，且该更改以某种方式影响生成的包时，都必须增加 PORTREVISION。这包括仅影响具有非默认 选项 的包的更改。

以下是需要增加 PORTREVISION 的示例：

• 添加补丁以修复安全漏洞、错误或为 Port 添加新功能。
• 更改 Port 的 Makefile 以启用或禁用包中的编译时选项。
• 更改包的打包清单或安装时的行为。例如，修改生成初始数据的脚本，如 ssh(1) 主机密钥。
• Port 的共享库依赖项版本更新（在这种情况下，用户在安装依赖项的新版本后尝试安装旧包将失败，因为它会查找旧的 libfoo.x 而不是 libfoo.(x+1)）。
• 对 Port 的分发文件进行的静默更改，且具有重要的功能差异。例如，对分发文件的更改需要更正 distinfo，但 DISTVERSION 没有相应改变，且 diff -ru 比较新旧版本显示代码有非平凡的差异。
• 更改 MAINTAINER。

以下是一些不需要增加 PORTREVISION 的更改示例：

• 对 Port 骨架的样式更改，没有影响最终包的功能。
• 更改 MASTER_SITES 或其他对 Port 的功能性更改，不会影响生成的包。
• 对分发文件进行微小的补丁，如拼写错误修正，其重要性不足以让用户费力升级。
• 构建修复，使得原本无法编译的包变得可编译。只要这些更改不会在以前能够构建的其他平台上引入功能性变化。由于 PORTREVISION 反映了包的内容，如果包之前无法构建，则不需要增加 PORTREVISION 来标记更改。

一个经验法则是判断提交到 Port 的更改是否会让某些人受益。不管是增强功能、修复问题，还是因为新包实际上能正常工作。然后，权衡这一点与这样一个事实，即这会导致所有定期更新 Ports 树的人被迫进行更新。如果是这样，就必须增加 PORTREVISION。

注意

如果没有增加 PORTREVISION，使用二进制包的人 永远 看不到更新。没有增加 PORTREVISION，包构建器无法检测到更改，因此无法重建包。

5.2.3.2. PORTEPOCH

有时，软件供应商或 FreeBSD Port 维护者会做出一些不合逻辑的决定，发布一个实际上在数字上小于之前版本的版本。例如，Port 可能从 foo-20000801 更新为 foo-1.0（前者会被错误地视为更新版本，因为 20000801 在数字上大于 1）。

技巧

版本号比较的结果并不总是显而易见的。可以使用 pkg version（请参见 pkg-version(8)）来测试两个版本号字符串的比较。例如：

% pkg version -t 0.031 0.29
>

> 输出表示版本 0.031 被认为大于版本 0.29，这一点可能对 Port 维护者来说并不显而易见。

在这种情况下，必须增加 PORTEPOCH。如果 PORTEPOCH 非零，它会像前述章节中描述的那样附加到包名中。PORTEPOCH 绝不能减少或重置为零，因为这样会导致与先前 epoch 的包比较时出现问题。例如，这个包将无法被检测为过时。尽管新版本号 1.0,1 在数字上仍小于之前的版本 20000801，但是 ,1 后缀会被自动化工具特殊处理并被视为大于先前包中的 ,0 后缀。

错误地丢弃或重置 PORTEPOCH 会导致不断的麻烦。如果上述讨论不够清晰，请参考 FreeBSD ports 邮件列表。

预计大多数 Port 不会使用 PORTEPOCH，通过合理使用 DISTVERSION 或谨慎使用 PORTVERSION，通常可以避免在软件的未来版本更改版本结构时需要使用 PORTEPOCH。然而，当供应商发布没有官方版本号的版本时（例如代码“快照”版本），FreeBSD Port 维护者需要特别小心。由于有时会将版本标记为发布日期，这会在新“官方”版本发布时引起问题，正如上面的例子所示。

例如，如果在 20000917 发布了一个快照版本，而该软件的先前版本是 1.2，则不应将 20000917 用作 DISTVERSION。正确的做法是使用 1.2.20000917 作为 DISTVERSION，或者类似的格式，这样后续版本（如 1.3）仍然是数字上更大的版本。

5.2.3.3. PORTREVISION 和 PORTEPOCH 使用示例

gtkmumble Port，版本 0.10，已提交到 Ports：

PORTNAME=	gtkmumble
DISTVERSION=	0.10

PKGNAME 变为 gtkmumble-0.10。

发现了一个安全漏洞，需要一个本地的 FreeBSD 补丁。PORTREVISION 相应地增加。

PORTNAME=	gtkmumble
DISTVERSION=	0.10
PORTREVISION=	1

PKGNAME 变为 gtkmumble-0.10_1

供应商发布了一个新版本，版本号为 0.2（事实证明作者实际上想要的是 0.10 代表 0.1.0，而不是“0.9 后的版本”——哎呀，现在已经太迟了）。由于新的次版本 2 在数字上小于之前的版本 10，必须增加 PORTEPOCH 来手动强制将新包检测为“更新的”。由于这是代码的新版本发布，PORTREVISION 被重置为 0（或从 Makefile 中删除）。

PORTNAME=	gtkmumble
DISTVERSION=	0.2
PORTEPOCH=	1

PKGNAME 变为 gtkmumble-0.2,1

下一个版本是 0.3。由于 PORTEPOCH 不会减少，因此版本变量现在是：

PORTNAME=	gtkmumble
DISTVERSION=	0.3
PORTEPOCH=	1

PKGNAME 变为 gtkmumble-0.3,1

注意

如果在此升级中将 PORTEPOCH 重置为 0，那么安装了 gtkmumble-0.10_1 包的用户将无法检测到 gtkmumble-0.3 包为更新的版本，因为 3 仍然小于 10。记住，这正是 PORTEPOCH 的作用所在。

5.2.4. PKGNAMEPREFIX 和 PKGNAMESUFFIX

两个可选变量，PKGNAMEPREFIX 和 PKGNAMESUFFIX，与 PORTNAME 和 PORTVERSION 结合，形成 PKGNAME，其格式为 ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}。确保它符合我们的良好包名指南。特别地，PORTVERSION 中不允许使用连字符（-）。此外，如果包名中有 language- 或 -compiled.specifics 部分（见下文），则分别使用 PKGNAMEPREFIX 和 PKGNAMESUFFIX，不要将它们作为 PORTNAME 的一部分。

5.2.5. 包命名规范

这些是命名包时要遵循的规范。目的是使包目录便于扫描，因为目前已经有成千上万个包，如果名称伤眼，用户会因此离开！

包名的格式为 语言_地区-名称-编译特性-版本号

包名定义为 ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}。确保设置变量以符合该格式。

语言_地区- FreeBSD 力求支持其用户的母语。当 Port 专用于某种特定语言时，语言- 部分是该语言的 ISO-639 两个字母缩写。例如，ja 表示日语，ru 表示俄语，vi 表示越南语，zh 表示中文，ko 表示韩语，de 表示德语。

如果 Port 专用于某个特定地区的语言，则还应添加两位字母的国家代码。例如，en_US 表示美式英语，fr_CH 表示瑞士法语。

语言- 部分由 PKGNAMEPREFIX 设置。

名称 确保 Port 的名称和版本清晰地分开并放入 PORTNAME 和 DISTVERSION 中。PORTNAME 中包含版本部分的唯一原因是如果上游发行版确实是按该方式命名的，例如 textproc/libxml2 或 japanese/kinput2-freewnn Port。否则，PORTNAME 中不能包含任何版本特定的信息。多个 Port 使用相同的 PORTNAME 是很常见的，就像 www/apache* Port 那样；在这种情况下，使用 PKGNAMEPREFIX 和 PKGNAMESUFFIX 值来区分不同的版本（以及不同的索引条目）。

有一个传统，就是为 Perl 5 模块命名时，前面加上 p5-，并将双冒号分隔符转换为连字符。例如，Data::Dumper 模块变为 p5-Data-Dumper。

-编译特性 如果 Port 可以通过不同的 硬编码默认值 来构建（通常是某个 Port 家族的目录名称的一部分），那么 -编译特性 部分表示已编译的默认值。连字符是可选的。示例包括纸张大小和字体单位。

-编译特性 部分由 PKGNAMESUFFIX 设置。

-版本号 版本字符串跟随一个连字符（-），并且是由整数和小写字母组成的由句点分隔的列表。特别地，版本字符串中不允许再有其他的连字符。唯一的例外是字符串 pl（表示“补丁级别”），只能在软件没有主版本号和次版本号时使用。如果软件版本中包含类似“alpha”，“beta”，“rc”或“pre”之类的字符串，则取其首字母并直接放在句点后。如果版本字符串在这些名称后继续，则数字紧跟在单个字母后，不会有额外的句点（例如，1.0b2）。

这样做的目的是为了便于通过版本字符串对 Port 进行排序。特别地，确保版本号的各个部分始终由句点分隔，如果日期是版本字符串的一部分，则使用 dyyyy.mm.dd 格式，而不是 dd.mm.yyyy 或不符合 Y2K 的 yy.mm.dd 格式。重要的是在版本前加上字母前缀，这里用 d（表示日期），以防发布带有实际版本号的版本时，其数值会小于 yyyy。

重要

包名必须在整个 Ports 树中唯一，检查是否已经存在相同的 PORTNAME，如果存在，则添加 PKGNAMEPREFIX 或 PKGNAMESUFFIX 之一。

以下是一些（真实的）示例，展示了如何将软件作者指定的名称转换为合适的包名。每行只设置了 DISTVERSION 或 PORTVERSION 其中一个，取决于在 Port 的 Makefile 中使用的是哪一个：

表 2. 包命名示例

发行版名称	PKGNAMEPREFIX	PORTNAME	PKGNAMESUFFIX	DISTVERSION	PORTVERSION	原因或备注
mule-2.2.2	(空)	mule	(空)	2.2.2		无需更改
mule-1.0.1	(空)	mule	1	1.0.1		这是 mule 的版本 1，版本 2 已经存在
EmiClock-1.0.2	(空)	emiclock	(空)	1.0.2		单个程序名不能使用大写字母
rdist-1.3alpha	(空)	rdist	(空)	1.3alpha		版本将是 1.3.a
es-0.9-beta1	(空)	es	(空)	0.9-beta1		版本将是 0.9.b1
mailman-2.0rc3	(空)	mailman	(空)	2.0rc3		版本将是 2.0.r3
v3.3beta021.src	(空)	tiff	(空)		3.3	那到底是什么？
tvtwm	(空)	tvtwm	(空)		p11	文件名中没有版本号，使用上游给出的版本号
piewm	(空)	piewm	(空)	1.0		文件名中没有版本号，使用上游给出的版本号
xvgr-2.10pl1	(空)	xvgr	(空)		2.10.pl1	在这种情况下，pl1 表示补丁级别，因此不能使用 DISTVERSION
gawk-2.15.6	ja-	gawk	(空)	2.15.6		日语版本
psutils-1.13	(空)	psutils	-letter	1.13		在包构建时硬编码了纸张大小
pkfonts	(空)	pkfonts	300	1.0		300dpi 字体包

如果原始源代码中完全没有版本信息，并且原作者不太可能发布另一个版本，则将版本字符串设置为 1.0（如上面 piewm 示例）。否则，询问原作者或使用源文件发布的日期字符串（dyyyy.mm.dd，或 dyyyymmdd）作为版本。

技巧

可以使用任何字母。这里的 d 代表日期，如果源是 Git 仓库，通常使用 g 后跟提交日期，使用 s 表示快照也是常见的。