第 5 章. 源代码树指南和策略

目录

本章介绍 FreeBSD 源代码树中实施的各种指南和策略。

5.1. 风格指南

一致的编码风格非常重要，尤其是在 FreeBSD 这样的大型项目中。代码应遵循 FreeBSD 编码风格，如 style(9) 和 style.Makefile(5) 中所述。

5.2. Makefiles 中的 MAINTAINER

如果 FreeBSD src/ 发行版的某个特定部分由个人或团队维护，则通过 src/MAINTAINERS 中的条目来进行说明。端口集合中端口的维护人员通过在相应端口的 Makefile 中添加 MAINTAINER 行来向世界表明他们的维护关系。

MAINTAINER= email-addresses

对于存储库的其他部分，或者对于没有列出维护人员的部分，或者当您不确定谁是活跃的维护人员时，请尝试查看相关源代码树部分的最近提交历史。通常，维护人员没有明确说明，但过去几年一直在源代码树的某个部分积极工作的人对审查更改感兴趣。即使这在文档或源代码本身中没有明确说明，以礼貌的形式要求审查也是非常合理的事情。

维护人员的角色如下：

  • 维护人员拥有并负责该代码。这意味着他/她负责修复与该代码相关的 bug 并回答问题报告，并且在贡献的软件情况下，根据需要跟踪新版本。

  • 对已定义维护人员的目录的更改应在提交之前发送给维护人员进行审查。只有在维护人员对多封电子邮件在不可接受的时间段内没有回复的情况下，才允许在没有维护人员审查的情况下提交更改。但是，建议您尽可能让其他人审查更改。

  • 当然，除非他们同意承担此职责，否则不允许添加个人或团队作为维护人员。另一方面，它不一定是提交者，它可以轻松地是团队。

5.3. 贡献的软件

FreeBSD 发行版中的一部分由在 FreeBSD 项目之外积极维护的软件组成。出于历史原因，我们将此称为贡献的软件。一些例子包括 LLVM、zlib(3) 和 awk(1)。

管理贡献的软件的公认程序包括创建一个供应商分支，在该分支中可以干净地导入软件（无需修改）并以版本化的方式跟踪更新。然后，供应商分支的内容将应用于源代码树，可能进行本地修改。FreeBSD 特定的构建胶水在源代码树中维护，而不是在供应商分支中。

根据其需求和复杂性，各个软件项目可能会根据维护人员的决定偏离此程序。更新特定贡献的软件所需的精确步骤应记录在名为 FREEBSD-upgrade 的文件中；例如，libarchive 的 FREEBSD-upgrade 文件。

贡献的软件通常放置在源代码树的 contrib/ 子目录中，但也有一些例外。仅由内核使用的贡献的软件位于 sys/contrib/ 下。

由于这会使导入未来的版本变得更加困难，因此强烈不建议对仍在跟踪供应商分支的文件进行微不足道、琐碎或美观的更改。

5.3.1. 供应商导入

管理贡献的软件和供应商分支的标准流程在 提交者指南 中进行了详细描述。

5.4. 受限制的文件

有时可能需要在 FreeBSD 源代码树中包含受限制的文件。例如，如果某个设备需要加载一小段二进制代码才能运行，而我们没有该代码的源代码，那么该二进制文件被称为受限制的。以下策略适用于在 FreeBSD 源代码树中包含受限制的文件。

  1. 任何由系统 CPU 解释或执行且不是源代码格式的文件都是受限制的。

  2. 任何许可证比 BSD 或 GNU 更严格的文件都是受限制的。

  3. 包含硬件使用的可下载二进制数据的文件不受限制，除非它满足 (1) 或 (2)。

  4. 任何受限制的文件都需要在添加到存储库之前获得 核心团队 的特定批准。

  5. 受限制的文件位于 src/contrib 或 src/sys/contrib 中。

  6. 整个模块应保持在一起。除非与不受限制的代码共享代码，否则没有必要将其拆分。

  7. 过去，二进制文件通常使用 uuencode 进行编码，并命名为 arch/filename.o.uu。这不再必要，二进制文件可以不经修改地添加到存储库中。

  8. 内核文件

    1. 应始终在 conf/files.* 中引用（为了构建简便）。

    2. 应始终在 LINT 中，但 核心团队 会根据具体情况决定是否将其注释掉。当然，核心团队 以后可能会改变主意。

    3. 发行版工程师决定是否将其包含在发行版中。

  9. 用户空间文件

    1. 核心团队 决定代码是否应作为 make world 的一部分。

    2. 发行版工程 决定是否将其包含在发行版中。

5.5. 共享库

如果您正在为没有共享库支持的端口或其他软件添加共享库支持，则版本号应遵循以下规则。通常，最终的数字与软件的发行版版本无关。

对于端口

  • 优先使用上游已选择的数字

  • 如果上游提供符号版本控制，请确保我们使用他们的脚本

对于基本系统

  • 将库版本从 1 开始

  • 强烈建议为新库添加符号版本控制

  • 如果有不兼容的更改，请使用符号版本控制来处理它，保持向后的 ABI 兼容性

  • 如果这不可能，或者库不使用符号版本控制，请增加库版本

  • 在考虑为使用符号版本控制的库增加库版本之前，请咨询发行版工程团队，说明为什么更改如此重要，以至于即使破坏 ABI 也应允许进行更改

例如，添加函数和 bug 修复而没有更改接口是可以的，而删除函数、更改函数调用语法等则应提供向后兼容的符号，或者将强制主版本号更改。

进行更改的提交者有责任处理库版本控制。

ELF 动态链接器按字面匹配库名称。有一个流行的约定，其中库版本以 libexample.so.x.y 的形式编写，其中 x 是主版本，y 是次版本。常见的做法是将库的 soname（DT_SONAME ELF 标签）设置为 libexample.so.x，并在库安装时为最新次版本 y 设置符号链接 libexample.so.x→libexample.so.x.y、libexample.so→libexample.so.x。然后，由于静态链接器在指定 -lexample 命令行选项时会搜索 libexample.so，因此与 libexample 链接的对象会依赖于正确的库。几乎所有流行的构建系统都会自动使用这种方案。

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

首页