1 / 42

文章

编辑日志

警告
除已校对部分外，本项目目前翻译错漏百出，不适合用于生产。
本项目目前处于低维护状态，主要维护者因精力所限仅处理 PR。欢迎社区通过 PR 贡献力量。

点击页面左上角的“文章”可以选择其他内容

2025.5.6 重译
2024.7.3-2024.7.5 机器翻译完成。

FreeBSD 中文文章翻译项目

警告
除已校对部分外，本项目目前翻译错漏百出，不适合用于生产。
本项目目前处于低维护状态，主要维护者因精力所限仅处理 PR。欢迎社区通过 PR 贡献力量。

正在施工

由于过于冗长且无翻译意义的原因，《FreeBSD 的贡献者》和《OpenPGP 密钥》两篇文章略去不译。

使用 FreeBSD 开发产品

摘要

FreeBSD 项目是一个全球性的、基于志愿者的合作项目，旨在开发一个可移植且高质量的操作系统。FreeBSD 项目以宽松的许可协议发布其产品的源代码，目的是鼓励更多的用户使用其代码。与 FreeBSD 项目合作可以帮助组织减少产品上市时间、降低工程成本，并提高产品质量。

本文探讨了在家电和软件产品中使用 FreeBSD 代码时可能遇到的问题。它突出了 FreeBSD 的一些特性，使其成为产品开发的优秀基础平台。文章最后建议了一些与 FreeBSD 项目合作时的“最佳实践”。

1. 简介

FreeBSD 今天已广泛知名，作为一种高性能的服务器操作系统，它已在全球数百万台 Web 服务器和互联网主机上部署。FreeBSD 的代码也构成了许多产品的核心部分，从网络路由器、防火墙和存储设备等家电，到个人计算机。FreeBSD 的部分内容也已用于商业包装软件中（请参阅）。

在本文中，我们将从软件工程资源的角度探讨，即作为一组构建模块和过程，你可以利用它们来构建产品。

尽管 FreeBSD 的源代码是公开免费的，但为了充分享受该项目成果的好处，组织需要与该项目进行合作。在本文接下来的章节中，我们将讨论与 FreeBSD 项目有效合作的方式，以及在此过程中需要避免的陷阱。

读者警告。 作者认为，本文中列出的 FreeBSD 项目的特点在文章构思和撰写时（2005年）是大致真实的。然而，读者应当意识到，开源社区使用的实践和过程会随着时间的推移发生变化，因此本文中的信息应被视为指示性而非规范性。

1.1. 目标读者

本文适合以下广泛群体：

产品公司的决策者，他们希望提高产品质量，减少上市时间，并在长期内降低工程成本。
寻找利用“开源”最佳实践的技术顾问。
对理解开源项目动态感兴趣的行业观察者。
希望使用 FreeBSD 并寻找贡献方式的软件开发者。

1.2. 文章目标

阅读完本文后，你应当能够：

理解 FreeBSD 项目的目标及其组织结构。
理解其开发模式和发布工程过程。
理解传统企业软件开发过程与 FreeBSD 项目中使用的过程有何不同。
了解项目使用的通信渠道，以及你可以期待的透明度程度。

1.3. 文章结构

本文的其余部分结构如下：

介绍了 FreeBSD 项目，探讨了其组织结构、关键技术和发布工程过程。
介绍了与 FreeBSD 项目合作的方式，并审视了企业在与 FreeBSD 等志愿项目合作时常遇到的陷阱。
进行总结。

2. FreeBSD 作为构建模块集

FreeBSD 是构建产品的优秀基础：

FreeBSD 源代码以宽松的 BSD 许可协议发布，方便其在商业产品中采纳。让其在商业化过程中几乎没有麻烦。
FreeBSD 项目有着卓越的工程实践，企业可以加以利用。
该项目提供了异常透明的工作流程，使得使用其代码的组织可以有效地规划未来。
从加利福尼亚大学伯克利分校的计算机科学研究组

更详细地探讨了使用开源的商业原因。对于企业来说，将 FreeBSD 组件用于产品中带来的好处包括缩短上市时间、降低开发成本和降低开发风险。

2.1. 使用 FreeBSD 构建

以下是一些组织使用 FreeBSD 的方式：

作为库和工具的上游源代码。作为该项目的“下游”，企业可以利用上游代码所获得的新特性、错误修复和测试。
作为嵌入式操作系统（例如，用于 OEM 路由器和防火墙设备）。在这种模型下，企业使用定制的 FreeBSD 内核和应用程序集，并为设备添加专有的管理层。OEM 可以从 FreeBSD 项目上游添加的新硬件支持中受益，并从基础系统所接受的测试中获益。 FreeBSD 提供了一个自托管的开发环境，允许轻松创建这样的配置。
作为高端存储和网络设备管理功能的类 Unix 环境，运行在独立的处理器“刀片”上。 FreeBSD 提供了创建专用操作系统和应用程序镜像的工具。它对 BSD Unix API 的实现已经成熟并经过测试。FreeBSD 还可以为高端设备的其他组件提供稳定的交叉开发环境。

2.2. 技术

FreeBSD 项目支持大量的技术，以下是其中的一部分：

一个完整的系统，可以为进行交叉托管。
一个模块化的对称多处理能力内核，具有可加载的内核模块和灵活易用的配置系统。
支持以接近机器速度模拟 Linux™ 和 SVR4 二进制文件。支持二进制 Windows™ (NDIS) 网络驱动程序。
提供多种编程任务的库：归档工具、FTP 和 HTTP 支持、线程支持，以及完整的 POSIX™ 类编程环境。

2.3. 组织结构

FreeBSD 的组织结构是非等级化的。

FreeBSD 的贡献者主要分为两类：普通用户和具有写权限的开发者（在术语中称为 committers）。

第一类贡献者有成千上万；绝大多数对 FreeBSD 的贡献来自于这个群体。对代码库的提交权限（写权限）授予那些对项目有持续贡献的个人。获得提交权限的开发者将承担额外的责任，且新提交者会分配导师，以帮助他们学习相关流程。

图 1. FreeBSD 组织结构

冲突解决由一个由九名成员组成的“核心团队”来执行，该团队由提交者选举产生。

FreeBSD 没有“企业”提交者。个人提交者需要对自己引入的代码变更负责。详细记录了提交者的规则和责任。

FreeBSD 的项目模型在中有详细的讨论。

2.4. FreeBSD 发布工程流程

FreeBSD 的发布工程流程在确保发布版本质量高方面起着重要作用。在任何时间点，FreeBSD 的志愿者都会支持多个代码分支（）：

新特性和破坏性代码进入开发分支，也称为 -CURRENT 分支。
-STABLE 分支是从 HEAD 定期分支出来的代码线。只有经过测试的代码才能进入 -STABLE 分支。新特性在 -CURRENT 分支中经过测试和稳定后，才允许进入 -STABLE 分支。
-RELEASE 分支由 FreeBSD 安全团队维护。只有对关键问题的 bug 修复才能进入 -RELEASE 分支。

图 2. FreeBSD 发布分支

代码分支会保持活跃，直到用户和开发者对其仍有兴趣。

机器架构被分为“层级”；Tier 1 架构由项目的发布工程和安全团队全面支持，Tier 2 架构按最佳努力支持，而实验性架构则属于 Tier 3。支持的是 FreeBSD 文档的一部分。

发布工程团队在项目网站上发布了。路线图中列出的日期并非截止日期；FreeBSD 会在代码和文档准备好时发布。

FreeBSD 的发布工程流程可参见。

3. 与 FreeBSD 协作

像 FreeBSD 这样的开源项目提供了非常高质量的成品代码。

尽管访问优质源代码可以降低初始开发成本，但随着时间的推移，管理变更的成本将开始占主导地位。随着计算环境的变化和新安全漏洞的发现，你的产品也需要改变和适应。使用开源代码最好视为一个 持续过程 而非一次性活动。最适合合作的项目是那些 活跃的 项目；即，拥有活跃社区、明确目标和透明工作风格的项目。

FreeBSD 拥有一个活跃的开发者社区。截至目前，来自全球每个有人口的大陆的许多贡献者参与其中，且有 300 余名具有提交权限的个人。
FreeBSD 项目的目标是：
- 为流行的计算机硬件开发一个高质量的操作系统；

3.1. 理解 FreeBSD 文化

为了有效地与 FreeBSD 项目合作，你需要理解该项目的文化。

志愿者驱动的项目与营利性公司运作的规则不同。公司进入开源世界时常犯的一个错误是低估了这些差异。

动机。 大多数对 FreeBSD 的贡献都是自愿进行的，没有金钱奖励参与其中。驱动个人参与的动机因素是复杂的，从利他主义到解决 FreeBSD 所尝试解决的问题的兴趣不等。在这种环境中，“优雅从来不是可选的”。

长期视角。 FreeBSD 的根源可以追溯到近二十年前，加利福尼亚大学伯克利分校计算机科学研究组（CSRG）的工作。[1](FreeBSD 的源代码库包含了自项目创立以来的所有历史记录，并且还有可用的 CD-ROM，里面包含了 CSRG（计算机科学研究组）早期的代码。 ) 一些最初的 CSRG 开发者仍与该项目保持联系。

该项目重视长期视角。在项目中，一个常见的缩写是 DTRT，代表“做正确的事”（Do The Right Thing）。

开发流程。 计算机程序是沟通的工具：在一个层面上，程序员通过精确的符号与工具（编译器）沟通，工具将他们的指令翻译成可执行代码。在另一个层面上，相同的符号用于程序员之间意图的沟通。

在项目中，很少使用正式的规格和设计文档。相反，使用清晰且编写良好的代码和变更日志（）。FreeBSD 的开发通过“粗略共识和运行中的代码”进行。

变更日志样本

程序员之间的沟通通过使用通用编码标准得到增强。

沟通渠道。 FreeBSD 的贡献者遍布全球。电子邮件（以及较少使用的 IRC）是项目中首选的沟通方式。

3.2. 与 FreeBSD 项目合作的最佳实践

接下来，我们来看一些在产品开发中最有效利用 FreeBSD 的最佳实践。

规划长期发展 设置有助于跟踪 FreeBSD 开发进展的流程。例如：

跟踪 FreeBSD 源代码。 该项目通过使用使镜像其 SVN 仓库变得简单。拥有完整的源代码历史对于调试复杂问题非常有用，并且可以深入了解原开发者的意图。使用一个强大的源代码管理系统，可以轻松地合并上游 FreeBSD 代码库和你自己内部代码之间的变化。

显示了由变更日志引用的文件的注释清单部分。每一行代码的祖先历史清晰可见。显示 FreeBSD 每个文件历史的注释清单。

通过 svn blame 生成的注释源代码清单

使用 gatekeeper（门控者）。 任命一名 gatekeeper 来监控 FreeBSD 开发，及时发现可能影响你产品的变化。

向上游报告 bug。 如果你注意到正在使用的 FreeBSD 代码中有 bug，请提交一个。这一步可以确保下次你从上游获取代码时不必再次修复该 bug。

利用 FreeBSD 的发布工程努力。 使用来自 -STABLE 开发分支的代码。这些开发分支由 FreeBSD 的发布工程和安全团队正式支持，并且包含经过测试的代码。

捐赠代码以降低成本。 开发产品的主要成本之一是维护工作。通过向项目捐赠非关键代码，你可以使你的代码得到比通常更多的曝光，从而有助于发现更多的 bug、安全漏洞以及性能问题，并且能够被修复。

有效获取支持。 对于有紧迫期限的产品，建议你聘请或与有 FreeBSD 经验的开发者或公司达成咨询协议。你可以通过寻找人才。FreeBSD 项目还维护了一个，他们提供 FreeBSD 工作相关的服务。提供所有主要 BSD 派生操作系统的认证。

对于不太紧急的需求，你可以在上寻求帮助。询问帮助时遵循这篇指南。

公开宣传你的参与。 你不必公开宣传你使用 FreeBSD，但这样做有助于你的努力和项目的发展。

让 FreeBSD 社区知道你的公司使用 FreeBSD，有助于提高吸引高质量人才的机会。广泛的支持 FreeBSD 也意味着开发者中对它的关注度更高，这反过来为你的未来奠定了更健康的基础。

支持 FreeBSD 开发者。 有时候，将一个所需的功能加入 FreeBSD 的最直接方法是支持已经在处理相关问题的开发者。帮助可以从硬件捐赠到直接的财政援助不等。在一些国家，捐赠 FreeBSD 项目可以享受税收优惠。该项目有专门的来协助捐赠者。项目还维护一个网页，开发者在这里。

作为政策，FreeBSD 项目会在其网站上所有收到的贡献。

4. 结论

FreeBSD 项目的目标是创建并公开一个高质量操作系统的源代码。通过与 FreeBSD 项目的合作，你可以在多个产品开发场景中降低开发成本，并提高上市时间。

我们考察了 FreeBSD 项目的特性，阐明了它为什么是作为组织产品战略一部分的优秀选择。然后，我们探讨了该项目的主流文化，并审视了与其开发者有效互动的方法。本文最后列出了与项目合作时可能有帮助的最佳实践。

参考文献

[Carp1996] B. Carpenter. The Internet Architecture Board.The Internet Architecture Board. Copyright® 1996.

[ComGuide] The FreeBSD Project. Copyright® 2005.

[GoldGab2005] Ron Goldman. Richard Gabriel. Copyright® 2005. Morgan-Kaufmann.

[Hub1994] Jordan Hubbard. Copyright® 1994-2005. The FreeBSD Project.

[McKu1999] Kirk McKusick. Gregory Ganger. Copyright® 1999.

[McKu1999-1] Marshall Kirk McKusick. O’Reilly Inc.. Copyright® 1993.

[Mon2005] Bruce Montague. The FreeBSD Project. Copyright® 2005.

[Nik2005] Niklas Saers. Copyright® 2005. The FreeBSD Project.

[Nor1993] Peter Norvig. Kent Pitman. Copyright® 1993.

[Nor2001] Peter Norvig. Copyright® 2001.

[Ray2004] Eric Steven Raymond. Copyright® 2004.

[RelEngDoc] Murray Stokely. Copyright® 2001. The FreeBSD Project.

FreeBSD 上的打印服务器（CUPS）

原文链接

摘要

本文介绍了如何在 FreeBSD 上配置 CUPS。

FreeBSD 状态报告流程

原文：FreeBSD Status Report Process

FreeBSD 状态报告每季度发布一次，向公众提供了项目的最新动态，它们通常会附带来自开发者峰会的特别报告。由于状态报告是我们最为显眼的沟通形式之一，因此它们非常重要。

在本文档中以及与 FreeBSD 状态报告相关的其他地方，状态报告 这个术语既指代每季度发布的文档，也指其中的单个条目。

1. 为作者提供的写作指南

本节提供了一些写作状态报告条目的建议，也包括如何提交条目的说明。

不要担心自己的母语不是英语。状态团队会检查你的条目，并修正拼写和语法错误。

1.1. 介绍你的工作

不要假设阅读报告的人了解你的项目。

状态报告的受众广泛。它们通常是 FreeBSD 网站上的头条新闻，是人们了解 FreeBSD 相关信息时首先阅读的内容。考虑这个例子：

如果读者熟悉 UNIX 手册页，他们会知道 abc(4) 是某种设备。但读者为什么需要关心呢？它是何种设备？对比以下版本：

现在读者知道 abc 是一款网络接口驱动程序。即便他们不使用 Yoyodyne 的产品，你已经传达了 FreeBSD 在网络设备方面的支持正在不断增强。

1.2. 显示你工作的意义

状态报告不仅仅是告诉大家做了什么，它们还需要解释为什么要做这些事情。

继续前面的例子。现在我们支持 Yoyodyne Frobnicator 卡，为什么这件事值得一提？它们广泛使用吗？是否在某些流行设备中使用？是否在 FreeBSD 希望进入的特定领域有重要地位？它们是否是世界上最快的网卡？状态报告通常会包含类似这样的内容：

然后就停了，也许读者是 Cyberdyne 的忠实粉丝，知道 T800 带来了哪些激动人心的新特性，但这并不常见。大多数情况下，他们可能对你导入的内容不太了解（尤其是对于 Ports：记住那里面有 35,000 余项其他条目）。列出一些新特性或修复的 bug，告诉他们为什么我们获得了新版本是件好事。

1.3. 告诉我们一些新信息

不要重复相同的状态报告条目。

请记住，状态报告不仅仅是对项目状态的报告，它们还是项目状态变化的报告。如果某个项目正在进行中，简要介绍一下它，但接下来要专注于新工作。自上次报告以来有什么进展？还剩下什么工作？什么时候可能完成（或者如果“完成”并不适用，那什么时候可能准备好供更广泛的使用、测试、生产部署等）？

1.4. 赞助

不要忘记提及你的赞助商。

如果你或你的项目获得了赞助，或者你已经作为承包商或员工为某公司工作，请在报告中提到。赞助商总是很高兴你感谢他们的资助，同时他们也会从中受益，展示他们在积极支持 FreeBSD 项目。最后，这有助于 FreeBSD 更好地了解其重要的用户。

1.5. 待办事项

如果需要帮助，请明确说明！

是否需要别人提供帮助？有没有任务是其他人可以完成的？你可以在状态报告中的待办事项部分用两种方式来描述：请求帮助，或者快速概述剩余的工作量。如果已经有足够多的人参与项目，或者项目处于一个不适合增加人手的状态，那么后一种方式更为合适。列出正在进行的大任务，可能还可以标明每个任务的负责人。

列出任务，提供足够的细节让人们知道他们是否能够做这些事情，并邀请他们联系你。

1.6. 提交报告

你可以通过以下方法提交你的报告：

提交，并将 status 组添加到审阅者列表。你应该将报告放在 doc/website/content/en/status/ 的适当子目录中（如果缺少此子目录，创建它）；
通过提交 pull request 到文档仓库。你应该将报告放在 doc/website/content/en/status 的适当子目录中（如果缺少此子目录，创建它）；
发送电子邮件至，并附上你的报告。

可以参考。

2. 编辑指南

本节介绍了状态报告的审阅和发布流程。

2.1. 时间线

状态团队始终接受报告，但主要的收集过程发生在每个季度的最后一个月，即 3 月、6 月、9 月和 12 月。在这些月份，会明确发出状态报告的征集通知。1 月、4 月、7 月和 10 月则专注于整理上一季度提交的报告，这期间可能会等待迟交的报告。状态报告的发布会在报告准备好后尽快完成，通常是在同一个季度内。

所有报告的提交截止日期可以通过请求延期，延期时间为季度结束后 8 天。由于状态报告和季度 Ports 分支之间的重叠，的条目默认为延期截止。

提交报告的审阅工作通常应在 1 月、4 月、7 月和 10 月的中旬完成（第三方审阅期）。也就是说，除了错别字或轻微的文稿编辑外，状态团队应该在每月 15 日之后开始整理提交的报告。请注意，这并不是完全冻结，状态团队仍然可以接受审阅。

第一季度

第二季度

第三季度

第四季度

2.2. 征集报告

状态报告的征集通知会发送给以下收件人：

；
所有上次提交状态报告的人（他们可能有更新或进一步的改进）；
根据季节变化：

发送状态报告征集通知的最简单方法是使用，该脚本位于文档 git 仓库的 tools/sendcalls 目录中。该脚本会自动发送通知给所有预定的收件人。也可以通过定时任务来使用，例如：

警告、如果你负责发送状态报告的调用，并且确实使用了 cron 作业，请在 freefall 上运行它并签上你的名字，以便在出现问题时能够推断出是谁配置了该 cron 作业。同时，请将上面的示例更新为包含你的名字，作为额外的安全措施。

也可以考虑像在论坛上发布状态报告的调用。

2.3. 构建报告

提交的报告会在收到后进行审查，并合并到 doc/website/content/en/status/ 的适当子目录中。在报告更新的同时，状态团队之外的人也可以审查各个条目并提出修正建议。

通常，内容审查过程的最后一步是写一个名为 intro.adoc 的文件中的介绍：只有在所有报告收集完毕后，才能写出好的介绍。如果可能，最好让不同的人写介绍，以增加多样性：不同的人会带来不同的观点，有助于保持新鲜感。

待所有报告和介绍准备好后，需要创建 _index.adoc 文件：这是报告按类别分发并排序的文件。

2.4. 发布报告

当状态报告的所有文件准备就绪后，就可以发布它了。

首先，编辑 doc/website/content/en/status/_index.adoc：更新下一个截止日期并添加新报告的链接。然后将更改推送到仓库，状态团队检查一切是否按预期工作。

接着，将新闻条目添加到 doc/website/data/en/news/news.toml 中。

以下是新闻条目的示例：

报告的 HTML 版本已经构建并上线后，使用将网站转储为纯文本，例如：

完全支持 Unicode。-dump 仅输出 HTML 代码的文本渲染，之后可以删除其中的一些元素，而 -cols 确保所有内容都换行到 80 列。

链接到渲染后的报告会添加在介绍和第一个条目之间。

最后，报告准备好发送，切换邮件的显示方式（报告应嵌入邮件正文中），并确保它以 UTF-8 编码。

发送两封电子邮件，主题格式为 FreeBSD 状态报告 - <第一/第二/第三/第四> 季度 <年份>：

一封发送到 ;

重要
这封邮件必须获得批准，因此，如果你负责发送此邮件，请确保有人批准（如果处理时间过长，请邮件联系）。

一封发送到，并抄送到、和 [email protected]。

FreeBSD 对闰秒的支持

原文：FreeBSD Support for Leap Seconds

1. 介绍

闰秒是每年在特定时刻对 UTC 进行的一秒钟调整，用以将原子时间与地球自转的变化同步。本文介绍了 FreeBSD 如何处理闰秒。

截至本文写作时，下一个闰秒将在 2015 年 6 月 30 日 23:59:60 UTC 发生。这个闰秒将在北美、南美和亚太地区的工作日内发生。

闰秒由在中宣布。

标准的闰秒行为介绍见。也请参考。

2. FreeBSD 默认的闰秒处理

处理闰秒的最简单方法是使用 FreeBSD 默认的 POSIX 时间规则，结合。当运行时，且系统时间与正确处理闰秒的上游 NTP 服务器同步，闰秒将导致系统时间自动重复当天的最后一秒。无需其他调整。

如果上游 NTP 服务器没有正确处理闰秒，会在上游服务器注意到并自行调整后，将系统时间调整一秒。

如果没有使用 NTP，在闰秒过去后需要手动调整系统时钟。

3. 注意事项

闰秒是在全球范围内同一时刻插入的：UTC 午夜。在日本是上午，在太平洋地区是中午，在美洲是傍晚，而在欧洲是晚上。

我们相信并期望，FreeBSD 在提供正确且稳定的 NTP 服务时，会在这次闰秒时正常工作，就像之前的闰秒一样。

然而，我们要提醒的是，几乎没有应用程序曾经向内核询问过关于闰秒的信息。我们的经验是，按照设计，闰秒本质上是对闰秒前一秒的重播，而这对大多数应用程序开发人员来说是一个意外。

其他操作系统和其他计算机可能会或不会像 FreeBSD 一样处理闰秒，没有正确和稳定的 NTP 服务的系统根本无法了解闰秒。

计算机因闰秒而崩溃并非罕见，经验表明，许多公共 NTP 服务器可能会错误地处理并宣布闰秒。

请尽量确保闰秒事件不会造成严重问题。

4. 测试

可以测试是否会使用闰秒。由于 NTP 的性质，测试可能在闰秒前最多 24 小时内有效。一些主要的参考时钟源只会在事件发生前一小时宣布闰秒。查询 NTP 守护进程：

包含 leap_add_sec 的输出表示正确支持闰秒。在闰秒前的 24 小时内或闰秒过后，将显示 leap_none。

5. 结论

实际上，闰秒通常不会在 FreeBSD 上造成问题。我们希望这篇概述能帮助澄清预期情况，并确保闰秒事件的顺利进行。

Port 导师指南

原文：Port Mentor Guidelines
作者：Thomas Abthorpe, Chris Rees

1. 导师/学员关系指南

本节旨在帮助解开导师关系的谜团，并作为公开促进建设性讨论的方式，以适应和发展这些指南。在我们的生活中有太多的规则；我们不是个强制执行法规的政府组织，而是由志同道合的人们组成的集体，致力于共同目标，保持我们称之为 Ports 的产品质量保证。

1.1. 为什么做导师？

对于我们中的大多数人来说，都是在项目中得到了导师的指导，因此回报这个恩惠，向其他人提供指导。
你有一种不可抗拒的冲动，想要将知识传授给别人。
通常的“惩罚”是因为你已经厌倦了贡献别人做的好工作！

1.2. 导师/共同导师

共同导师的理由：

显著的时区差异。通过即时通讯可以方便互动的导师非常有帮助！
可能存在语言障碍。是的，FreeBSD 主要以英语为主，就像大多数软件开发一样，但是，如果有一个能讲母语的导师，那将非常有用。
没有时间！直到有了 30 小时的一天和 8 天的一周，我们中的一些人只能提供有限的时间。与其他人分担负担会更容易。
初级导师可以从资深提交者/导师那里获得经验。

单独担任导师的理由：

你不喜欢与他人合作。
你更喜欢一对一的关系。
共同导师的理由对你不适用。

1.3. 期望

我们期望导师能够审查并测试构建所有提出的补丁，至少在最初的一个多星期或两周内进行。

我们期望导师应对其学员的行为负责。导师应跟进学员所做的所有提交，无论是已批准的还是隐性提交。

我们期望导师确保学员阅读、和。虽然没有必要记住所有的细节，但每个提交者都需要了解这些内容，才能有效地成为社区的一部分（并尽量避免犯新手错误）。

1.4. 选择学员

没有明确的规则来判断候选人是否准备好；它可以是他们提交的 PR 数量、维护的 Port 数量、Port 更新的频率或在 GNOME、KDE、Gecko 等特定领域的参与程度的组合。

候选人应该几乎没有超时，能够及时回应请求，并且在支持其 Port 上通常是乐于助人的。

必须有一定的参与历史，因为普遍认为培训一名提交者需要时间和精力。如果某人已经在社区里呆了更长时间，并花时间观察事情是如何做的，那么可以预期其积累了一些知识。我们常常看到有的维护者提交了几个 PR，出现在 IRC 上，问什么时候可以获得提交权限。

订阅并关注邮件列表非常有益。没有真正的期望认为在邮件列表上发布帖子会使某人成为提交者，但它展示了参与。有些邮件能提供候选人的知识见解，以及他们如何与他人互动。同样，参与 IRC 也可以让某人提高知名度。

如果你问六个不同的提交者，一个维护者在被提名之前应该提交多少个 PR，你将得到六个不同的答案。如果问这些人应该参与多久，也会是同样的困境。最低应该有多少个 Port？现在我们有“分歧”！有些事情很难量化，导师只能凭借他们的最佳判断，期望 portmgr 同意。

1.5. 导师关系的持续时间

随着信任水平的发展，学员可能会被授予“隐性”提交权限。这可以包括对 Makefile、pkg-descr 等的小修改。同样，它也可以包括不包含 plist 更改的 PORTVERSION 更新。在导师的酌情决定下，可能会形成其他情况。然而，在导师关系期间，影响依赖 Port 的版本提升应该由导师检查。

正如我们每个人都是不同的个体，每位学员有不同的学习曲线、时间承诺和其他影响因素，这些因素会影响他们何时能够“独立操作”。经验上，学员应该观察至少 3 个月。90-100 次提交是导师可以使用的另一目标，之后可以考虑让学员独立。其他考虑因素包括他们可能犯过的错误、收到的 QAT 等。如果他们仍然犯新手错误，仍然需要导师指导。

1.6. 导师/共同导师辩论

当一个请求提交给 portmgr 时，通常是：“我提议将 'foo' 提名为 Port 提交者，我将与 'bar' 一起共同担任导师。” 提案接收、投票并通过。

导师是主要的联络人，或者说是“首席”，共同导师是备用。

有个不愿透露姓名的坏蛋做出了。类似的共同导师提交也出现在 src 树中。这就意味着对吗？这就意味着错吗？似乎这是事物发展的一部分。

1.7. 期望

我们期望学员准备好接受来自社区的建设性批评。社区中仍有许多“经验”，但这些经验并未写下来。我们希望通过首先审查学员在 IRC 和邮件列表上的现有贡献来挑选那些能够很好回应建设性批评的人。

我们警告学员，某些收到的批评可能不那么“建设性”（可能是语言沟通问题，或者过于挑剔），并且优雅地处理这些批评是成为大型社区一员的一部分。如果与某些人有特定问题，或有任何疑问，我们希望学员能够通过 IRC 或电子邮件联系 portmgr 成员。

vinum 卷管理器

原文：The vinum Volume Manager

1. 概述

无论硬盘类型如何，总是存在潜在的问题。硬盘可能太小、太慢，或者可靠性不足，无法满足系统的要求。尽管硬盘的容量越来越大，但数据存储需求也在不断增加。常常需要一个比硬盘容量更大的文件系统。为了解决这些问题，已经提出并实现了各种解决方案。

其中一种方法是使用多个有时是冗余的硬盘。除了支持各种卡和控制器用于硬件独立磁盘冗余阵列（RAID）系统外，FreeBSD 基本系统还包括 vinum 卷管理器，它是一个块设备驱动程序，实现了虚拟磁盘驱动器，并解决了这三个问题。vinum 提供比传统磁盘存储更高的灵活性、性能和可靠性，并实现了 RAID-0、RAID-1 和 RAID-5 模型，既可以单独使用，也可以组合使用。

本章概述了传统磁盘存储的潜在问题，并介绍了 vinum 卷管理器。

警告
已弃用 vinum，并且在 FreeBSD 15.0 及以后的版本中不再存在。建议用户迁移到、、、或。

注意
从 FreeBSD 5 开始，vinum 被重写为适应，同时保留了原始的思想、术语和磁盘上的元数据。这个重写版本被称为 gvinum（即 GEOM vinum）。虽然本章使用 vinum 这个术语，但所有命令的调用应使用 gvinum。内核模块的名称已从原来的 vinum.ko 更改为 geom_vinum.ko，所有设备节点位于 /dev/gvinum 下，而不是 /dev/vinum。从 FreeBSD 6 开始，原始的 vinum 实现不再出现在代码库中。

2. 访问瓶颈

现代系统经常需要高并发地访问数据。例如，大型 FTP 或 HTTP 服务器可以维护数千个并发会话，并通过多个 100 Mbit/s 的连接与外部世界通信，这远超大多数硬盘的持续传输速率。

当前的硬盘可以以最高 70 MB/s 的速度顺序传输数据，但在许多独立进程访问同一硬盘的环境下，这个速度并不重要，而且它们可能只能达到这些数值的一小部分。在这种情况下，更有意义的是从磁盘子系统的角度来看问题。关键的参数是传输给子系统带来的负载，或者传输占用参与传输的硬盘的时间。

在任何磁盘传输中，硬盘必须先定位磁头，等待第一个扇区通过读写磁头，然后执行传输。这些动作可以视为原子操作，因为中途打断它们是没有意义的。

假设一次典型的传输大约是 10 kB：当前一代高性能硬盘平均定位磁头的时间是 3.5 毫秒。最快的硬盘转速为每分钟 15,000 转，因此平均旋转延迟（半圈）是 2 毫秒。在 70 MB/s 的传输速率下，传输本身大约需要 150 微秒，这几乎可以忽略不计，相比之下，定位时间占据了绝大部分时间。在这种情况下，实际的传输速率降到了每秒 1 MB 以上，并且显然高度依赖于传输的大小。

传统且明显的解决方法是“更多的盘片”：与其使用一块大硬盘，不如使用多个较小的硬盘，总存储空间相同。每个硬盘都能独立进行定位和传输，因此有效吞吐量将接近所用硬盘的数量。

然而，实际的吞吐量提高幅度小于所用硬盘的数量。尽管每个硬盘都能够并行传输，但无法确保请求能均匀分布在各个硬盘上。不可避免地，某些硬盘的负载将高于其他硬盘。

硬盘负载的均匀性与数据在硬盘上的分布方式密切相关。以下讨论中，便于理解的方式是将磁盘存储看作一个包含大量数据扇区的空间，可以通过编号访问，就像一本书的页面一样。最明显的方法是将虚拟磁盘划分为多个连续的扇区组，每组大小与单个硬盘的大小相同，并按此方式存储，类似于将一本大书撕成若干小部分。该方法称为 连接（concatenation），其优点是硬盘不需要有任何特定的大小关系。当访问虚拟磁盘时，访问均匀分布在其地址空间时，这种方法效果良好。如果访问集中在较小的区域，效果则较差。说明了在连接组织中，存储单元分配的顺序。

图 1. 连接组织

另一种映射方法是将地址空间划分为更小的、大小相等的单元，并将它们顺序存储在不同的设备上。例如，前 256 个扇区存储在第一块硬盘上，接下来的 256 个扇区存储在第二块硬盘上，以此类推。直到最后一块硬盘填满，过程重复进行。这个映射方法称为 条带化（striping） 或 RAID-0。

RAID 提供了各种形式的容错机制，但 RAID-0 有些误导，因为它没有提供冗余。条带化需要稍多的工作来定位数据，并且当传输跨多个硬盘时，它可能会导致额外的 I/O 负载，但它也可以提供更均匀的硬盘负载。说明了在条带化组织中，存储单元分配的顺序。

图 2. 条带化组织

3. 数据完整性

硬盘的最终问题是它们不可靠。尽管近年来硬盘的可靠性大大提高，但硬盘仍然是服务器中最容易发生故障的核心组件。待发生故障，后果可能是灾难性的，更换故障的硬盘并恢复数据可能导致服务器停机。

解决这个问题的一种方法是镜像（mirroring），即 RAID-1，它将数据保存在不同的物理硬件上各有一份副本。对卷的任何写入操作都会同时写入两个硬盘；读取操作可以从任何一个硬盘上获取，因此如果一个硬盘发生故障，数据仍然可以从另一个硬盘上获得。

镜像有两个问题：

它需要比非冗余解决方案多一倍的磁盘存储空间。
写入操作必须同时写入两个硬盘，因此它们占用了比非镜像卷多一倍的带宽。读取操作不受性能影响，甚至可能更快。

另一种解决方案是 奇偶校验（parity），它在 RAID 2、3、4 和 5 等级中得到了实现。其中，RAID-5 是最有趣的。在 vinum 中，它是条带化组织的一种变体，其中每个条带中的一个块用于存储其他块的奇偶校验块。vinum 中实现的 RAID-5 结构类似于条带化结构，只不过它通过在每个条带中包含一个奇偶校验块来实现 RAID-5。根据 RAID-5 的要求，这个奇偶校验块的位置从一个条带到下一个条带不断变化。数据块中的数字表示相对块号。

图 3. RAID-5 组织结构

与镜像相比，RAID-5 的优势在于它显著减少了存储空间的需求。读取访问与条带化组织类似，但写入访问明显更慢，约为读取性能的 25%。如果一个硬盘发生故障，阵列仍然可以在降级模式下运行，剩余可访问硬盘中的读取操作仍然正常进行，而故障硬盘的读取则会通过从其他剩余硬盘的相应块重新计算得到。

4. vinum 对象

为了解决这些问题，vinum 实现了一个四级层次结构的对象体系：

最显著的对象是虚拟磁盘，称为卷（volume）。卷本质上与 UNIX® 磁盘驱动器具有相同的属性，尽管有一些小的区别。例如，卷没有大小限制。
卷由 plex 组成，每个 plex 表示一个卷的整个地址空间。这个层次结构提供了冗余。可以把 plex 看作是镜像阵列中的单个硬盘，每个硬盘都包含相同的数据。
由于 vinum 存在于 UNIX® 磁盘存储框架中，因此可以使用 UNIX® 分区作为构建多磁盘 plex 的基础块。事实上，这样做太不灵活，因为 UNIX® 磁盘只能有有限数量的分区。因此，vinum 将单个 UNIX® 分区（称为 驱动器）划分为连续区域，这些区域称为 子磁盘（subdisk），并将它们作为构建 plex 的基础块。

以下部分介绍了这些对象如何提供 vinum 所需的功能。

4.1. 卷大小考虑

Plex 可以包含多个子磁盘，这些子磁盘分布在 vinum 配置中的所有驱动器上。因此，单个驱动器的大小不会限制 plex 或卷的大小。

4.2. 冗余数据存储

vinum 通过将多个 plex 附加到一个卷来实现镜像。每个 plex 表示卷中的数据。一个卷可以包含从一个到八个 plex。

虽然一个 plex 代表一个卷的完整数据，但某些表示部分可能会物理缺失，可能是有意的（通过不为 plex 的某些部分定义子磁盘）或偶然的（由于驱动器故障）。只要至少一个 plex 能提供卷完整地址范围的数据，卷就能正常工作。

4.3. 选择哪种 Plex 组织方式？

vinum 在 plex 层次上实现了连接和条带化：

连接 plex 使用每个子磁盘的地址空间。连接的 plex 是最灵活的，因为它们可以包含任意数量的子磁盘，且子磁盘的长度可以不同。通过添加额外的子磁盘，可以扩展 plex。与条带化 plex 相比，它们所需的 CPU 时间较少，尽管 CPU 开销的差异不可测量。另一方面，连接的 plex 更容易出现热点，其中一个硬盘非常活跃，而其他硬盘处于空闲状态。
条带化 plex 将数据条带化存储在每个子磁盘上。所有子磁盘必须具有相同的大小，且必须至少有两个子磁盘，以将其与连接 plex 区分开来。条带化 plex 的最大优势是它们减少了热点问题。通过选择最佳大小的条带（大约 256 kB），可以平衡各个组件驱动器的负载。通过添加新的子磁盘扩展 plex 是非常复杂的，vinum 没有实现这种扩展。

总结了每种 plex 组织方式的优缺点。

表 1. vinum Plex 组织方式

Plex 类型

最小子磁盘数

可添加子磁盘数

必须相等的大小

应用场景

5. 一些示例

vinum 维护一个 配置数据库，介绍了系统中已知的对象。用户最初通过一个或多个配置文件使用创建配置数据库。vinum 在每个受其控制的硬盘设备上存储其配置数据库的副本。该数据库在每次状态变化时更新，以便在重启时准确恢复每个 vinum 对象的状态。

5.1. 配置文件

配置文件介绍了单个 vinum 对象。一个简单卷的定义可能如下所示：

这个文件介绍了四个 vinum 对象：

drive 行介绍了一个磁盘分区（驱动器）及其相对于底层硬件的位置。它被赋予符号名称 a。这种将符号名称与设备名称分开的方法允许磁盘在不同位置之间移动而不会产生混淆。
volume 行介绍了一个卷。唯一需要的属性是名称，这里是 myvol。
plex 行定义了一个 plex。唯一必需的参数是组织方式，这里是 concat。不需要名称，因为系统会通过添加后缀 .px 自动生成名称，其中 x 是该卷中 plex 的编号。因此，这个 plex 将被命名为 myvol.p0。

在处理完该文件后，会产生以下输出：

此输出显示了的简要列出格式。图形化表示见于。

图 4. 简单的 vinum 卷

该图以及随后出现的图形表示了一个卷，其中包含 plex，而 plex 又包含子磁盘。在这个例子中，卷包含一个 plex，而该 plex 包含一个子磁盘。

这个特定的卷与常规磁盘分区没有特别的优势。它包含一个单一的 plex，因此没有冗余。该 plex 包含一个子磁盘，因此与常规磁盘分区在存储分配上没有区别。接下来的部分将展示更有趣的配置方法。

5.2. 增加弹性：镜像

可以通过镜像来增加卷的弹性。在布置一个镜像卷时，重要的是要确保每个 plex 的子磁盘位于不同的驱动器上，这样才能避免驱动器故障同时影响两个 plex。以下配置展示了一个镜像卷：

在这个例子中，无需再次定义驱动器 a，因为 vinum 会在其配置数据库中跟踪所有对象。处理完这个定义后，配置变成了：

以图形化方式展示了结构。

图 5. 一个镜像的 vinum 卷

在这个例子中，每个 plex 包含完整的 512 MB 地址空间。如同之前的例子，每个 plex 只包含一个子磁盘。

5.3. 优化性能

前面例子中的镜像卷比未镜像的卷更能抵抗故障，但其性能较差，因为每次对卷的写入都需要同时写入到两个驱动器，占用了更大比例的磁盘带宽。性能考量需要另一种方法：不使用镜像，而是将数据条带化分布到尽可能多的磁盘驱动器上。以下配置展示了一个条带化卷，plex 被条带化到四个磁盘驱动器上：

如之前一样，无需定义已经为 vinum 所知的驱动器。处理完这个定义后，配置变成了：

图 6. 条带化的 vinum 卷

此卷在中进行了表示。条带的深浅表示在 plex 地址空间中的位置，最浅的条带在前，最深的条带在后。

5.4. 韧性与性能

借助足够的硬件，可以构建出相较于标准 UNIX® 分区具有更高韧性和性能的卷。一个典型的配置文件可能如下所示：

第二个 plex 的子磁盘与第一个 plex 的子磁盘错开了两个驱动器。这有助于确保写入操作不会写入到相同的子磁盘，即使传输跨越了两个驱动器。

表示该卷的结构。

图 7. 一个镜像条带化的 vinum 卷

6. 对象命名

vinum 为 plex 和子磁盘分配默认名称，尽管可以覆盖这些名称。我们不建议覆盖默认名称，因为这样做不会带来显著的优势，且可能导致混淆。

名称可以包含任何非空白字符，但建议仅限字母、数字和下划线字符。卷、plex 和子磁盘的名称最长可达 64 个字符，驱动器的名称最长可达 32 个字符。

vinum 对象在 /dev/gvinum 层次结构中分配设备节点。上面的配置将导致 vinum 创建以下设备节点：

每个卷的设备条目。这些是 vinum 使用的主要设备。上述配置会包括设备 /dev/gvinum/myvol、/dev/gvinum/mirror、/dev/gvinum/striped、/dev/gvinum/raid5 和 /dev/gvinum/raid10。
所有卷都会在 /dev/gvinum/ 下获得直接条目。
目录 /dev/gvinum/plex 和 /dev/gvinum/sd，分别包含每个 plex 和每个子磁盘的设备节点。

例如，考虑以下配置文件：

处理此文件后，会在 /dev/gvinum 中创建以下结构：

尽管建议不要为 plex 和子磁盘分配特定名称，但 vinum 驱动器必须命名。这使得在将驱动器移动到不同位置时，仍然可以自动识别它。驱动器名称最长可达 32 个字符。

6.1. 创建文件系统

卷对系统的表现与磁盘相同，唯一的例外是，vinum 不对卷进行分区，因此卷中没有分区表。这要求对一些磁盘工具进行修改，特别是，以防它尝试将 vinum 卷名的最后一个字母解释为分区标识符。例如，磁盘驱动器的名称可能是 /dev/ad0a 或 /dev/da2h。这些名称分别表示第一个（0）IDE 磁盘（ad）上的第一个分区（a）和第三个（2）SCSI 磁盘（da）上的第八个分区（h）。相比之下，vinum 卷可能被称为 /dev/gvinum/concat，它与分区名称没有任何关系。

要在此卷上创建文件系统，请使用：

7. 配置 vinum

GENERIC 内核不包含 vinum。可以构建一个包含 vinum 的自定义内核，但不推荐这样做。启动 vinum 的标准方法是将其作为内核模块加载。因为启动时会检查模块是否已加载，如果没有，它会自动加载模块，所以不需要使用。

7.1. 启动

vinum 将配置信息存储在磁盘切片中，形式与配置文件基本相同。当从配置数据库读取时，vinum 会识别一些在配置文件中不允许使用的关键字。例如，磁盘配置可能包含以下文本：

显而易见的区别是位置和命名信息的存在，这些信息是允许但不推荐的，以及状态信息。vinum 不存储关于驱动器的任何信息，它通过扫描配置的磁盘驱动器来查找具有 vinum 标签的分区。这使得 vinum 能够正确识别驱动器，即使它们被分配了不同的 UNIX® 驱动器 ID。

7.1.1. 自动启动

Gvinum 总是能够在内核模块加载后通过实现自动启动。要在启动时加载 Gvinum 模块，请将 geom_vinum_load="YES" 添加到 /boot/loader.conf。

当 vinum 使用 gvinum start 启动时，vinum 会从某个 vinum 驱动器读取配置数据库。在正常情况下，每个驱动器包含配置数据库的副本，因此读取哪个驱动器并不重要。然而，在崩溃之后，vinum 必须确定哪个驱动器是最新更新的，并从该驱动器读取配置。然后，它会根据需要从逐渐较旧的驱动器更新配置。

8. 使用 vinum 作为根文件系统

对于具有完全镜像文件系统的机器，使用 vinum 作为根文件系统也是理想的。设置这种配置比镜像一个任意文件系统要复杂一些，因为：

根文件系统必须在引导过程中很早就可用，因此 vinum 基础设施必须在此时已经可用。
包含根文件系统的卷还包含系统引导程序和内核。这些必须使用主机系统的本地工具（如 BIOS）读取，而这些工具通常无法了解 vinum 的细节。

在以下章节中，术语“根卷”通常用来描述包含根文件系统的 vinum 卷。

8.1. 让 vinum 在启动时足够早地加载以支持根文件系统

为了确保 vinum 在系统启动时能被加载，必须让能够在启动内核之前加载 vinum 内核模块。可以通过在 /boot/loader.conf 文件中加入以下行来实现：

8.2. 使基于 vinum 的根卷对引导程序可访问

当前的 FreeBSD 引导程序只有 7.5 KB 的代码，并且不能理解 vinum 的内部结构。这意味着它无法解析 vinum 配置数据，也无法识别启动卷的元素。因此，需要一些解决方法来为引导程序提供一个标准 a 分区的假象，该分区包含根文件系统。

为了使这种情况成为可能，根卷必须满足以下要求：

根卷不能是条带化（stripe）或 RAID-5 类型。
根卷的每个 plex 中不能包含超过一个连接子磁盘（concatenated subdisk）。

需要注意的是，使用多个 plex 每个包含一个根文件系统的副本是可行的，并且是期望的。引导程序过程将只使用一个副本来查找引导程序和所有启动文件，直到内核挂载根文件系统为止。这些 plex 中的每个单独的子磁盘需要其自己的 a 分区假象，以便相应的设备可以引导系统。严格来说，这些伪造的 a 分区不必位于每个设备中的相同偏移量，但为了避免混淆，最好按这种方式创建 vinum 卷，使结果镜像设备是对称的。

为了为每个包含根卷部分的设备设置这些 a 分区，需要执行以下步骤：

使用以下命令检查该设备的根卷子磁盘的位置、偏移量以及大小：
vinum 的偏移量和大小是以字节为单位的。必须将这些值除以 512，以获得要用于 bsdlabel 的块号。
对参与根卷的每个设备运行以下命令：
devname 必须是磁盘的名称，例如没有切片表的磁盘的名称 da0，或切片名称，例如 ad0s1。
如果设备上已经存在一个 a

请记住，所有包含控制信息的文件都必须相对于根文件系统，这个根文件系统在 vinum 卷中，在设置新的 vinum 根卷时，可能与当前活动的根文件系统不匹配。因此，必须特别小心处理 /etc/fstab 和 /boot/loader.conf 文件。

在下次重启时，引导程序应该能够从新的基于 vinum 的根文件系统获取相应的控制信息，并相应地进行操作。内核初始化过程结束时，在所有设备都已声明之后，显示的成功消息应该类似于：

8.3. 基于 vinum 的根文件系统示例

在设置好 vinum 根卷之后，运行 gvinum l -rv root 的输出可能如下所示：

需要注意的值是 135680，即相对于分区 /dev/da0h 的偏移量。这在 bsdlabel 中等同于 265 个 512 字节的磁盘块。类似地，根卷的大小是 245760 个 512 字节的块。包含第二个副本的 /dev/da1h 设备有对称的设置。

这些设备的 bsdlabel 可能如下所示：

可以观察到，伪造的 a 分区的 size 参数与上面计算出的值相匹配，而 offset 参数是 vinum 分区 h 内的偏移量与该分区在设备或切片中的偏移量之和。这是避免中描述的问题的典型设置。整个 a 分区完全位于包含所有 vinum 数据的 h 分区内。

在上面的示例中，整个设备专门用于 vinum，并且没有剩余的预 vinum 根分区。

8.4. 故障排除

以下是一些已知的常见问题和解决方法。

8.4.1. 系统引导加载，但系统无法启动

如果由于某种原因系统无法继续启动，可以通过在 10 秒警告时按下空格键来中断引导程序。可以通过输入 show 来检查引导程序变量 vinum.autostart，并使用 set 或 unset 进行修改。

如果 vinum 内核模块尚未列在自动加载的模块列表中，可以输入 load geom_vinum 来加载它。

加载完成后，可以输入 boot -as 继续启动过程，-as 参数请求内核询问要挂载的根文件系统（-a），并使启动过程在单用户模式下停止（-s），此时根文件系统以只读方式挂载。这样，即使只有一个 plex 的多 plex 卷被挂载，也不会导致 plex 之间的数据不一致。

在提示输入根文件系统时，可以输入任何包含有效根文件系统的设备。如果 /etc/fstab 配置正确，默认值应该类似于 ufs:/dev/gvinum/root。一个典型的替代选择可能是 ufs:da0d，它可能是包含预 vinum 根文件系统的假设分区。如果此处输入的是某个别名 a 分区，必须确保它实际引用的是 vinum 根设备的子磁盘，因为在镜像设置中，这只会挂载一个镜像根设备的一部分。如果此文件系统以后要以读写方式挂载，则需要移除其他 plex，因为这些 plex 会携带不一致的数据。

8.4.2. 只加载了主引导程序

如果 /boot/loader 无法加载，但主引导程序仍然加载（在启动过程开始后屏幕的左列可见一个破折号），可以尝试通过按空格键中断主引导程序。这样可以使引导程序停在进行操作。在此阶段，可以尝试从备用分区启动，例如包含先前根文件系统的分区。

8.4.3. 什么也没启动，引导程序崩溃

如果引导程序在 vinum 安装后被破坏，就会发生这种情况。不幸的是，vinum 会在其分区的开始处意外地留下 4 KB 的空闲空间，然后才开始写入 vinum 头信息。然而，第一阶段和第二阶段的引导程序以及 bsdlabel 需要 8 KB。因此，如果 vinum 分区从 0 偏移量开始，且该分区位于一个本应可启动的切片或磁盘中，vinum 设置将破坏引导程序。

同样，如果通过从 "Fixit" 媒体启动并使用 bsdlabel -B 重新安装引导程序来恢复上述情况，重新安装的引导程序会破坏 vinum 头，导致 vinum 无法找到其磁盘。尽管实际的 vinum 配置数据和 vinum 卷中的数据不会被破坏，并且可以通过重新输入相同的 vinum 配置数据来恢复所有数据，但这种情况很难修复。需要将整个 vinum 分区移动至少 4 KB，以避免 vinum 头和系统引导程序的冲突。

BSD 中的实用 rc.d 脚本编程

原文：Practical rc.d scripting in BSD

摘要

初学者可能会觉得很难将来自正式文档中关于 BSD rc.d 框架的事实与实际的 rc.d 脚本任务联系起来。本文将考虑几个典型的、逐渐复杂的案例，展示适用于每个案例的 rc.d 特性，并讨论它们如何工作。这样的探讨应该为进一步研究 rc.d 的设计和高效应用提供参考点。

1. 引言

历史上的 BSD 系统有一个单一的启动脚本 /etc/rc。它在系统启动时由调用，并执行所有多用户操作所需的用户空间任务：检查和挂载文件系统、设置网络、启动守护进程等。具体的任务列表在不同的系统中有所不同；管理员需要根据需要进行定制。除少数例外，/etc/rc 必须进行修改，真正的黑客对此感到满意。

单一脚本方法的真正问题在于，它无法控制从 /etc/rc 启动的各个组件。例如，/etc/rc 无法重新启动单个守护进程。系统管理员必须手动找到守护进程，终止它，等待它实际退出，然后浏览 /etc/rc 查找标志，最后输入完整的命令行来重新启动守护进程。如果要重新启动的服务包含多个守护进程或需要其他操作，这项任务会变得更加困难且容易出错。简而言之，单一脚本未能实现脚本的基本目的：使系统管理员的工作更轻松。

后来，为了单独启动最重要的子系统，曾试图将一些 /etc/rc 的部分内容拆分出来。著名的例子是 /etc/netstart 用于启动网络。它确实允许从单用户模式访问网络，但由于其代码的一些部分需要与本质上与网络无关的操作交织在一起，因此未能很好地融入自动启动过程。这就是为什么 /etc/netstart 最终变成了 /etc/rc.network 的原因。后者不再是一个普通的脚本；它由大型、复杂的函数组成，这些函数在系统启动的不同阶段由 /etc/rc 调用。然而，随着启动任务的多样化和复杂化，这种“准模块化”方法变得比单一的 /etc/rc 更加繁琐。

在没有干净且设计良好的框架的情况下，启动脚本不得不竭尽全力满足快速发展的基于 BSD 的操作系统的需求。最终，越来越明显的是，要实现一个细粒度且可扩展的 rc 系统，还需要更多的步骤。于是，BSD rc.d 应运而生。它的公认创始人是 Luke Mewburn 和 NetBSD 社区。后来它被引入到 FreeBSD。它的名称来源于系统脚本的位置，这些脚本用于单独的服务，位于 /etc/rc.d。很快我们将了解 rc.d 系统的更多组件，并查看如何调用单个脚本。

BSD rc.d 背后的基本思想是 细粒度模块化 和 代码重用。细粒度模块化 意味着每个基本的“服务”如系统守护进程或基本启动任务都有自己的脚本，能够启动服务、停止它、重新加载它、检查其状态。特定的操作通过脚本的命令行参数来选择。/etc/rc 脚本仍然负责系统启动，但它现在只是依次调用这些小脚本，并传递 start 参数。通过用 stop 参数运行同一组脚本，执行关闭任务变得也很容易，这由 /etc/rc.shutdown 完成。请注意，这与 Unix 系统的方式非常接近，Unix 系统有一组小型的专用工具，每个工具尽可能地完成其任务。代码重用 意味着常见操作通过函数实现，并集中在 /etc/rc.subr 中。现在，典型的脚本可能只是几行代码。最后，rc.d 框架的一个重要部分是，它帮助 /etc/rc 按照它们之间的依赖关系有序地运行这些小脚本。它也可以帮助 /etc/rc.shutdown，因为关闭顺序的正确顺序与启动顺序相反。

BSD rc.d 的设计在中有所描述，rc.d 组件在中得到了详细的文档说明。然而，对于一个 rc.d 新手来说，如何将众多的片段和组件结合起来，创建一个风格良好的特定任务脚本，可能并不显而易见。因此，本文将采用一种不同的方法来描述 rc.d。它将展示在一些典型情况下应该使用哪些特性，以及为什么。请注意，这不是一份操作指南，因为我们的目标不是提供现成的配方，而是展示一些进入 rc.d 领域的简单入口。这篇文章也不是相关手册页的替代品。在阅读本文时，遇到需要正式和完整文档的部分，应该随时参考手册页。

理解本文有一些前提条件。首先，你应该熟悉脚本语言，以掌握 rc.d。此外，你应该了解系统如何执行用户空间的启动和关闭任务，这在中有所描述。

本文侧重于 FreeBSD 分支的 rc.d。尽管如此，它对于 NetBSD 开发人员也可能有用，因为两个 BSD rc.d 分支不仅共享相同的设计，而且在脚本作者可见的方面也保持相似。

2. 概述任务

在开始编辑 $EDITOR 之前，稍作思考不会有坏处。为了编写一个调和良好的 rc.d 脚本来管理系统服务，我们应该首先能够回答以下问题：

这个服务是必须的还是可选的？
脚本是为单个程序（例如守护进程）服务，还是执行更复杂的操作？
我们的服务依赖于哪些其他服务，反之亦然？

从以下的示例中，我们将看到为什么了解这些问题的答案如此重要。

3. 示范脚本

下面的脚本在系统每次启动时都会发出一条消息：

需要注意的事项如下：

① 一个解释型脚本应该以魔法的“shebang”行开始。该行指定脚本的解释器程序。由于 shebang 行，脚本可以像二进制程序一样被调用，只要设置了执行位。例如，系统管理员可以从命令行手动运行我们的脚本：

注意
为了被 rc.d 框架正确管理，脚本需要使用语言编写。如果你有一个服务或 Port 使用二进制控制工具或用其他语言编写的启动例程，可以将该元素安装到 /usr/sbin（用于系统）或 /usr/local/sbin（用于 Port），并从相应的 rc.d 目录中的脚本中调用它。

技巧
如果你想了解为什么 rc.d 脚本必须用语言编写的详细原因，请查看 /etc/rc 如何通过 run_rc_script 调用它们，然后研究 /etc/rc.subr 中 run_rc_script 的实现。

② 在 /etc/rc.subr 中定义了多个供 rc.d 脚本使用的函数。这些函数在中有文档说明。虽然理论上可以编写不使用的 rc.d 脚本，但它的函数非常方便，使工作变得容易得多。所以，毫不奇怪，大家都在 rc.d 脚本中使用，我们也不例外。

一个 rc.d 脚本必须在调用函数之前“source”/etc/rc.subr（通过“.”包含它），以便可以了解这些函数。推荐的写法是首先包含 /etc/rc.subr。

注意
有关网络的某些有用函数由另一个包含文件 /etc/network.subr 提供。

③ 必须变量 name 指定了我们脚本的名称。它是所要求的。也就是说，每个 rc.d 脚本必须在调用函数之前设置 name。

现在是时候为我们的脚本选择一个唯一的名称了。我们将会在编写脚本的多个地方使用它。name 变量的内容需要与脚本名称匹配，FreeBSD 的某些部分（例如和 rc 框架的 cpuset 功能）依赖于此。因此，文件名也不能包含可能在脚本中引起问题的字符（例如，不要使用连字符“-”等）。

注意
当前的 rc.d 脚本风格是将分配给变量的值用双引号括起来。请记住，这仅仅是一个风格问题，可能并非总是适用。你可以安全地省略不包含元字符的简单词语周围的引号，而在某些情况下你需要使用单引号来防止对值的解释。程序员应能根据语言语法和风格约定来区分并合理使用两者。

④ 的主要思想是，rc.d 脚本提供处理程序或方法，以供调用。特别是，start、stop 和 rc.d 脚本的其他参数就是通过这种方式处理的。方法是一个存储在名为 argument_cmd 的变量中的表达式，其中 argument 对应于脚本命令行中可以指定的内容。稍后我们将看到为标准参数提供了默认的方法。

注意
为了使 rc.d 代码更统一，通常在适当的地方使用 ${name}。这样，许多行可以直接从一个脚本复制到另一个脚本。

⑤ 我们应该记住，提供了标准参数的默认方法。因此，如果我们希望某个标准方法什么也不做，我们必须使用一个无操作的表达式来重载该方法。

⑥ 一个复杂方法的主体可以作为函数来实现。为函数命名时最好有意义。

重要
强烈建议为脚本中定义的所有函数添加 ${name} 前缀，这样它们就不会与或其他公共包含文件中的函数冲突。

⑦ 这行调用加载变量。我们的脚本目前尚未使用这些变量，但仍然建议加载，因为可能有控制本身的变量。

⑧ 通常这是 rc.d 脚本中的最后一条命令。它调用的机制，根据我们提供的变量和方法执行请求的操作。

4. 可配置的虚拟脚本

现在让我们为我们的虚拟脚本添加一些控制选项。如你所知，rc.d 脚本通过来进行控制。幸运的是，隐藏了所有复杂性。下面的脚本使用通过来检查它是否启用，并在启动时显示一条消息。这两个任务实际上是独立的。一方面，rc.d 脚本可以只支持启用和禁用它的服务。另一方面，强制性的 rc.d 脚本可以有配置变量。尽管如此，我们会在同一个脚本中做这两件事：

在这个例子中有什么变化呢？

① 变量 rcvar 指定了 ON/OFF 开关变量的名称。

② 现在 load_rc_config 在脚本中较早地被调用，在访问任何变量之前。

注意
在检查 rc.d 脚本时，请记住会推迟评估函数中的表达式，直到函数被调用。因此，在脚本中很晚才调用 load_rc_config 并且仍然能够访问变量，是没有问题的，因为方法函数是在 load_rc_config 调用之后由 run_rc_command 调用的。

③ 如果 rcvar 本身已设置，但所指示的开关变量未设置，run_rc_command 将发出警告。如果你的 rc.d 脚本是系统自带的，你应当将开关变量的默认设置添加到 /etc/defaults/rc.conf 中，并在中进行文档说明。否则，应该由你的脚本提供开关的默认设置。后者的标准方法如本例所示。

注意
你可以通过在脚本的参数前加上 one 或 force，使认为开关已设置为 ON，不管其当前设置如何，例如：onestart 或 forcestop。不过，请记住，force 会有其他危险影响，稍后会讨论，而 one 只是覆盖了开关。假设 dummy_enable 为 OFF，那么下面的命令将强制执行 start

④ 现在，启动时显示的消息不再硬编码在脚本中。它由一个名为 dummy_msg 的变量指定。这是一个简单的例子，展示了如何通过变量来控制 rc.d 脚本。

重要
所有仅由我们的脚本使用的变量的名称必须具有相同的前缀：${name}_。例如：dummy_mode、dummy_state_file 等等。

注意
尽管可以在内部使用更短的名称，例如仅使用 msg，但将唯一的前缀 ${name}_ 添加到脚本引入的所有全局名称，将帮助避免与命名空间发生冲突。作为规则，基础系统中的 rc.d 脚本无需为它们的变量提供默认值，因为默认值应该在 /etc/defaults/rc.conf 中设置。另一方面，rc.d 脚本对于 Port 则应提供像示例中那样的默认值。

⑤ 现在我们使用 dummy_msg 来控制脚本，即显示一个变量消息。这里使用 shell 函数是多余的，因为它只运行一条命令；一个同样有效的替代方法是：

5. 简单守护进程的启动与关闭

我们之前提到过，可以提供默认方法。显然，这些默认方法不能过于通用，它们适用于启动和关闭一个简单的守护进程。现在假设我们需要为一个名为 mumbled 的守护进程编写 rc.d 脚本。下面是该脚本：

这个脚本看起来简单而又简洁，不是吗？让我们分析一下这个小脚本。唯一需要注意的新事物是：

① command 变量对于是有意义的。如果它被设置，将根据提供的默认方法来启动和关闭守护进程。特别地，默认方法会为以下命令提供支持：start、stop、restart、poll 和 status。

守护进程将通过运行 $command 并使用 $mumbled_flags 指定的命令行标志来启动。因此，默认 start 方法的所有输入数据都可以通过我们脚本中设置的变量获得。与 start 方法不同，其他方法可能需要有关已启动进程的附加信息。例如，stop 方法必须知道要终止的进程的 PID。在这种情况下，会扫描所有进程列表，寻找名称为 procname 的进程。后者是另一个对有意义的变量，默认情况下其值与 command 相同。换句话说，当我们设置 command 时，procname 会自动设置为相同的值。这使得我们的脚本能够终止守护进程，并首先检查它是否正在运行。

注意
有些程序实际上是可执行脚本。系统通过启动其解释器并将脚本的名称作为命令行参数传递给它来运行此类脚本。这会反映在进程列表中，可能会让感到困惑。如果 $command 是一个脚本，应该额外设置 command_interpreter 变量，以便知道实际的进程名称。
对于每个 rc.d 脚本，都有一个可选的变量，它优先于 command。该变量的名称按照以下规则构造：${name}_program，其中 name 是我们之前讨论的必需变量。例如，在此案例中，它将是 mumbled_program。是负责让 ${name}_program 重写 command

有关默认方法的更多详细信息，请参阅。

6. 启动和关闭一个高级守护进程

让我们为之前的脚本增加一些内容，使其变得更加复杂和功能丰富。默认方法对我们来说已经足够好，但有时我们可能需要调整它们的一些方面。现在我们将学习如何根据我们的需求来调整默认方法。

① 除了 $command 外，还可以通过 command_args 传递额外的参数。这些参数将添加到 $mumbled_flags 后面。由于最终的命令行会通过 eval 执行，因此可以在 command_args 中指定输入输出重定向。

注意
永远不要 在 command_args 中包含以破折号开头的选项，如 -X 或 --foo。command_args 的内容会出现在最终命令行的末尾，因此它们可能会跟在 ${name}_flags 中的参数后面，而大多数命令在普通参数后不会识别这些带破折号的选项。传递额外的选项给 $command 的更好方法是将它们放在 ${name}_flags 的前面，或者修改 rc_flags 。

② 一个良好设计的守护进程应该创建一个 pidfile，这样可以更容易且更可靠地找到它的进程。设置 pidfile 变量后，会在默认方法中使用该 pidfile。

注意
实际上，还会使用 pidfile 检查守护进程是否已在运行。若要跳过此检查，可以使用 faststart 参数。

③ 如果守护进程必须在启动前确保某些文件存在，可以将这些文件列在 required_files 中，会在启动守护进程之前检查这些文件是否存在。此外，还有 required_dirs 和 required_vars 用于检查目录和环境变量，具体内容请查阅。

注意
可以通过在命令行中使用 forcestart 参数来强制跳过这些前置检查。

④ 如果守护进程需要的信号与默认的不同，我们可以自定义信号。例如，sig_reload 指定了用于重新加载守护进程配置的信号，默认是 SIGHUP。另一个信号是用于停止守护进程的，默认是 SIGTERM，但也可以通过设置 sig_stop 来改变它。

注意
信号名称应当不带 SIG 前缀，正如示例中所示。FreeBSD 版本的可以识别 SIG 前缀，但其他操作系统版本可能不识别。

⑤⑥ 在默认方法之前或之后执行额外的任务很简单。对于脚本支持的每个命令参数，我们可以定义 argument_precmd 和 argument_postcmd，这些命令将在相应方法的前后执行，名称也非常直观。

注意
即使我们重写了默认方法并定义了自定义的 argument_cmd，也可以使用 argument_precmd 或 argument_postcmd。特别地，前者非常适合用来检查自定义的复杂条件，只有在条件满足时才执行命令本身。结合使用 argument_precmd 和 argument_cmd 可以将检查与动作逻辑上分开。
在方法、前后命令中，你可以放入任何有效的表达式。虽然调用一个实现实际工作的函数是大多数情况下的好风格，但不要让风格限制你对其背后原理的理解。

⑦ 如果我们想实现自定义的命令（也可以称为命令），只需将它们列在 extra_commands 中，并提供相应的处理方法。

注意
reload 命令是特殊的。一方面，它在中有预设的方法。另一方面，reload 默认是不会提供的。原因是并不是所有守护进程都使用相同的重新加载机制，有些甚至根本不需要重新加载。因此我们需要显式要求提供内建的功能，可以通过 extra_commands 来实现。
默认的 reload 方法做了什么呢？通常情况下，守护进程会在接收到某个信号后重新加载其配置——通常是 SIGHUP。因此，会尝试通过向守护进程发送信号来重新加载它。默认信号是 SIGHUP，但可以通过 sig_reload 来进行定制。

⑧⑭ 我们的脚本支持两个非标准命令，plugh 和 xyzzy。它们在 extra_commands 中列出，现在是时候为它们提供方法了。xyzzy 的方法就是内联定义的，而 plugh 则由 mumbled_plugh 函数实现。

非标准命令在启动或关闭时不会被调用。它们通常是为了系统管理员的便利而设，也可以从其他子系统调用，例如在中通过指定。

完整的可用命令列表可以在脚本没有参数时通过打印的使用行中找到。例如，这是我们正在研究的脚本中的使用行：

⑬ 脚本可以根据需要调用它自己的标准或非标准命令。这看起来像是调用函数，但我们知道命令和 shell 函数并不总是相同的。例如，xyzzy 在这里不是作为函数实现的。此外，还可以有前命令和后命令，它们应该按顺序执行。因此，脚本运行自己的命令的正确方法是通过，如示例所示。

⑨ 有个非常方便的函数 checkyesno 是提供的。它以变量名作为参数，只有当变量的值为 YES、TRUE、ON 或 1（不区分大小写）时，返回零退出码；否则返回非零退出码。如果变量包含其他值，即无效的值，它会打印一条警告信息。

记住，在中，零退出码意味着真，非零退出码意味着假。

重要
checkyesno 函数接受的是 变量名。不要将变量的展开值传给它；那样不会按预期工作。
下面是 checkyesno 的正确用法：
相反，如下所示调用 checkyesno 将不起作用 —— 至少不会按预期工作：

⑩ 我们可以通过在 $start_precmd 中修改 rc_flags 来影响传递给 $command 的参数。

⑪ 在某些情况下，我们可能需要发出一条重要信息，并同时将其写入 syslog。这可以通过以下提供的函数轻松实现：debug、info、warn 和 err。其中，err 函数在输出信息后会以指定的状态码退出脚本。

⑫ 方法及其 pre-command 返回的退出码默认不会被忽略。如果 argument_precmd 返回一个非零的退出码，则主方法将不会被执行。反过来，除非主方法返回零退出码，argument_postcmd 也不会被调用。

注意
不过，可以通过在命令行参数前加上 force，如 forcestart，来指示 [rc.subr(8)] 忽略这些退出码并无论如何执行所有命令。

7. 将脚本接入 rc.d 框架

写好脚本之后，就需要将它整合进 rc.d。关键的一步是将脚本安装到 /etc/rc.d（用于基础系统）或 /usr/local/etc/rc.d（用于 Port）。bsd.prog.mk 和 bsd.port.mk 都提供了方便的安装钩子，通常无需担心文件的所有权和权限。系统脚本应通过 src/libexec/rc/rc.d 下的 Makefile 进行安装；Port 的脚本则可以使用 USE_RC_SUBR 来安装，具体做法见。

不过，在此之前，我们应该先考虑脚本在系统启动序列中的位置。脚本所管理的服务很可能依赖于其他服务。例如，一个网络守护进程在网络接口和路由尚未启动之前是无法工作的。即使某个服务看似不依赖其他内容，它也不可能在基本文件系统被检查和挂载之前启动。

我们之前提到过。现在是时候仔细了解一下它了。简而言之，[rcorder(8)] 会读取一组文件，分析其内容，然后按依赖顺序将这些文件输出到 stdout。关键点在于将依赖信息保存在文件内部，让每个文件只描述自身。一个文件可以指定以下信息：

它所提供的“条件”（即我们所说的服务）；
它所需要的“条件”；
它应该在其前运行的“条件”；
额外的

不出意外，[rcorder(8)] 只能处理语法类似的文本文件。也就是说，[rcorder(8)] 所能识别的特殊行看起来像 [sh(1)] 的注释。这些特殊行的语法相当严格，以便于程序处理。详见 [rcorder(8)]。

除了使用 [rcorder(8)] 的特殊行之外，一个脚本还可以通过强制启动另一个服务来表达其依赖关系。这在所依赖服务是可选的情况下尤其有用——如果系统管理员在中禁用了该服务，它本不会自动启动。

了解了以上这些基础知识之后，我们来看一个添加了依赖信息的简单守护进程脚本示例：

如前所述，接下来是详细分析：

① 这一行声明了我们的脚本所提供的“条件”名称。现在其他脚本就可以通过这些名称来记录对我们脚本的依赖关系。

注意
通常，一个脚本只会声明一个所提供的条件。不过，并没有什么限制我们在此列出多个条件，例如为了兼容性原因。
无论如何，主要的（或唯一的）PROVIDE: 条件名称应当与 ${name} 相同。

②③ 所以我们的脚本表明它依赖于其他脚本所提供的哪些“条件”。根据这些行，我们的脚本要求将它排列在提供 DAEMON 和 cleanvar 的脚本之后，但在提供 LOGIN 的脚本之前。

注意
BEFORE: 行不应被滥用于绕过其他脚本中不完整的依赖列表。使用 BEFORE: 的合理情形是：另一个脚本并不关心我们的脚本是否存在，但如果我们的脚本能在它之前运行，则可以更好地完成任务。一个典型的现实示例是网络接口与防火墙：虽然接口在工作时并不依赖防火墙，但若防火墙在网络流量出现前就已就绪，系统安全性将受益。
除了每个服务对应一个条件外，还有一些元条件及其“占位符”脚本，用于确保某些操作组在其他操作组之前执行。这些元条件以 全大写字母 表示。它们的列表和用途可在中找到。
请记住，在 REQUIRE: 行中列出某个服务名称，并不能保证该服务在我们的脚本启动时一定已运行。被要求的服务可能启动失败，或者只是被系统管理员在中禁用了。显然，无法跟踪此类细节，也不会这样做。因此，我们脚本启动的应用程序应能应对任何所需服务不可用的情况。在某些情形下，我们可以像所述那样提供帮助。

④ 正如我们在上文中所了解到的，的关键字可用于选择或排除某些脚本。也就是说，任何的使用者都可以通过 -k 和 -s 选项，分别指定哪些关键字属于“保留列表”或“跳过列表”。在所有待进行依赖排序的文件中，将只挑选那些具备保留列表中的关键字（如果该列表非空），且不具备跳过列表中关键字的文件。

在 FreeBSD 中，被 /etc/rc 和 /etc/rc.shutdown 所使用。这两个脚本定义了 FreeBSD rc.d 关键字的标准列表及其含义如下：

nojail 该服务不适用于环境。如果在 jail 中，自动启动和关闭流程将忽略此脚本。

nostart 该服务应由手动启动，或根本不启动。自动启动流程将忽略此脚本。若与 shutdown 关键字同时使用，可用于编写仅在系统关机时执行操作的脚本。

shutdown 若服务需要在系统关机前被停止，必须显式列出此关键字。

注意
当系统即将关机时，/etc/rc.shutdown 会运行。它假设大多数 rc.d 脚本在那时没有任何操作。因此，/etc/rc.shutdown 会选择性地调用具有 shutdown 关键字的 rc.d 脚本，忽略其他脚本。为了更快的关机，/etc/rc.shutdown 会向其运行的脚本传递 faststop 命令，促使它们跳过初步检查，例如 pidfile 检查。由于依赖的服务应当在其前提条件之前停止，/etc/rc.shutdown 按反向依赖顺序运行脚本。如果编写一个真实的 rc.d 脚本，你应当考虑它在系统关机时是否相关。例如，如果你的脚本仅在接收到 start 命令时才执行工作，那么你不需要包括此关键字。然而，如果你的脚本管理一个服务，最好在系统进入最终关机阶段（如中描述的）之前停止该服务。特别是，当某个服务需要较长时间或特殊操作才能干净地关闭时，应该显式地停止它。数据库引擎就是此类服务的典型例子。

⑤ 首先，force_depend 应当谨慎使用。通常情况下，如果你的 rc.d 脚本之间有依赖关系，最好是重新审视它们的配置变量层次结构。

如果你仍然无法避免使用 force_depend，示例展示了如何有条件地调用它。在这个示例中，我们的 mumbled 守护进程要求另一个守护进程 frotz 先启动。然而，frotz 也是可选的；而并不知道这些细节。幸运的是，我们的脚本可以访问所有的变量。如果 frotz_enable 为真，我们会尽力而为，依赖 rc.d 启动 frotz。否则，我们强制检查 frotz 的状态。最后，如果发现 frotz 没有运行，我们会强制执行对 frotz 的依赖。force_depend 会发出警告信息，因为它应该只在发现配置错误时才被调用。

8. 给 rc.d 脚本提供更多灵活性

在启动或关机时调用时，rc.d 脚本应当操作其负责的整个子系统。例如，/etc/rc.d/netif 应该启动或停止由描述的所有网络接口。任何一项任务都可以通过单一的命令参数，如 start 或 stop 来唯一指示。在启动和关机之间，rc.d 脚本帮助管理员控制运行中的系统，这时就需要更多的灵活性和精确性。例如，管理员可能希望将一个新的网络接口的设置添加到中，然后启动它，而不干扰现有接口的操作。下次，管理员可能需要关闭单个网络接口。为了符合命令行精神，相应的 rc.d 脚本需要一个额外的参数，即接口名称。

幸运的是，允许将任何数量的参数传递给脚本的方法（在系统限制内）。因此，脚本本身的修改可以最小化。

那么，如何让获得额外的命令行参数呢？它是否应该直接获取这些参数？当然不行。首先，sh(1) 函数无法访问调用者的定位参数，而只是这些函数的集合。其次，rc.d 的良好习惯是由主脚本决定哪些参数传递给其方法。

因此，采用的做法如下：run_rc_command 将所有参数（除了第一个）原样传递给相应的方法。第一个被省略的参数是方法本身的名称：start、stop 等。它会被 run_rc_command 移除，因此原始命令行中的 $2 将作为 $1 传递给方法，依此类推。

为了说明这个机会，让我们修改这个原始的虚拟脚本，使得其消息依赖于传递的额外参数。我们来看一下：

我们可以注意到脚本中的哪些关键变化？

① 你在 start 后输入的所有参数都可以成为相应方法的位置参数。我们可以根据任务、技能和需要以任何方式使用它们。在当前的示例中，我们只是将所有参数作为一个字符串传递给，请注意双引号内的 $*。以下是如何调用该脚本的示例：

② 同样的方式适用于脚本提供的任何方法，而不仅仅是标准方法。我们添加了一个名为 kiss 的自定义方法，它同样可以利用额外的参数，就像 start 方法那样。例如：

③ 如果我们只想将所有额外的参数传递给某个方法，我们可以简单地在脚本的最后一行将 "$@" 替换为 "$1"，在该行调用 run_rc_command。

重要
一个程序员应当理解 $* 和 $@ 之间的微妙区别，因为它们表示所有位置参数。有关详细讨论，请参考一本好的脚本手册。*在完全理解之前不要使用这些表达式，因为它们的误用会导致脚本有漏洞并不安全。

注意
当前 run_rc_command 可能存在一个 bug，导致它无法保持参数之间的原始边界。也就是说，包含空格的参数可能无法正确处理。该 bug 源于 $* 的误用。

9. 使脚本准备好用于服务 Jail

启动长期运行服务的脚本适合用于服务 Jail，并应配有适当的服务 Jail 配置。

以下是一些不适合在服务 Jail 中运行的脚本示例：

仅在 start 命令中更改程序或内核的运行时设置的任何脚本，
尝试挂载某些内容的脚本，
查找并删除文件的脚本。

不适合在服务 Jail 中运行的脚本需要防止在服务 Jail 中使用。

如果一个脚本具有长期运行的服务，在启动或停止之前需要执行上述操作中的某些操作，则可以将其拆分为两个有依赖关系的脚本，或使用脚本的 precommand 和 postcommand 部分来执行该操作。

默认情况下，只有脚本的 start 和 stop 部分会在服务 Jail 中运行，其余部分则在 Jail 外部运行。因此，任何在 start/stop 部分中使用的设置不能通过例如 precommand 来设置。

为了使脚本准备好与一起使用，只需要插入一行配置：

① 如果脚本需要在 Jail 中运行，它必须具有可覆盖的服务 Jail 配置。如果它不需要网络访问或访问 Jail 中受限的任何其他资源，则像显示的那样使用空配置即可。

严格来说，空配置并不是必需的，但它明确介绍了该脚本已准备好用于服务 Jail，并且不需要额外的 Jail 权限。因此，在这种情况下，强烈建议添加这样的空配置。最常用的选项是 "net_basic"，它启用对主机 IPv4 和 IPv6 地址的使用。所有可能的选项在中都有解释。

如果 start/stop 设置依赖于来自 rc 框架的变量（例如，在中设置的变量），则需要通过 load_rc_config 和 run_rc_command 来处理，而不是在 precommand 中处理。

如果出于某种原因，脚本无法在服务 Jail 中运行，例如因为无法运行或在 Jail 中运行没有意义，则使用以下方法：

① 禁用操作需要在 load_rc_config 调用之后进行，否则中的设置可能会覆盖它。

10. 高级 rc 脚本：实例化

有时需要运行多个实例的服务。通常，你希望能够独立启动/停止这些实例，并且希望每个实例有一个单独的配置文件。每个实例应在启动时启动，能够在更新后存活，并受益于更新。

以下是支持此功能的 rc 脚本示例：

① 和 ② 确保将 name 变量设置为脚本文件名的。如果文件名是 /usr/local/etc/rc.d/dummy，则 name 设置为 dummy。这样，改变 rc 脚本的文件名将自动改变 name 变量的内容。

③ 指定用于 rc.conf 中启用该服务的变量名，基于此脚本的文件名。在此示例中，它解析为 dummy_enable。

④ 确保 _enable 变量的默认值为 NO。

⑤ 是为服务特定的框架变量提供一些默认值的示例，在此示例中是服务监狱选项。

⑥ 和 ⑦ 设置脚本内部的变量（注意在 _dummy_user 前的下划线，它使其与可以在 rc.conf 中设置的 dummy_user 区分开）。

⑤ 部分用于脚本内部未使用但在 rc 框架中使用的变量。所有在脚本中作为参数使用的变量都分配给一个通用变量，如⑦所示，以便更容易引用它们（不需要在每个使用位置重新评估它们）。

现在，如果启动脚本有不同的名称，此脚本将表现不同。这允许创建它的符号链接：

上述命令创建了一个名为 dummy_foo 的 dummy 服务实例。它不会使用配置文件 /usr/local/etc/dummy.cfg，而是使用配置文件 /usr/local/etc/dummy_foo.cfg（⑦），并且它使用 /var/run/dummy/dummy_foo.pid 作为 PID 文件，而不是 /var/run/dummy/dummy.pid。

dummy 和 dummy_foo 服务可以独立管理，而启动脚本会在包更新时自动更新（由于符号链接）。这不会更新 REQUIRE 行，因此没有简单的方法依赖特定的实例。为了在启动顺序中依赖特定实例，必须进行复制，而不是使用符号链接。这将防止在安装更新时自动拾取启动脚本的更改。

11. 深入阅读

提供了 rc.d 的概述，并详细阐述了其设计决策的理由。它对整个 rc.d 框架以及它在现代 BSD 操作系统中的位置提供了深刻的见解。

手册页、和详细记录了 rc.d 组件。要充分利用 rc.d 的强大功能，必须阅读这些手册页，并在编写自己的脚本时参考它们。

/etc/rc.d 中的内容是工作中的真实示例，来自一个正在运行的系统，是最主要的学习资源。其内容简单易读，因为大多数棘手问题都隐藏在中。然而请记住，/etc/rc.d 脚本并非由天使编写，因此它们可能存在缺陷和不理想的设计决策。现在，你可以改进它们！

FreeBSD 中的 Linux® 仿真

原文：Linux® emulation in FreeBSD

摘要

本篇硕士论文讨论了更新 Linux® 仿真层（即 Linuxulator）。任务是将该层更新，以匹配 Linux® 2.6 的功能。作为参考实现，选择了 Linux® 2.6.16 内核。该概念大致基于 NetBSD 实现。大部分工作在 2006 年夏季完成，作为谷歌编程之夏学生项目的一部分。重点是将 NPTL（新的 POSIX® 线程库）支持引入仿真层，包括 TLS（线程本地存储）、futexes（快速用户空间互斥锁）、PID 混淆等其他一些小问题。在这个过程中，识别并修复了许多小问题。我的工作已经被整合到 FreeBSD 的主源代码库，并将在即将发布的 7.0R 版本中发布。我们仿真开发团队，正在努力使 Linux® 2.6 仿真成为 FreeBSD 中的默认仿真层。

1. 引言

近年来，基于 UNIX® 的开源操作系统已广泛部署在服务器和客户端机器上。在这些操作系统中，我特别想提到两个：FreeBSD，它具有 BSD 传统、经过时间考验的代码库和许多有趣的特性；以及 Linux®，它具有广泛的用户基础、热情的开源开发者社区和大公司的支持。FreeBSD 通常用于服务器级机器，承担重型网络任务，在桌面类机器上的使用较少，而 Linux® 在服务器上也有相同的用途，但更多地被家庭用户使用。这导致了许多仅适用于 Linux® 的二进制程序，而 FreeBSD 缺乏对此的支持。

因此，在 FreeBSD 系统上运行 Linux® 二进制程序的需求自然产生了，而本篇论文正是探讨这一问题：在 FreeBSD 操作系统中仿真 Linux® 内核。

在 2006 年夏季，谷歌公司资助了一项项目，旨在扩展 FreeBSD 中的 Linux® 仿真层（即 Linuxulator），以包括 Linux® 2.6 的功能。本文作为该项目的一部分而编写。

2. 内部探讨……

在这一部分，我们将介绍每个相关操作系统，如何处理系统调用、陷阱帧等底层内容。我们还将概述它们如何理解常见的 UNIX® 原语，比如 PID 是什么，线程是什么等。在第三个小节中，我们讨论了 UNIX® 与 UNIX® 之间仿真的一般方法。

2.1. 什么是 UNIX®

UNIX® 是一款具有悠久历史的操作系统，几乎影响了当前使用的所有操作系统。自 1960 年代开始，它的开发至今仍在继续（尽管已分叉为不同的项目）。UNIX® 的发展很快复刻成两大主流：BSD 系列和 System III/V 系列。它们通过共同的 UNIX® 标准相互影响。在 BSD 系列中，值得一提的贡献有虚拟内存、TCP/IP 网络、FFS 等，而 System V 分支则贡献了 SysV 进程间通信原语、写时复制等。虽然 UNIX® 本身已不存在，但其思想已被世界上许多操作系统所采用，形成了所谓的类 UNIX® 操作系统。目前，最具影响力的操作系统包括 Linux®、Solaris 和可能在一定程度上包括 FreeBSD。还有一些公司内部的 UNIX® 派生操作系统（如 AIX、HP-UX 等），但这些系统越来越多地迁移到了上述操作系统。让我们总结一下 UNIX® 的典型特征。

2.2. 技术细节

每个运行的程序构成一个进程，代表计算的某个状态。运行中的进程分为内核空间和用户空间。某些操作只能在内核空间执行（如与硬件交互等），但进程应该大部分时间运行在用户空间。内核负责管理进程、硬件和底层细节，并为用户空间提供统一的 UNIX® API。下面列出了最重要的几个。

2.2.1. 内核与用户空间进程之间的通信

常见的 UNIX® API 定义了系统调用（syscall）作为用户空间进程向内核发出命令的一种方式。最常见的实现方式是通过使用中断或专用指令（例如，ia32 的 SYSENTER/SYSCALL 指令）。系统调用是通过一个编号来定义的。例如，在 FreeBSD 中，系统调用编号 85 是系统调用，编号 132 是系统调用。某些系统调用需要参数，这些参数通过多种方式从用户空间传递到内核空间（具体实现依赖于操作系统）。系统调用是同步的。

另一种可能的通信方式是通过使用 trap（陷阱）。陷阱是由于某些事件发生后异步触发的（例如，除零错误、页面错误等）。陷阱可能对进程透明（如页面错误），或者可能导致某些反应，如发送一个 signal（信号）（例如，除零错误）。

2.2.2. 进程间通信

除了其他 API（如 System V IPC、共享内存等）之外，最重要的 API 是信号。信号由进程或内核发送，并由进程接收。某些信号可以被忽略或由用户提供的例程处理，其他信号则会导致预定义的动作，这些动作无法改变或忽略。

2.2.3. 进程管理

内核实例首先在系统中被处理（称为 init）。每个运行的进程都可以使用系统调用创建它的副本。这个系统调用有一些稍微修改过的版本，但其基本语义是相同的。每个运行的进程可以通过调用系统调用转换为另一个进程。这个系统调用也有一些修改过的版本，但所有版本的基本目的是一样的。进程通过调用系统调用结束其生命周期。每个进程都有一个唯一的标识号，称为 PID，每个进程都有一个父进程（通过其 PID 来标识）。

2.2.4. 线程管理

传统的 UNIX® 并未定义任何关于线程的 API 或实现，而 POSIX® 定义了其线程 API，但未定义其实现。传统上，线程有两种实现方式。将其作为独立进程处理（1:1 线程）或将整个线程组封装在一个进程中并在用户空间管理线程（1:N 线程）。比较这两种方法的主要特点：

1:1 线程

重型线程
用户无法修改调度（通过 POSIX® API 稍微可以缓解）
无需系统调用包装
可以利用多个 CPU

1:N 线程

轻量级线程
可以轻松修改调度
需要包装系统调用
无法利用多个 CPU

2.3. 什么是 FreeBSD？

FreeBSD 项目是目前可供日常使用的最古老的开源操作系统之一。它是正统 UNIX® 的直接后代，因此可以声称它是一个真正的 UNIX®，尽管由于许可证问题不能这样称呼。该项目始于 1990 年代初，当时一群 BSD 用户修补了 386BSD 操作系统。在这个补丁包的基础上，一个新的操作系统应运而生，名为 FreeBSD，因其宽松的许可证而得名。另一组人则创建了 NetBSD 操作系统，目标有所不同。我们将重点讨论 FreeBSD。

FreeBSD 是一个现代的基于 UNIX® 的操作系统，具备 UNIX® 的所有特性。包括抢占式多任务处理、多用户功能、TCP/IP 网络、内存保护、对称多处理支持、虚拟内存与合并的 VM 和缓冲区缓存等功能，它们都包含在内。一个有趣且非常有用的特性是能够模拟其他 UNIX® 类操作系统。截至 2006 年 12 月和 7-CURRENT 开发版本，以下模拟功能已经得到支持：

FreeBSD/i386 在 FreeBSD/amd64 上的模拟
FreeBSD/i386 在 FreeBSD/ia64 上的模拟
Linux® 模拟：在 FreeBSD 上模拟 Linux® 操作系统
NDIS 模拟：Windows 网络驱动接口的模拟

目前正在积极开发的模拟功能有 Linux® 层和各种 FreeBSD-on-FreeBSD 层。其他的功能目前不被认为是能够正常工作或可用的。

2.3.1. 技术细节

FreeBSD 是传统的 UNIX® 版本，在进程运行方面将其分为两个部分：内核空间和用户空间。进程进入内核有两种方式：系统调用和陷阱。返回的方式只有一种。在接下来的章节中，我们将介绍进出内核的三个入口。整段简介适用于 i386 架构，因为 Linuxulator 仅存在于此，但在其他架构上的概念类似。以下信息来源于 [1] 和源代码。

2.3.1.1. 系统入口

FreeBSD 有个抽象概念，称为执行类加载器，它是系统调用的一个切入点。它使用一个名为 sysentvec 的结构，描述可执行文件的 ABI。该结构包含错误号翻译表、信号翻译表、以及为系统调用提供服务的各种函数（例如堆栈修正、核心转储等）。FreeBSD 内核想要支持的每个 ABI 都必须定义这个结构，因为它会在系统调用处理代码和其他地方被使用。系统入口由陷阱处理程序处理，我们可以同时访问内核空间和用户空间。

2.3.1.2. 系统调用

FreeBSD 中的系统调用通过执行中断 0x80 发起，其中寄存器 %eax 被设置为所需的系统调用号，参数则通过堆栈传递。

当一个进程发出中断 0x80 时，将调用 int0x80 系统调用陷阱处理程序（在 sys/i386/i386/exception.s 中定义），该处理程序为调用 C 函数（在 sys/i386/i386/trap.c 中定义）做准备，处理传入的陷阱帧。处理过程包括准备系统调用（取决于 sysvec 条目），确定系统调用是 32 位还是 64 位（这会改变参数的大小），然后将参数复制，包括系统调用。接下来，执行实际的系统调用函数，并处理返回代码（特殊情况包括 ERESTART 和 EJUSTRETURN 错误）。最后，调度一个 userret()，将进程切换回用户空间。实际的系统调用处理程序的参数以 struct thread *td 和 struct syscall args * 参数的形式传递，第二个参数是指向复制的参数结构的指针。

2.3.1.3. 陷阱

在 FreeBSD 中，陷阱的处理与系统调用的处理类似。每当发生陷阱时，会调用一个汇编处理程序。这个处理程序的选择依据陷阱类型而不同，可以是 alltraps、alltraps with regs pushed 或 calltrap。该处理程序准备好参数后，调用 C 函数 trap()（定义在 sys/i386/i386/trap.c 中），然后处理发生的陷阱。处理完成后，可能会向进程发送信号和/或使用 userret() 返回到用户空间。

2.3.1.4. 退出

从内核到用户空间的退出是通过汇编例程 doreti 完成的，无论是通过陷阱还是系统调用进入内核。该过程会从堆栈中恢复程序状态并返回到用户空间。

2.3.1.5. UNIX® 原语

FreeBSD 操作系统遵循传统的 UNIX® 方案，其中每个进程都有一个唯一的标识号，称为 PID（进程 ID）。PID 数字的分配可以是线性分配或随机分配，范围从 0 到 PID_MAX。PID 数字的分配是通过线性搜索 PID 空间完成的。每个进程中的线程都会获得与进程相同的 PID，作为调用的结果。

FreeBSD 中目前有两种实现线程的方法。第一种是 M:N 线程模型，接下来是 1:1 线程模型。默认使用的库是 M:N 线程模型（libpthread），并且可以在运行时切换到 1:1 线程模型（libthr）。计划是尽快将默认库切换为 1:1 库。尽管这两个库使用相同的内核原语，但它们通过不同的 API 访问。M:N 库使用 kse_* 系列系统调用，而 1:1 库使用 thr_* 系列系统调用。因此，内核和用户空间之间没有共享的线程 ID 概念。当然，这两个线程库都实现了 pthread 线程 ID API。每个内核线程（由 struct thread 描述）都有一个 td tid 标识符，但它不能直接从用户空间访问，只供内核使用。它也被用作 1:1 线程库中的 pthread 线程 ID，但其处理方式是库内部的，不能依赖于此。

如前所述，FreeBSD 中有两种线程实现。M:N 库将工作分配给内核空间和用户空间。线程是一个在内核中调度的实体，但它可以表示多个用户空间线程。M 个用户空间线程映射到 N 个内核线程，从而节省资源，同时保持利用多处理器并行性的能力。有关实现的更多信息可以从手册页或 [1] 获取。1:1 库则直接将用户空间线程映射到内核线程，从而大大简化了方案。这些设计都没有实现公平机制（虽然曾经实现过，但由于造成了严重的性能下降并使代码更难维护，最近已被移除）。

2.4. 什么是 Linux®？

Linux® 是一款类似 UNIX® 的内核，最初由 Linus Torvalds 开发，现在由全球大量程序员贡献。自从它的起步到今天，得到了 IBM 和谷歌等公司的广泛支持，Linux® 与其快速的开发速度、全面的硬件支持和仁慈独裁的组织模式相关联。

Linux® 的开发始于 1991 年，在芬兰赫尔辛基大学作为一个爱好者项目启动。从那时起，它就获得了现代 UNIX® 类操作系统的所有特性：多处理、支持多用户、虚拟内存、网络功能，基本上所有功能都具备了。还有一些先进的特性，如虚拟化等。

截至 2006 年，Linux® 已成为最广泛使用的开源操作系统，得到了独立软件厂商如 Oracle、RealNetworks、Adobe 等的支持。大多数为 Linux® 分发的商业软件只能以二进制形式获得，因此无法重新编译为其他操作系统。

大多数 Linux® 的开发都发生在 Git 版本控制系统中。Git 是一款分布式系统，因此 Linux® 代码没有中央来源，但一些分支被认为是突出和官方的。Linux® 实现的版本号方案由四个数字 A.B.C.D 组成。目前开发版本为 2.6.C.D，其中 C 代表主要版本，添加或更改新特性，而 D 是次要版本，仅用于修复 bug。

更多信息可以从 [3] 获取。

2.4.1. 技术细节

Linux® 遵循传统的 UNIX® 方案，将进程的执行分为两个部分：内核空间和用户空间。内核可以通过两种方式进入：通过陷阱或通过系统调用。返回只有一种方式。以下描述适用于 i386™ 架构上的 Linux® 2.6。该信息来源于 [2]。

2.4.1.1. 系统调用

Linux® 中的系统调用（在用户空间中）使用 syscallX 宏来执行，其中 X 是表示给定系统调用参数数量的数字。此宏会转换为一个代码，该代码将 %eax 寄存器加载为系统调用的编号，并执行中断 0x80。在系统调用返回后，负返回值会转换为正的 errno 值，并且在发生错误时将 res 设置为 -1。每当调用中断 0x80 时，进程就会进入内核，进入系统调用陷阱处理程序。该程序将所有寄存器保存到堆栈中，并调用选定的系统调用入口。需要注意的是，Linux® 的调用约定要求通过寄存器传递系统调用的参数，具体如下：

参数 → %ebx
参数 → %ecx
参数 → %edx

有些系统调用例外，使用了不同的调用约定（最显著的例子是 clone 系统调用）。

2.4.1.2. 陷阱

陷阱处理程序定义在 arch/i386/kernel/traps.c 中，处理大部分陷阱的代码位于 arch/i386/kernel/entry.S，其中进行陷阱的处理。

2.4.1.3. 退出

从系统调用返回由系统调用管理，系统调用会检查进程是否有未完成的工作，然后检查是否使用了用户提供的选择器。如果发生这种情况，会应用堆栈修复，最后从堆栈恢复寄存器，进程返回到用户空间。

2.4.1.4. UNIX® 原语

在 2.6 版本中，Linux® 操作系统重新定义了一些传统的 UNIX® 原语，特别是 PID、TID 和线程。PID 并不被定义为每个进程唯一的标识符，因此对于某些进程（线程），返回相同的值。进程的唯一标识是通过 TID 提供的。这是因为 NPTL（新 POSIX® 线程库）将线程定义为普通进程（即 1:1 线程模型）。在 Linux® 2.6 中创建新进程是通过 clone 系统调用（fork 的变体）来完成的。这个 clone 系统调用定义了一组影响线程实现的克隆过程行为的标志。其语义有点模糊，因为没有单一的标志可以告诉系统调用创建一个线程。

实现的 clone 标志包括：

CLONE_VM - 进程共享内存空间
CLONE_FS - 共享 umask、当前工作目录和命名空间
CLONE_FILES - 共享打开的文件

CLONE_PARENT 将实际父进程设置为调用者的父进程。这对于线程非常有用，因为如果线程 A 创建了线程 B，那么我们希望线程 B 的父进程是整个线程组的父进程。CLONE_THREAD 完全执行与 CLONE_PARENT 相同的操作，CLONE_VM 和 CLONE_SIGHAND，将 PID 修改为与调用者的 PID 相同，设置退出信号为空，并进入线程组。CLONE_SETTLS 设置 TLS 处理的 GDT 条目。CLONE_*_*TID 系列标志设置/清除 TID 或 0 的用户提供地址。

正如你所见，CLONE_THREAD 完成了大部分工作，并且似乎并不完全适应当前的方案。其原始意图不明确（根据代码中的注释，甚至连作者也不清楚），但我认为最初可能有一个线程标志，后来被拆分为许多其他标志，但这种拆分从未完全完成。对于这一划分的意义也不清楚，因为 glibc 并没有使用它，所以只有通过手写的 clone 调用，程序员才能访问这些功能。

对于非线程程序，PID 和 TID 是相同的。对于线程程序，第一个线程的 PID 和 TID 是相同的，每个创建的线程共享相同的 PID，并获得一个唯一的 TID（因为传递了 CLONE_THREAD），同时所有进程共享父进程，形成该线程程序。

在 NPTL 中实现的代码定义了 clone 标志，如下所示：

CLONE_SIGNAL 定义为：

最后的 0 表示在任何线程退出时不会发送信号。

2.5. 什么是仿真

根据词典定义，仿真是程序或设备模仿另一个程序或设备的能力。这是通过对给定的刺激作出与被仿真对象相同的反应来实现的。在实际中，软件世界通常看到三种类型的仿真——用于仿真机器的程序（如 QEMU，各种游戏机仿真器等）、硬件设施的仿真软件（如 OpenGL 仿真器，浮点单元仿真等）以及操作系统仿真（无论是在操作系统的内核中还是作为用户空间程序）。

仿真通常在无法或完全不可能使用原始组件的地方使用。例如，有人可能希望使用为不同操作系统开发的程序。这时仿真就派上了用场。有时别无选择，只能使用仿真——例如当你试图使用的硬件设备不存在（还不存在或不再存在）时，那么唯一的选择就是仿真。通常在将操作系统移植到一个新平台（该平台尚不存在）时会发生这种情况。有时仿真只是更便宜。

从实现的角度来看，仿真的实现方法主要有两种。你可以仿真整个组件——接受原始对象的可能输入，维护内部状态并根据状态和/或输入发出正确的输出。这种仿真不需要特殊的条件，基本上可以在任何地方为任何设备/程序实现。缺点是，实现这种仿真相当困难、耗时且容易出错。在某些情况下，我们可以使用更简单的方法。假设你想在一台从右向左打印的打印机上仿真一台从左向右打印的打印机。显然，没有必要使用复杂的仿真层，只需简单地反转打印的文本即可。也有可能仿真环境与被仿真环境非常相似，因此只需要一层薄薄的转换即可提供完整的仿真！正如你所见，这种方法比前一种方法更不要求实现，因此也更不耗时且更不容易出错。但必要的条件是两个环境必须足够相似。第三种方法结合了前两种方法。大多数情况下，仿真对象提供的能力并不相同，因此在更强大的对象上仿真较弱的对象时，我们必须使用上述完全仿真所描述的方式来仿真缺失的功能。

本硕士论文涉及 UNIX® 在 UNIX® 上的仿真，这正是一个只需薄薄的转换层就能提供完整仿真的案例。UNIX® API 由一组系统调用组成，这些调用通常是自包含的，并不会影响全局的内核状态。

有一些系统调用会影响内部状态，但这可以通过提供一些结构来处理，这些结构维护额外的状态。

没有任何仿真是完美的，仿真通常会缺少一些部分，但这通常不会造成严重的缺陷。想象一个游戏机仿真器，仿真所有内容但没有声音输出。毫无疑问，游戏仍然是可以玩的，尽管不如原始游戏机那样舒适，但它是价格与舒适度之间的一个可以接受的折衷。

UNIX® API 也是如此。大多数程序可以在很有限的系统调用集工作下生存。这些系统调用通常是最古老的那些（/、系列、处理、、 API)，因此它们很容易仿真，因为它们的语义在今天存在的所有 UNIX® 操作系统中是共享的。

3. 模拟

3.1. FreeBSD 中模拟的工作原理

如前所述，FreeBSD 支持运行来自其他多个 UNIX® 系统的二进制文件。之所以能实现这一点，是因为 FreeBSD 提供了一个叫做执行类加载器（execution class loader）的抽象机制。该机制与系统调用结合使用，当准备执行一个二进制文件时，它会检查该文件的类型。

在 FreeBSD 中，二进制文件大致分为两种类型。第一种是类似 shell 的文本脚本，它们的前两个字符是 #!；第二种是正常的（通常是 ELF 格式的）二进制文件，表示编译后的可执行对象。绝大多数（可以说所有）FreeBSD 中的二进制文件都是 ELF 类型。ELF 文件包含一个头部，其中指定了该 ELF 文件的操作系统 ABI（应用二进制接口）。通过读取这些信息，操作系统可以准确地确定给定文件的二进制类型。

每个操作系统 ABI 必须在 FreeBSD 内核中注册，包括 FreeBSD 本身的原生操作系统 ABI。因此，当执行一个二进制文件时，它会遍历已注册的 ABI 列表，当找到匹配的 ABI 时，它会开始使用该 ABI 描述中包含的信息（如系统调用表、errno 转换表等）。因此，每当进程调用系统调用时，它都会使用自己的一套系统调用，而不是使用全局系统调用。这为支持执行各种二进制格式提供了一种非常优雅且简单的方式。

不同操作系统（以及其他一些子系统）模拟的特点促使开发者引入了事件处理机制。内核中的多个地方允许注册事件处理程序，这些处理程序会按需被调用。例如，当一个进程退出时，会调用一个处理程序，清理该子系统需要清理的内容。

这些简单的设施基本上提供了模拟基础架构所需的一切，实际上，它们是实现 Linux® 模拟层所必需的唯一内容。

3.2. FreeBSD 内核中的常见原语

模拟层需要操作系统的支持。接下来我将描述一些 FreeBSD 操作系统中支持的原语。

3.2.1. 锁原语

贡献者：Attilio Rao <[email protected]>

FreeBSD 的同步原语集基于提供大量不同原语的理念，以便在每种特定情况下可以使用最合适的原语。

从高层次来看，FreeBSD 内核中可以视为三种同步原语：

原子操作和内存屏障
锁
调度屏障

以下是这三类原语的描述。对于每种锁，你应该查阅相应的手册页（如果可能的话）以获取更详细的解释。

3.2.1.1. 原子操作和内存屏障

原子操作通过一组函数实现，这些函数以原子的方式对内存操作数进行简单的算术运算，并且对外部事件（如中断、抢占等）保持原子性。原子操作仅能保证对小数据类型的原子性（在 .long. 架构的 C 数据类型量级范围内），因此它们应该在最终级代码中很少直接使用，除非是进行非常简单的操作（例如，在位图中设置标志）。事实上，单纯依赖原子操作编写错误的语义（通常被称为无锁操作）是相当常见的。FreeBSD 内核提供了一种方法，将原子操作与内存屏障结合使用。内存屏障能够保证原子操作按照指定的顺序执行，与其他内存访问之间保持一定的顺序关系。例如，如果我们需要确保原子操作在所有其他待处理写操作（指令重排缓冲区活动）完成之后才发生，就需要明确地在该原子操作之前使用内存屏障。因此，理解内存屏障在更高级别锁构建中的关键作用是很简单的（比如引用计数、互斥锁等）。关于原子操作的详细解释，请参考。然而，值得注意的是，原子操作（以及内存屏障）理想情况下应仅用于构建前端锁（如互斥锁）。

3.2.1.2. 引用计数

引用计数是用于处理引用计数器的接口。它们通过原子操作实现，旨在仅在引用计数器是唯一需要保护的内容时使用，因此即使是旋转互斥锁（spin-mutex）也不再推荐使用。对于已经使用互斥锁保护的结构，使用引用计数接口通常是不正确的，因为我们可能应该在一些已经保护的路径中关闭引用计数器。当前没有关于引用计数的手册页面，请查看 sys/refcount.h 以获取现有 API 的概述。

3.2.1.3. 锁

FreeBSD 内核有大量的锁类型。每种锁都由一些特定的属性定义，但最重要的属性可能是与争用持有者相关的事件（或换句话说，线程无法获取锁时的行为）。FreeBSD 的锁定方案为竞争者提供了三种不同的行为：

自旋
阻塞
睡眠

注意
数字并非随意

3.2.1.4. 自旋锁

自旋锁允许等待的线程自旋，直到它能够获取锁。需要处理的一个重要问题是，当线程在自旋锁上发生争用时，如果线程没有被重新调度，会发生什么情况。由于 FreeBSD 内核是抢占式的，这使得自旋锁面临死锁的风险，唯一的解决办法是禁用中断来获取锁。由于这些原因（例如缺乏优先级传播支持、CPU 之间负载均衡方案的不足等），自旋锁应该仅保护非常小的代码路径，或者如果没有明确要求，最好根本不使用它们（稍后将解释）。

3.2.1.5. 阻塞

阻塞锁允许等待的线程被重新调度并阻塞，直到锁的拥有者释放锁并唤醒一个或多个竞争者。为了避免饥饿问题，阻塞锁会将优先级从等待者传递给锁的拥有者。阻塞锁必须通过转门（turnstile）接口实现，并且应该是内核中最常用的锁类型，除非满足某些特定条件。

3.2.1.6. 睡眠

睡眠锁允许等待的线程被重新调度并进入睡眠，直到锁的持有者释放锁并唤醒一个或多个等待者。由于睡眠锁旨在保护较大的代码路径并处理异步事件，因此它们不会进行任何形式的优先级传播。它们必须通过接口实现。

获取锁的顺序非常重要，不仅因为锁顺序反转可能导致死锁，还因为获取锁时应遵循特定的规则，这些规则与锁的性质有关。如果你查看上面的表格，可以得出一个实际规则：如果一个线程持有级别为 n 的锁（其中级别是与锁类型相对应的数字），则不允许获取更高级别的锁，因为这会破坏路径的语义。例如，如果一个线程持有一个阻塞锁（级别 2），它可以获取自旋锁（级别 1），但不能获取睡眠锁（级别 3），因为阻塞锁旨在保护比睡眠锁更小的路径（然而这些规则与原子操作或调度屏障无关）。

以下是锁及其相应行为的列表：

自旋互斥锁 - 自旋 -
睡眠互斥锁 - 阻塞 -
池互斥锁 - 阻塞 -
睡眠家族 - 睡眠 -

在这些锁中，只有互斥锁、sx 锁、读写锁和 lockmgr 锁是设计用来处理递归的，但目前只有互斥锁和 lockmgr 锁支持递归。

3.2.1.7. 调度屏障

调度屏障用于驱动线程的调度。它们主要由三种不同的存根组成：

临界区（和抢占）
sched_bind
sched_pin

通常，这些应该仅在特定的上下文中使用，即使它们通常可以替代锁，也应该避免使用它们，因为它们不允许使用锁调试工具（如）来诊断简单的潜在问题。

3.2.1.8. Critical sections

FreeBSD 内核是为了处理中断线程而使其具有抢占性。实际上，为了避免高中断延迟，时间共享优先级线程可以被中断线程抢占（这样，它们无需等到正常调度路径的预设）。然而，抢占引入了新的竞争点，必须处理这些点。通常，为了应对抢占，最简单的做法是完全禁用抢占。临界区定义了一段代码（由和这两个函数边界标定），在此期间保证不会发生抢占（直到受保护的代码完全执行完毕）。这通常可以有效地替代锁，但应小心使用，以免失去抢占带来的整体优势。

3.2.1.9. sched_pin/sched_unpin

另一种处理抢占的方法是使用 sched_pin() 接口。如果一段代码被包含在 sched_pin() 和 sched_unpin() 这对函数中，保证该线程即使可以被抢占，也将始终在同一个 CPU 上执行。固定（pinning）在某些情况下非常有效，特别是当我们需要访问每个 CPU 特有的数据，并假设其他线程不会更改这些数据时。后者的条件将决定临界区对我们代码来说过于强的条件。

3.2.1.10. sched_bind/sched_unbind

sched_bind 是一种 API，用于将线程绑定到特定的 CPU 上，直到 sched_unbind 函数调用将其解除绑定。这一功能在你无法信任当前 CPU 状态的情况下非常重要（例如，在引导的早期阶段），因为你希望避免线程迁移到非活动的 CPU 上。由于 sched_bind 和 sched_unbind 操作内部调度器结构，因此在使用时需要在 sched_lock 获取/释放之间进行封装。

3.2.2. Proc 结构

各种仿真层有时需要一些额外的每个进程数据。可以为每个进程管理单独的结构（如列表、树等）来存储这些数据，但这往往效率低下且消耗内存。为了解决这个问题，FreeBSD 的 proc 结构包含了 p_emuldata，它是一个指向某些仿真层特定数据的 void 指针。这个 proc 条目受到 proc 锁的保护。

FreeBSD 的 proc 结构包含 p_sysent 条目，标识该进程正在运行的 ABI。事实上，它是指向上述 sysentvec 的一个指针。所以，通过将这个指针与给定 ABI 的 sysentvec 结构的存储地址进行比较，我们可以有效地判断该进程是否属于我们的仿真层。代码通常如下所示：

如你所见，我们有效地使用 __predict_true 修饰符将最常见的情况（FreeBSD 进程）压缩为简单的返回操作，从而保持高性能。由于当前不支持 Linux®64 仿真或 i386 上的 A.OUT Linux® 进程，因此这段代码应当转换为宏，因为它目前不够灵活。

3.2.3. VFS

FreeBSD 的 VFS 子系统非常复杂，但 Linux® 仿真层仅通过一个小子集通过明确定义的 API 使用它。它可以操作 vnodes 或文件句柄。Vnode 代表一个虚拟 vnode，即 VFS 中节点的表示。另一种表示是文件句柄，它从进程的角度表示一个已打开的文件。文件句柄可以代表套接字或普通文件。一个文件句柄可以指向其 vnode。多个文件句柄可以指向同一个 vnode。

3.2.3.1. namei

例程是路径名查找和转换的中央入口点。它从起始点到终点逐点遍历路径，使用内部的查找功能。系统调用能够处理符号链接、绝对路径和相对路径。当一个路径通过查找时，它被输入到名称缓存中。此行为可以被抑制。这个例程在整个内核中被广泛使用，其性能非常关键。

3.2.3.2. vn_fullpath

函数尽最大努力遍历 VFS 名称缓存，并为给定（已锁定的）vnode 返回路径。这个过程不可靠，但对于大多数常见情况来说效果很好。不可靠的原因是它依赖于 VFS 缓存（它不会遍历介质结构），它不适用于硬链接等。这一例程在 Linuxulator 中的多个地方使用。

3.2.3.3. Vnode 操作

fgetvp - 给定线程和文件描述符号，它返回关联的 vnode
- 锁定 vnode
vn_unlock - 解锁 vnode

3.2.3.4. 文件句柄操作

fget - 给定线程和文件描述符号，它返回关联的文件句柄并引用它
fdrop - 删除对文件句柄的引用
fhold - 引用文件句柄

4. Linux® 仿真层——机器相关部分

本节讨论了 FreeBSD 操作系统中 Linux® 仿真层的实现。首先介绍了与用户态和内核交互的机器相关部分，涉及系统调用、信号、ptrace、陷阱、栈修正等内容。尽管本节以 i386 为例，但其编写方式是通用的，因此其他架构的实现应不会有很大不同。接下来是 Linuxulator 的机器无关部分，本节仅覆盖 i386 和 ELF 处理，A.OUT 已不再使用且未经测试。

4.1. 系统调用处理

系统调用处理大部分写在 linux_sysvec.c 中，该文件覆盖了 sysentvec 结构中列出的绝大多数例程。当在 FreeBSD 上运行的 Linux® 进程发出系统调用时，通用系统调用例程会调用 Linux® 的 prepsyscall 例程。

4.1.1. Linux® prepsyscall

Linux® 通过寄存器传递系统调用的参数（这就是为什么它在 i386 上仅限于 6 个参数的原因），而 FreeBSD 则使用栈。Linux® 的 prepsyscall 例程必须将参数从寄存器复制到栈中。寄存器的顺序是：%ebx、%ecx、%edx、%esi、%edi、%ebp。需要注意的是，这对于 大多数 系统调用是成立的。有些（尤其是 clone）使用不同的顺序，但幸运的是，可以通过在 linux_clone 原型中插入一个虚拟参数来轻松修复。

4.1.2. 系统调用写入

Linuxulator 中实现的每个系统调用必须在 syscalls.master 中定义其原型，并附带各种标志。该文件的格式如下：

第一列表示系统调用编号。第二列用于审计支持。第三列表示系统调用类型。它可以是 STD、OBSOL、NOPROTO 或 UNIMPL。STD 是标准系统调用，具有完整的原型和实现。OBSOL 是过时的，仅定义原型。NOPROTO 表示系统调用在其他地方实现，因此不需要添加 ABI 前缀等。UNIMPL 表示该系统调用将被 nosys 系统调用替代（该系统调用仅打印一条关于该系统调用未实现的消息，并返回 ENOSYS）。

从 syscalls.master 文件中，脚本会生成三个文件：linux_syscall.h、linux_proto.h 和 linux_sysent.c。linux_syscall.h 包含系统调用名称及其数值的定义，例如：

linux_proto.h 包含每个系统调用的参数结构定义，例如：

最后，linux_sysent.c 包含描述系统入口表的结构，该表用于实际调度系统调用，例如：

如你所见，linux_fork 是在 Linuxulator 中实现的，因此其定义为 STD 类型，并且没有参数，这通过虚拟参数结构来体现。另一方面，close 只是 FreeBSD 的别名，因此没有与 Linux 参数结构相关联，并且在系统入口表中没有添加 linux_ 前缀，因为它调用的是内核中的真实。

4.1.3. 虚拟系统调用

Linux® 仿真层并不完整，因为某些系统调用没有正确实现，有些则根本没有实现。仿真层通过 DUMMY 宏标记未实现的系统调用。这些虚拟定义存在于 linux_dummy.c 中，形式为 DUMMY(syscall);，然后会被转换到各种系统调用辅助文件中，实际实现就是打印一条消息，表明该系统调用未实现。UNIMPL 原型没有使用，因为我们希望能够识别被调用的系统调用名称，以了解哪些系统调用更需要实现。

4.2. 信号处理

信号处理在 FreeBSD 内核中通常是针对所有二进制兼容性进行的，调用了与兼容性相关的层。Linux® 兼容性层定义了 linux_sendsig 例程来处理这一任务。

4.2.1. Linux® sendsig

该例程首先检查信号是否已安装并带有 SA_SIGINFO，如果是，它会调用 linux_rt_sendsig 例程。除此之外，它会分配（或重用已存在的）信号处理上下文，然后为信号处理程序构建参数列表。它根据信号翻译表翻译信号编号，分配处理程序，翻译信号集。接着，它为 sigreturn 例程保存上下文（各种寄存器、翻译后的陷阱号和信号掩码）。最后，它将信号上下文复制到用户空间并准备实际运行的信号处理程序上下文。

4.2.2. linux_rt_sendsig

这个例程与 linux_sendsig 类似，只是信号上下文的准备过程不同。它添加了 siginfo、ucontext 和一些 POSIX® 部分。值得考虑的是，是否可以将这两个函数合并，以减少代码重复，并可能提高执行效率。

4.2.3. linux_sigreturn

这个系统调用用于从信号处理程序返回。它执行一些安全检查并恢复原始进程上下文，同时取消对进程信号掩码的屏蔽。

4.3. Ptrace

许多 UNIX® 派生系统实现了系统调用，以允许各种跟踪和调试功能。该功能使得跟踪进程能够获取关于被跟踪进程的各种信息，如寄存器转储、进程地址空间中的任何内存等，并且能够像单步执行指令或在系统调用和陷阱之间进行跟踪一样跟踪进程。还允许你设置被跟踪进程中的各种信息（如寄存器等）。是一个 UNIX® 广泛使用的标准，在大多数 UNIX® 系统中都有实现。

在 FreeBSD 中，Linux® 仿真层实现了功能，代码位于 linux_ptrace.c 文件中。该例程负责在 Linux® 和 FreeBSD 之间转换寄存器，并执行实际的系统调用仿真。该系统调用是一个长的 switch 块，为每个命令实现了 FreeBSD 对应的功能。命令在 Linux® 和 FreeBSD 之间大多是相同的，因此通常只需要做少量修改。例如，Linux® 中的 PT_GETREGS 直接操作数据，而 FreeBSD 使用指向数据的指针，因此在执行（本地）系统调用后，必须执行 copyout 以保持 Linux® 的语义。

Linuxulator 中的实现存在一些已知的缺陷。使用 strace（它是的消费方）时，曾经发生过 panic 错误。同时，PT_SYSCALL 也没有实现。

4.4. 陷阱

当在仿真层中运行的 Linux® 进程发生陷阱时，陷阱会被透明地处理，唯一的例外是陷阱的翻译。Linux® 和 FreeBSD 对于什么是陷阱有不同的看法，因此在这里进行处理。代码实际上非常简短：

4.5. 栈修复

RTLD（运行时链接编辑器）期望在 execve 调用期间栈上存在所谓的 AUX 标签，因此必须进行修复以确保这一点。当然，每个 RTLD 系统都是不同的，因此仿真层必须提供自己的栈修复例程来执行此操作。Linuxulator 也不例外。elf_linux_fixup 简单地将 AUX 标签复制到栈上，并调整用户空间进程的栈，使其指向这些标签之后的位置。这样 RTLD 就能正常工作。

4.6. A.OUT 支持

在 i386 上，Linux® 仿真层还支持 Linux® A.OUT 二进制文件。前面描述的大多数内容（除了陷阱翻译和信号发送）都必须实现以支持 A.OUT。A.OUT 二进制文件的支持已经不再维护，特别是 2.6 版本的仿真并不支持它，但这并不会造成问题，因为在 Ports 中的 linux-base 可能根本不支持 A.OUT 二进制文件。此支持可能会在未来移除。加载 Linux® A.OUT 二进制文件所需的大部分内容都在 imgact_linux.c 文件中。

5. Linux® 仿真层——机器无关部分

本节讨论 Linuxulator 的机器无关部分。它涵盖了 Linux® 2.6 仿真所需的仿真基础设施、线程局部存储（TLS）实现（在 i386 上）以及 futex。然后简要讨论一些系统调用。

5.1. NPTL 的描述

Linux® 2.6 发展中的一个主要进展领域是线程支持。在 2.6 之前，Linux® 线程支持是通过 linuxthreads 库实现的。该库是 POSIX® 线程的部分实现。线程是通过为每个线程创建单独的进程来实现的，使用 clone 系统调用让它们共享地址空间（以及其他资源）。这种方法的主要弱点是每个线程都有不同的 PID，信号处理出现问题（从 pthreads 角度看），等等。并且性能不佳（使用 SIGUSR 信号进行线程同步，内核资源消耗等）。为了解决这些问题，开发了一个新的线程系统，命名为 NPTL。

NPTL 库专注于两件事，但第三件事也随之而来，因此通常认为它是 NPTL 的一部分。这两件事是将线程嵌入到进程结构中和 futex。第三件事是 TLS，虽然它不是 NPTL 直接要求的，但整个 NPTL 用户空间库都依赖于它。这些改进大大提升了性能并符合标准。NPTL 目前是 Linux® 系统中的标准线程库。

FreeBSD Linuxulator 的实现通过三个主要领域来接近 NPTL：TLS、futex 和 PID 混乱，这些是为了模拟 Linux® 线程。接下来的章节将描述这些领域。

5.2. Linux® 2.6 仿真基础设施

这些部分讨论了 Linux® 线程是如何管理的，以及我们如何在 FreeBSD 中模拟这一过程。

5.2.1. 运行时确定 2.6 仿真版本

FreeBSD 中的 Linux® 仿真层支持在运行时设置仿真版本。这是通过完成的，具体是 compat.linux.osrelease。设置该会影响仿真层的运行时行为。当设置为 2.6.x 时，它会设置 linux_use_linux26 变量，而设置为其他值则保持未设置状态。这个变量（加上与之相关的每个 prison 变量）决定是否在代码中使用 2.6 基础设施（主要是 PID 混乱）。版本设置是系统范围的，影响所有 Linux® 进程。运行任何 Linux® 二进制文件时不应更改该，因为这可能会导致问题。

5.2.2. Linux® 进程和线程标识符

Linux® 线程的语义有些令人困惑，并且使用与 FreeBSD 完全不同的术语。Linux® 中的一个进程由一个 struct task 组成，其中嵌套了两个标识符字段——PID 和 TGID。PID 不是进程 ID，而是线程 ID。TGID 用来标识一个线程组，也就是一个进程。对于单线程进程，PID 等于 TGID。

在 NPTL 中，线程只是一个普通的进程，只是它的 TGID 不等于 PID，并且其组领导者不等于它本身（当然，还共享虚拟内存等）。其他一切和普通进程相同。并没有像 FreeBSD 中那样将共享状态分离到某个外部结构中。这就导致了信息的重复和可能的数据不一致。Linux® 内核似乎在某些地方使用 task → group 信息，而在其他地方使用 task 信息，这种做法并不一致，容易出错。

每个 NPTL 线程都是通过调用 clone 系统调用并传入一组特定的标志来创建的（更多内容见下一小节）。NPTL 实现了严格的 1:1 线程模型。

在 FreeBSD 中，我们通过普通的 FreeBSD 进程来模拟 NPTL 线程，这些进程共享虚拟内存空间等，而 PID 操作则通过附加到进程的仿真特定结构来模拟。附加到进程的结构如下所示：

PID 用于标识附加此结构的 FreeBSD 进程。child_set_tid 和 child_clear_tid 用于在进程退出和创建时进行 TID 地址的拷贝。shared 指针指向一个在线程之间共享的结构体。pdeath_signal 变量标识父进程死亡信号，而 threads 指针用于将此结构链接到线程列表中。linux_emuldata_shared 结构如下所示：

refs 是一个引用计数器，用于确定何时可以释放结构体，以避免内存泄漏。group_pid 用于标识整个进程（即线程组）的 PID（=TGID）。threads 指针是该进程中所有线程的链表头。

可以通过 em_find 函数从进程中获取 linux_emuldata 结构。该函数的原型如下：

其中，proc 是我们想要从中获取仿真数据结构的进程，locked 参数决定是否需要加锁。接受的值为 EMUL_DOLOCK 和 EMUL_DOUNLOCK。关于加锁的内容稍后讨论。

5.2.3. PID 混乱

由于 FreeBSD 和 Linux® 在进程 ID 和线程 ID 的概念上有所不同，我们必须以某种方式转换这种视图。我们通过 PID 混乱来实现这一点。这意味着我们在内核和用户空间之间伪造 PID（=TGID）和 TID（=PID）。大致规则是，在内核中（在 Linuxulator 中）PID = PID，而 TGID = shared → group_pid，在用户空间中，我们呈现 PID = shared → group_pid 和 TID = proc → p_pid。linux_emuldata 结构中的 PID 是一个 FreeBSD PID。

上述内容主要影响 getpid、getppid 和 gettid 系统调用。在这些调用中，我们分别使用 PID/TGID。在 child_clear_tid 和 child_set_tid 的 TID 拷贝中，我们拷贝的是 FreeBSD PID。

5.2.4. Clone 系统调用

clone 系统调用是 Linux® 中创建线程的方式。该系统调用的原型如下所示：

flags 参数告诉系统调用进程应该如何被克隆。如前所述，Linux® 可以创建共享各种资源的进程，例如两个进程可以共享文件描述符但不共享虚拟内存等。flags 参数的最后一个字节是新创建进程的退出信号。stack 参数如果非 NULL，则指示线程栈的位置；如果为 NULL，则表示我们应该进行写时复制调用进程的栈（即执行普通的操作）。parent_tidptr 参数用于在进程足够初始化但尚未可运行时，将进程 PID（即线程 ID）拷贝到指定地址。dummy 参数是因为该系统调用在 i386 架构上的调用约定非常奇怪，直接使用寄存器而不让编译器处理，从而需要一个虚拟的系统调用。child_tidptr 参数用于在进程完成 fork 操作并退出时，拷贝 PID。

该系统调用通过设置传入的标志来执行相应的操作。例如，CLONE_VM 对应于 RFMEM（虚拟内存共享）等。唯一的细节是 CLONE_FS 和 CLONE_FILES，因为 FreeBSD 不允许单独设置这些标志，所以我们通过不设置 RFFDG（复制文件描述符表和其他文件系统信息）来伪造这种行为。由于这些标志总是一起设置，所以这不会引起任何问题。设置完标志后，进程通过内部 fork1 例程进行 fork，进程被设置为不可运行，即不会加入到运行队列中。在完成 fork 后，我们可能会将新创建的进程重新父化，以模拟 CLONE_PARENT 语义。接下来是创建仿真数据。Linux® 中的线程不会向其父进程发送信号，因此我们将退出信号设置为 0 以禁用此功能。然后设置 child_set_tid 和 child_clear_tid，以便在后续代码中启用这些功能。此时，我们将 PID 拷贝到 parent_tidptr 指定的地址。进程栈的设置通过简单地重写线程帧中的 %esp 寄存器（在 amd64 上是 %rsp）来完成。接下来是为新创建的进程设置 TLS。之后，可以模拟的语义，最后将新创建的进程加入运行队列，并通过 clone

clone 系统调用实际上也用于模拟传统的和系统调用。在 2.6 内核版本中，更新后的 glibc 使用 clone 来实现和系统调用。

5.2.5. 锁

锁的实现是按子系统来进行的，因为我们不期望会有大量的竞争。这里有两个锁：emul_lock 用于保护 linux_emuldata 的操作，emul_shared_lock 用于操作 linux_emuldata_shared。emul_lock 是一个不可睡眠的阻塞互斥锁，而 emul_shared_lock 是一个可睡眠的阻塞 sx_lock。由于按子系统锁定的方式，我们可以合并一些锁，因此 em_find 提供了不锁定的访问方式。

5.3. TLS

本节讨论 TLS，即线程局部存储。

5.3.1. 线程简介

计算机科学中的线程是进程中的实体，它们可以独立于其他线程进行调度。进程中的线程共享进程范围的数据（如文件描述符等），但每个线程也有自己的栈来存储线程数据。有时需要线程特定的进程范围数据。想象一下，正在执行的线程的名称之类的东西。传统的 UNIX® 线程 API，pthread 提供了一种方法，可以通过、和来创建线程局部数据的键，并使用或来操作这些数据。可以很容易地看出，这不是实现此功能的最方便方法。因此，许多 C/C++ 编译器的生产商引入了一种更好的方式。他们定义了一个新的修饰符关键字 thread，用于指定变量是线程特定的。还开发了访问此类变量的新方法（至少在 i386 上）。pthread 方法通常在用户空间实现为一个简单的查找表。这种解决方案的性能不太好。因此，新方法使用（在 i386 上）段寄存器来访问一个存储 TLS 区域的段，这样实际访问线程变量就像附加段寄存器到地址一样，从而通过它进行寻址。段寄存器通常是 %gs 和 %fs，它们充当段选择器。每个线程都有自己存储线程局部数据的区域，并且在每次上下文切换时都必须加载该段。此方法非常快速，几乎在整个 i386 UNIX® 世界中得到了广泛应用。FreeBSD 和 Linux® 都实现了这种方法，并且取得了非常好的效果。唯一的缺点是每次上下文切换时需要重新加载段，这可能会减慢上下文切换的速度。FreeBSD 通过只使用 1 个段描述符来避免这种开销，而 Linux® 使用了 3 个。值得注意的是，几乎没有使用多个描述符的情况（只有 Wine 似乎使用了 2 个），因此 Linux® 在上下文切换时付出了不必要的代价。

5.3.2. i386 上的段

i386 架构实现了所谓的段。段是描述一块内存区域的结构。该内存区域的基址（底部）、结束地址（顶端）、类型、保护等信息。可以使用段选择器寄存器（%cs、%ds、%ss、%es、%fs、%gs）来访问该内存区域。例如，假设我们有一个基地址为 0x1234 且长度为 0x1000 的段，执行以下代码：

这将把 %edx 寄存器的内容加载到内存位置 0x1244。一些段寄存器有特殊用途，例如 %cs 用于代码段，%ss 用于栈段，但 %fs 和 %gs 通常未被使用。段通常存储在全局 GDT 表中，或者存储在本地 LDT 表中。LDT 通过 GDT 中的一个条目来访问。LDT 可以存储更多类型的段，可以为每个进程单独设置 LDT。两个表最多可以定义 8191 个条目。

5.3.3. 在 Linux® i386 上的实现

在 Linux® 中设置 TLS 主要有两种方式。可以在克隆进程时通过 clone 系统调用设置，或者可以调用 set_thread_area。当进程传递 CLONE_SETTLS 标志给 clone 时，内核期望 %esi 寄存器指向 Linux® 用户空间表示的段，该段被转换为机器表示的段，并加载到 GDT 插槽中。可以使用数字指定 GDT 插槽，也可以使用 -1，表示系统应该选择第一个空闲插槽。实际上，大多数程序只使用一个 TLS 项目，并且不关心条目的数量。我们在模拟中利用了这一点，实际上也依赖于这一点。

5.3.4. Linux® TLS 的仿真

5.3.4.1. i386

当前线程的 TLS 加载通过调用 set_thread_area 实现，而第二个进程的 TLS 加载则在 clone 中的单独块中完成。这两个函数非常相似，唯一的区别是 GDT 段的实际加载，这发生在为新创建的进程进行下一个上下文切换时，而 set_thread_area 必须直接加载该段。代码基本上是这样做的：它将 Linux® 形式的段描述符从用户空间复制出来，检查描述符的数量，但由于 FreeBSD 和 Linux® 之间的差异，我们对其进行伪造。我们只支持 6、3 和 -1 索引。6 是 Linux® 的真实数字，3 是 FreeBSD 的真实数字，-1 表示自动选择。然后我们将描述符号设置为常数 3，并将其复制到用户空间。我们依赖于用户空间进程使用来自描述符的数字，但大多数情况下这没有问题（我们从未见过不工作的情况），因为用户空间进程通常传入 1。接着我们将描述符从 Linux® 形式转换为机器无关的形式（即操作系统无关形式），并将其复制到 FreeBSD 定义的段描述符中。最后，我们加载它。我们将该描述符分配给线程的 PCB（进程控制块），并使用 load_gs 加载 %gs 段。加载必须在临界区内进行，以确保没有中断我们。CLONE_SETTLS 情况下，操作与此完全相同，只是加载操作使用 load_gs 并没有执行。此用途的段（段号 3）在 FreeBSD 进程和 Linux® 进程之间共享，因此 Linux® 仿真层不会比纯 FreeBSD 增加额外的开销。

5.3.4.2. amd64

amd64 的实现与 i386 类似，但最初没有为此目的使用 32 位段描述符（因此甚至本地 32 位 TLS 用户也无法工作），所以我们不得不添加这样的段并在每次上下文切换时实现其加载（当设置了使用 32 位的标志时）。除此之外，TLS 加载完全相同，只是段号不同，描述符格式和加载方式稍有不同。

5.4. Futex

5.4.1. 同步介绍

线程需要某种同步机制，而 POSIX® 提供了其中一些：用于互斥的互斥锁、具有偏置读写比率的读写锁以及用于信号状态变化的条件变量。有趣的是，POSIX® 线程 API 不支持信号量。同步例程的实现很大程度上依赖于我们拥有的线程支持类型。在纯 1:M（用户空间）模型中，实施可以完全在用户空间进行，因此非常快速（条件变量可能最终通过信号实现，即不是非常快速），并且很简单。在 1:1 模型中，情况也很清楚——线程必须使用内核设施进行同步（这非常慢，因为必须执行系统调用）。混合的 M:N 场景则结合了前两种方法，或者完全依赖于内核。线程同步是线程启用编程的一个关键部分，它的性能可能极大地影响结果程序。最近 FreeBSD 操作系统的基准测试表明，改进的 sx_lock 实现使 ZFS（一个重度使用 sx 的应用）性能提高了 40%，这是内核中的内容，但它清楚地表明了同步原语的性能是多么重要。

线程程序应尽量减少对锁的竞争。否则，线程只是等待锁，而没有做有用的工作。因此，编写得最好的线程程序通常表现出较少的锁竞争。

5.4.2. Futex 介绍

Linux® 实现了 1:1 线程模型，即必须使用内核同步原语。如前所述，编写得很好的线程程序锁竞争较少。因此，一个典型的序列可能是执行两次原子增加/减少互斥锁引用计数，这非常快速，如下面的示例所示：

1:1 线程模型迫使我们为这些互斥锁调用执行两个系统调用，这非常慢。

Linux® 2.6 实现的解决方案被称为 futexes。Futexes 在用户空间中检查是否发生竞争，仅在发生竞争时才调用内核原语。因此，典型情况下不会有内核干预。这使得同步原语的实现既快速又灵活。

5.4.3. Futex API

futex 系统调用的原型如下所示：

在这个例子中，uaddr 是用户空间中互斥锁的地址，op 是我们要执行的操作，其他参数根据操作的不同有不同的含义。

Futexes 实现了以下操作：

FUTEX_WAIT
FUTEX_WAKE
FUTEX_FD

5.4.3.1. FUTEX_WAIT

此操作验证在地址 uaddr 处的值是否为 val。如果不是，返回 EWOULDBLOCK，否则线程会被排队到 futex 并被挂起。如果 timeout 参数非零，它指定最大睡眠时间，否则睡眠将是无限期的。

5.4.3.2. FUTEX_WAKE

此操作会在 uaddr 处取出一个 futex，并唤醒排队在此 futex 上的 val 个 futex。

5.4.3.3. FUTEX_FD

此操作将文件描述符与给定的 futex 关联。

5.4.3.4. FUTEX_REQUEUE

此操作会从 uaddr 处的 futex 上唤醒 val 个排队的线程，并将 val2 个线程重新排队到 uaddr2 处的 futex 上。

5.4.3.5. FUTEX_CMP_REQUEUE

此操作与 FUTEX_REQUEUE 相同，但首先会检查 val3 是否等于 val。

5.4.3.6. FUTEX_WAKE_OP

该操作对 val3（其中包含某些其他值）和 uaddr 执行原子操作。然后，它唤醒 uaddr 上的 val 个 futex 线程，如果原子操作返回一个正数，则它会唤醒 uaddr2 上的 val2 个 futex 线程。

FUTEX_WAKE_OP 中实现的操作如下：

FUTEX_OP_SET
FUTEX_OP_ADD
FUTEX_OP_OR

注意
futex 原型中没有 val2 参数。val2 通过 struct timespec *timeout 参数获取，适用于操作 FUTEX_REQUEUE、FUTEX_CMP_REQUEUE 和 FUTEX_WAKE_OP。

5.4.4. Futex 在 FreeBSD 中的仿真

FreeBSD 中的 futex 仿真来源于 NetBSD，并由我们进一步扩展。它位于 linux_futex.c 和 linux_futex.h 文件中。futex 结构如下：

waiting_proc 结构如下：

5.4.4.1. futex_get / futex_put

使用 futex_get 函数获取 futex，它在 futex 的线性列表中搜索并返回找到的 futex，或者创建一个新的 futex。释放 futex 时调用 futex_put 函数，该函数减少 futex 的引用计数，如果引用计数为零，则释放该 futex。

5.4.4.2. futex_sleep

当 futex 将线程排队等待时，它会创建一个 working_proc 结构，并将该结构放入 futex 结构中的列表中，然后执行一个来挂起线程。这个睡眠可以有超时限制。在返回后（线程被唤醒或超时），working_proc 结构从列表中移除并销毁。所有这些操作都在 futex_sleep 函数中完成。如果线程是通过 futex_wake 被唤醒的，我们会设置 wp_new_futex，因此我们会在它上面睡眠。这样，实际的重新排队是在这个函数中完成的。

5.4.4.3. futex_wake

在 futex_wake 函数中唤醒在 futex 上睡眠的线程。首先，我们在此函数中模仿了 Linux® 的奇怪行为，所有操作都会唤醒 N 个线程，唯一的例外是 REQUEUE 操作，它会唤醒 N+1 个线程。但通常这不会产生任何差异，因为我们唤醒了所有线程。接下来，在循环中唤醒 n 个线程后，我们会检查是否有新的 futex 需要重新排队。如果有，我们会将最多 n2 个线程重新排队到新的 futex 上。这与 futex_sleep 协作。

5.4.4.4. futex_wake_op

FUTEX_WAKE_OP 操作比较复杂。首先，我们获取地址为 uaddr 和 uaddr2 的两个 futex，然后使用 val3 和 uaddr2 执行原子操作。然后，唤醒 val 个等待在第一个 futex 上的线程，如果原子操作条件成立，我们会唤醒 val2（即 timeout）个等待在第二个 futex 上的线程。

5.4.4.5. futex 原子操作

原子操作接受两个参数：encoded_op 和 uaddr。编码操作将操作本身、比较值、操作参数和比较参数进行编码。该操作的伪代码如下所示：

这个操作是原子执行的。首先，从 uaddr 复制数字，然后执行操作。代码处理了页错误，如果没有发生页错误，则 oldval 会与 cmparg 参数进行比较，使用指定的比较操作符。

5.4.4.6. Futex 锁定

Futex 实现使用了两种锁列表来保护 sx_lock 和全局锁（无论是 Giant 还是其他 sx_lock）。每个操作从开始到结束都在锁定状态下进行。

5.5. 各种系统调用实现

在本节中，我将描述一些较小的系统调用，这些系统调用的实现比较特殊，或者从其他角度来看，它们的实现值得关注。

5.5.1. *at 系列系统调用

在 Linux® 2.6.16 内核的开发过程中，添加了 *at 系列的系统调用。例如，openat 就是这样一个系统调用，它的工作方式与没有 at 的对应调用几乎相同，唯一的区别在于 dirfd 参数。该参数决定了给定文件的位置，在执行系统调用时，filename 参数是相对路径时，dirfd 就变得非常重要。dirfd 参数是一个目录文件描述符，或者是 AT_FDCWD。例如，openat 系统调用可以像下面这样：

这种机制的必要性在于避免在打开文件时发生竞争条件，尤其是在工作目录之外。假设一个进程包含两个线程，线程 A 和线程 B。线程 A 执行 open(./tmp/foo/bah, flags, mode) 系统调用，但在返回之前，线程 A 被抢占，接着线程 B 执行并不关心线程 A 的操作，可能会重命名或删除 /tmp/foo/ 目录。这样就会发生竞争条件。为了解决这个问题，我们可以先打开 /tmp/foo 目录，并使用它作为 dirfd，然后再执行 openat 系统调用。这样还可以实现每个线程的工作目录。

Linux® 系列的 *at 系统调用包括：linux_openat、linux_mkdirat、linux_mknodat、linux_fchownat、linux_futimesat、linux_fstatat64、linux_unlinkat、linux_renameat、linux_linkat、linux_symlinkat、linux_readlinkat、linux_fchmodat

5.5.1.1. 实现

实现是通过修改例程来完成的，给其 nameidata 结构添加了 dirfd 参数，这个参数指定路径名查找的起始点，而不是每次都使用当前工作目录。dirfd 的解析过程从文件描述符号到 vnode 的过程是在本地 *at 系统调用中完成的。当 dirfd 是 AT_FDCWD 时，nameidata 结构中的 dvp 项为 NULL，但当 dirfd 是其他数值时，我们会为这个文件描述符获取一个文件，检查它是否有效，如果有 vnode 附加到它，我们就获取这个 vnode，然后检查这个 vnode 是否是一个目录。在实际的例程中，我们简单地将 dvp 变量替换为 dp，它决定了起始点。

因此，kern_open 和 vn_open 必须做相应的修改，以支持额外的 dirfd 参数。对于这些系统调用，并没有创建兼容层，因为它们的用户不多，且用户可以容易地进行转换。这种通用的实现方式使 FreeBSD 可以实现自己的 *at 系统调用。目前，这项工作仍在讨论中。

5.5.2. Ioctl

ioctl 接口由于其通用性而变得相当脆弱。我们必须考虑到设备在 Linux® 和 FreeBSD 之间的差异，因此在执行 ioctl 仿真时必须小心。ioctl 的处理在 linux_ioctl.c 文件中实现，其中定义了 linux_ioctl 函数。该函数简单地遍历一组 ioctl 处理程序，查找能够实现给定命令的处理程序。ioctl 系统调用有三个参数：文件描述符、命令和一个参数。命令是一个 16 位数字，理论上高 8 位确定命令的类别，低 8 位则是该类别内的具体命令。仿真程序利用这个划分实现。我们为每个类别实现处理程序，比如 sound_handler 或 disk_handler。每个处理程序都有最大和最小命令的定义，用于确定使用哪个处理程序。尽管如此，这种方法也存在一些问题，因为 Linux® 并不总是按类别划分 ioctl 命令，有时不同类别的 ioctl 会被放在不应属于的类别中（例如，将 SCSI 通用 ioctl

5.5.3. 调试

每个系统调用都应该支持调试。为此，我们引入了一个小的调试基础设施。我们有一个 ldebug 功能，它会告知是否应对某个系统调用进行调试（可以通过 sysctl 设置）。为了打印调试信息，我们使用了 LMSG 和 ARGS 宏。这些宏用于调整打印的字符串，以实现统一的调试信息输出。

6. 结论

6.1. 结果

截至 2007 年 4 月，Linux® 仿真层已经能够相当好地仿真 Linux® 2.6.16 内核。剩余的问题主要集中在 futex、未完成的 *at 系列系统调用、信号传递问题、缺失的 epoll 和 inotify，以及可能存在的未发现的 BUG。尽管如此，我们已经能够运行几乎所有 FreeBSD Ports 中包含的 Linux® 程序（如 Fedora Core 4 版本的 2.6.16），并且有一些成功的初步报告表明 Fedora Core 6 版本的 2.6.16 也能运行。最近提交的 Fedora Core 6 linux_base 使得我们能够进一步测试仿真层，并为我们提供了一些线索，指出了在哪些地方我们应该投入更多精力来实现缺失的功能。

我们能够运行一些常用的应用程序，比如、以及一些游戏。有些程序在 2.6 仿真下表现不佳，但这个问题目前正在调查中，并且希望很快能修复。唯一一个已知无法工作的主要应用程序是 Linux® Java™ 开发工具包，因为它需要 epoll 功能，而这与 Linux® 2.6 内核并不直接相关。

我们希望在 FreeBSD 7.0 发布后不久默认启用 2.6.16 仿真，以便进行更广泛的测试。完成这一切后，我们就可以切换到 Fedora Core 6 linux_base，这也是我们的最终计划。

6.2. 后续工作

未来的工作应集中在修复与 futex 相关的剩余问题，完成其余 *at 系列系统调用的实现，修复信号传递问题，并可能实现 epoll 和 inotify 功能。

我们希望能够尽快无缝运行最重要的程序，这样我们就能默认切换到 2.6 仿真，并将 Fedora Core 6 设为默认的 linux_base，因为我们当前使用的 Fedora Core 4 已不再受支持。

另一个可能的目标是与 NetBSD 和 DragonflyBSD 共享我们的代码。NetBSD 对 2.6 仿真有一些支持，但还远未完成且没有经过充分测试。DragonflyBSD 已表达出将 2.6 改进移植过来的兴趣。

一般来说，随着 Linux® 的发展，我们希望能跟进其发展，实施新添加的系统调用，首先想到的是 splice。一些已实现的系统调用也存在一些优化空间，例如 mremap 等。还可以进行一些性能改进，精细化锁等。

6.3. 团队

我在这个项目中与以下人员合作（按字母顺序排列）：

John Baldwin
Konstantin Belousov
Emmanuel Dreyfus
Scot Hetzel

我想感谢所有这些人对我的建议、代码审查和一般支持。

7. 文献

Marshall Kirk McKusick - George V. Nevile-Neil. 《FreeBSD 操作系统的设计与实现》。Addison-Wesley, 2005。

vm-bhyve Wiki

提交者指南

原文地址：Committer's Guide

摘要

本文档为 FreeBSD 提交者社区提供信息。所有新的提交者在开始之前应该阅读本文档，现有的提交者也强烈建议定期回顾。

几乎所有的 FreeBSD 开发者都有一个或多个代码库的提交权限。然而，也有一些开发者没有权限，文中某些内容同样适用于他们。（例如，有些人只有权限操作问题报告数据库。）有关更多信息，请参见非提交者特定问题。

本文档也可能对希望了解 FreeBSD 项目运作方式的社区成员有所帮助。

1. 管理详细信息

连接到项目主机需要使用。有关更多信息，请参见。

有用的链接：

2. FreeBSD 的 OpenPGP 密钥

FreeBSD 项目使用符合 OpenPGP（Pretty Good Privacy）标准的加密密钥来验证提交者的身份。携带重要信息（如公钥）的消息可以使用 OpenPGP 密钥进行签名，以证明它们确实来自提交者。有关更多信息，请参见和。

2.1. 创建密钥

可以使用现有的密钥，但应先通过 documentation/tools/checkkey.sh 检查。此时，确保密钥具有 FreeBSD 用户 ID。

对于那些还没有 OpenPGP 密钥，或者需要新的密钥来符合 FreeBSD 安全要求的人，以下是如何生成一个密钥的步骤。

安装 security/gnupg。在 ~/.gnupg/gpg.conf 中输入以下内容，以设置签名和新密钥的最低默认首选项（有关更多详细信息，请参见）：
生成密钥：

① 2048 位密钥，三年有效期目前提供足够的保护（2022-10）。
② 三年的密钥有效期足够短，以使得计算能力增强后不再使用过时的密钥，但又足够长，以减少密钥管理问题。
③ 在此处使用真实姓名，最好与政府签发的 ID 上显示的姓名匹配，以便其他人更容易验证你的身份。在 Comment 部分可以输入一些帮助别人识别你的文字。

输入电子邮件地址后，会请求设置密码短语。创建安全密码短语的方法存在争议。为了避免建议一种单一的方式，以下是一些描述不同方法的链接：，，，。

保护好私钥和密码短语。如果私钥或密码短语可能已被泄露或披露，请立即通知并撤销密钥。

新密钥的提交步骤请参见 [committers-guide](crossref:committers-guide)。

3. Kerberos 和 LDAP Web 密码用于 FreeBSD 集群

FreeBSD 集群需要 Kerberos 密码来访问某些服务。由于 LDAP 在集群中代理 Kerberos，Kerberos 密码也作为 LDAP Web 密码。一些需要此密码的服务包括：

要在 FreeBSD 集群中创建一个新的 Kerberos 账户，或使用随机密码生成器重置现有账户的 Kerberos 密码：

注意
必须从 FreeBSD.org 集群外部的机器执行此操作。

也可以通过登录 freefall.FreeBSD.org 并运行以下命令手动设置 Kerberos 密码：

注意
如果之前未使用过 FreeBSD.org 集群的 Kerberos 认证服务，则会显示 Client unknown 错误。此错误意味着必须先使用上面显示的 ssh kpasswd.freebsd.org 方法初始化 Kerberos 账户。

4. 提交权限类型

FreeBSD 仓库包含多个组件，这些组件合并后支持基本操作系统源代码、文档、第三方应用 Port 基础设施和各种维护的工具。当分配 FreeBSD 提交权限时，会指定可以使用该权限的树区域。通常，权限所在的区域反映了谁授权分配该提交权限。以后可能会添加额外的权限区域：当这种情况发生时，提交者应遵循该区域的正常提交权限分配程序，向相关实体寻求批准，并可能在该区域获得一段时间的导师支持。

在开发区域权限概念之前分配的提交权限可能适用于树的许多部分。然而，常识表明，提交者如果未曾在某个区域工作过，应在提交前寻求审查，向适当的责任方寻求批准，并/或与导师合作。由于不同区域的代码维护规则不同，这既有助于提交者在不熟悉的区域工作，也有助于树上的其他人。

鼓励提交者在开发过程中寻求审查，无论工作发生在哪个区域。

4.1. 提交者在其他树区域活动的政策

所有提交者都可以修改 src/share/misc/committers-*.dot，src/usr.bin/calendar/calendars/calendar.freebsd 和 ports/astro/xearth/files。
doc 提交者可以在没有 src 提交者批准的情况下提交文档更改，例如手册页、README 文件、fortune 数据库、日历文件以及注释修复，前提是提交时遵循正常的审查和管理程序。
所有提交者都可以在拥有适当权限的非导师提交者批准的情况下对一切其他区域进行更改。导师提交者可以提供 Reviewed by 但不能提供 Approved by

4.1.1. 文档隐式（普遍）批准

某些类型的修复被文档工程团队（）授予了“普遍批准”，允许所有提交者修复这些类别的问题，而不需要文档提交者的批准或审查。

普遍批准适用于以下类型的修复：

错别字
微小修复诸如标点、URL、日期、路径和文件名的错误信息等常见错误，这些错误可能使读者困惑。

多年来，某些隐式批准已经在文档树中获得。这些最常见的情况包括：

更改 documentation/content/en/books/porters-handbook/versions/_index.adoc，主要用于 src 提交者。
更改 doc/shared/contrib-additional.adoc 维护。
所有，文档相关。

在提交前，必须进行构建测试；有关更多信息，请参见中的“概述”和“FreeBSD 文档构建过程”部分。

5. Git 入门

5.1. Git 基础

当搜索 “Git Primer” 时，会出现很多优秀的资源。Daniel Miessler 的和 Willie Willus 的都是很好的概述。Git 书籍虽然更长一些，但也非常完整：。如果你需要关于 Git 的常见问题和陷阱的指导，可以参考这个网站。最后，一篇面向计算机科学家的也对一些人解释 Git 的世界观有所帮助。

本文档假设你已经阅读过这些内容，并尽量不重复基础知识（尽管会简要介绍）。

5.2. Git 简明入门

这份入门指南的范围比旧的 Subversion 入门指南小，但应该涵盖基本的操作。

5.2.1. 范围

如果你想下载 FreeBSD，编译源代码，并通过这种方式保持更新，那么这份指南适合你。它涵盖了获取源代码、更新源代码、二分搜索，并简要讲解如何处理一些本地更改。它主要覆盖基础内容，并在需要时提供深入学习的好指引。当读者觉得基础内容不足时，其他部分的指南会涉及更高级的贡献主题。

本节的目标是突出 Git 中跟踪源代码所需的功能。假设你对 Git 有基本了解。互联网上有许多 Git 入门资料，但提供了较为全面的介绍。

5.2.2. 开发者入门

本节介绍了提交者如何推送开发者或贡献者的提交。

5.2.2.1. 日常使用

注意
以下示例中，替换 ${repo} 为所需的 FreeBSD 仓库名称：doc、ports 或 src。

克隆仓库：
然后你应该会看到官方镜像作为远程源：
配置 FreeBSD 提交者数据：在 repo.freebsd.org 上的提交钩子会检查 Commit 字段是否与 FreeBSD.org 上的提交者信息匹配。最简单的方式是通过执行 /usr/local/bin/gen-gitconfig.sh 脚本获取推荐的配置：

5.2.2.2. admin 分支

access 和 mentors 文件存储在每个仓库的孤立分支 internal/admin 中。

以下是如何将 internal/admin 分支检出到本地名为 admin 的分支的示例：

或者，你可以为 admin 分支添加一个工作树：

要在 Web 上浏览 internal/admin 分支：<a href="https://cgit.freebsd.org/$%7Brepo%7D/log/?h=internal/admin" class="bare">https://cgit.freebsd.org/${repo}/log/?h=internal/admin</a>

推送时，指定完整的 refspec：

5.2.3. 保持与 FreeBSD src 树同步

第一步：克隆树。此操作将下载整个树。下载有两种方式。大多数人会选择对仓库进行深度克隆。但是，有时你可能希望进行浅克隆。

5.2.3.1. 分支名称

FreeBSD-CURRENT 使用 main 分支。

main 是默认分支。

对于 FreeBSD-STABLE，分支名称包括 stable/12 和 stable/13。

对于 FreeBSD-RELEASE，发布工程分支名称包括 releng/12.4 和 releng/13.2。

上显示：

main 和 stable/⋯ 分支是开放的
releng/⋯ 分支在发布标签时会被冻结。

示例：

在分支上标记
在分支上标记。

5.2.3.2. 仓库

请参见获取最新的 FreeBSD 源代码获取地址。$URL 可以从该页面获取。

注意：该项目不使用子模块，因为子模块与我们的工作流程和开发模型不太契合。如何跟踪第三方应用程序的变化在其他地方有讨论，通常对普通用户来说并不重要。

5.2.3.3. 深度克隆

深度克隆会拉取整个树，以及所有历史和分支。这是最容易操作的方式。它还允许你使用 Git 的 worktree 功能，将所有活跃分支签出到不同的目录，但只有一个仓库副本。

— 这将创建一个深度克隆。branch 应该是前面列出的分支之一。如果没有指定 branch，将使用默认分支 (main)。如果没有指定 <directory>，新目录的名称将与仓库的名称（doc、ports 或 src）匹配。

如果你对历史感兴趣，计划进行本地更改，或者计划在多个分支上工作，那么你会需要一个深度克隆。它也是最容易保持更新的方式。如果你对历史有兴趣，但只在一个分支上工作并且空间有限，你还可以使用 --single-branch 仅下载一个分支（尽管一些合并提交将不会引用已合并的分支，这对某些关注详细历史的用户可能很重要）。

5.2.3.4. 浅克隆

浅克隆仅复制当前的代码，而不会下载历史。这在你需要构建特定版本的 FreeBSD 时非常有用，或者当你刚开始并计划全面跟踪树时。你还可以使用它来限制历史版本的数量。然而，下面会提到这种方法的一个重要限制。

这将克隆仓库，但只包含最新版本，其余历史不会下载。如果你之后改变主意，可以使用 git fetch --unshallow 来获取旧的历史。

警告
当你进行浅克隆时，uname 输出中将不会显示提交计数。这可能使得在发布安全公告时，判断系统是否需要更新变得更困难。

5.2.3.5. 构建

下载完成后，构建过程按照手册中的描述进行，例如：

因此，这里不再深入讨论。

如果你想构建自定义内核，FreeBSD 手册中的建议在 sys/${ARCH}/conf 下创建一个文件 MYKERNEL，针对 GENERIC 进行修改。为了让 Git 忽略 MYKERNEL，可以将它添加到 .git/info/exclude。

5.2.3.6. 更新

更新两种类型的树使用相同的命令。这会拉取自上次更新以来的所有修改。

这将更新树。在 Git 中，"fast forward" 合并是指仅需要设置新的分支指针，而不需要重新创建提交。通过始终执行快速前进合并/拉取，你将确保拥有 FreeBSD 树的准确副本。如果你希望维护本地补丁，这一点非常重要。

见下文如何管理本地更改。最简单的方法是使用 --autostash 选项与 git pull 命令一起使用，但也有更复杂的选项可用。

5.2.4. 选择特定版本

在 Git 中，git checkout 用于检出分支和特定版本。Git 的版本是长哈希值，而不是顺序编号。

当你检出特定版本时，只需在命令行中指定你想要的哈希值（git log 命令可以帮助你决定要选择哪个哈希值）：

然后你就会检出该版本。你将看到类似如下的消息：

其中最后一行是由你检出的哈希值生成的，提交消息的第一行来自该版本的提交。哈希值可以缩写为最短的唯一长度。Git 本身对于显示的数字长度并不一致。

5.2.5. 二分查找（Bisect）

有时，事情出了问题。最后一个版本工作正常，但你刚刚更新的版本不行。开发人员可能会要求你通过二分查找来追踪是哪个提交导致了回归问题。

Git 通过强大的 git bisect 命令使得二分查找变得容易。以下是如何使用它的简要概述。你可以查看或获取更多详细信息。git bisect 手册页面非常适合描述可能出错的情况，如何处理无法构建的版本，何时使用除 'good' 和 'bad' 之外的术语等，这里不再涉及。

git bisect start --first-parent 将开始二分查找过程。接下来，你需要告诉 Git 要遍历的版本范围。git bisect good XXXXXX 会告诉它工作版本，git bisect bad XXXXX 会告诉它坏版本。坏版本通常是 HEAD（即你当前检出的版本）。好的版本是你上次检出的版本。--first-parent 参数是必需的，以确保后续的 git bisect 命令不会试图检出缺少完整 FreeBSD 源代码树的供应商分支。

技巧
如果你想知道上次检出的版本，可以使用
显示我将工作树移动到 main 分支（a816…），然后从上游更新（到 5ef0…）。在这种情况下，坏版本是 HEAD（或 5ef0bd68b515），好版本是 a8163e165c5b。正如你从输出中看到的，HEAD@{1} 通常也有效，但如果在更新后做了其他操作再发现需要进行二分查找时，它并不总是可靠的。

首先设置“好”版本，然后设置“坏”版本（尽管顺序无关紧要）。当你设置坏版本时，它会提供有关过程的统计信息：

然后，你需要构建并安装该版本。如果它是好的，输入 git bisect good；如果它是坏的，输入 git bisect bad。如果该版本无法编译，输入 git bisect skip。每一步之后你都会看到类似的消息。完成后，将坏版本报告给开发人员（或自己修复 bug 并提交补丁）。git bisect reset 会结束该过程，并将你带回到你开始的地方（通常是 main 的顶端）。同样，git bisect 手册（如上所述）是处理错误或特殊情况时的良好资源。

5.2.6. 使用 GnuPG 签名提交、标签和推送

Git 知道如何签名提交、标签和推送。当你签名 Git 提交或标签时，你可以证明提交的代码来自你，并且在传输过程中没有被更改。你还可以证明是你提交了代码，而不是别人。

关于签名提交和标签的更详细文档可以在章节中找到。

签名推送的原因可以在中找到。

最好的方法是告诉 Git，你总是希望签名提交、标签和推送。你可以通过设置以下几个配置变量来实现：

注意
为了避免可能的冲突，确保给 Git 提供一个长密钥 ID。你可以通过以下命令获得长 ID：gpg --list-secret-keys --keyid-format LONG。

技巧
如果要使用特定的子密钥，而不让 GnuPG 解析为主密钥，可以在密钥后加上 !。例如，要使用子密钥 DEADBEEF 进行加密，使用 DEADBEEF!。

5.2.6.1. 验证签名

提交签名可以通过运行 git verify-commit <commit hash> 或 git log --show-signature 来验证。

标签签名可以通过 git verify-tag <tag name> 或 git tag -v <tag name> 来验证。

5.2.7. Ports 考虑事项

ports 树的操作方式相同，分支名称不同，且仓库的位置也不同。

用于浏览器的 cgit 仓库 Web 界面位于。生产 Git 仓库位于和 ssh://[email protected]/ports.git（或 :ports.git）。

GitHub 上也有一个镜像，查看以了解概况。最新分支是 main。季度分支命名为 yyyyQn，其中 yyyy 为年份，n 为季度。

5.2.7.1. 提交信息格式

在 ports 仓库中，有一个钩子帮助你编写提交信息，位于。你可以通过运行 git config --add core.hooksPath .hooks 来启用它。

提交信息应格式化如下：

重要
第一行是提交的主题，包含了更改的 port 以及提交的总结。它应该包含 50 个字符或更少。
提交信息的其余部分应该在 72 个字符的边界处换行。
应该有一个空行将它与提交信息的其余部分分开。
如果有任何元数据字段，它们应该与提交信息之间有另一个空行，以便容易区分。

5.2.8. 管理本地更改

本节讨论跟踪本地更改。如果你没有本地更改，可以跳过本节。

一个重要的事项是：所有的更改在推送之前都是本地的。与 Subversion 不同，Git 使用的是分布式模型。对于用户而言，大多数操作几乎没有区别。然而，如果你有本地更改，你可以使用相同的工具来管理它们，就像你使用相同的工具来拉取 FreeBSD 的更改一样。所有你尚未推送的更改都是本地的，可以轻松修改（如 git rebase，稍后会讨论）。

5.2.8.1. 保留本地更改

保留本地更改（尤其是微小更改）最简单的方法是使用 git stash。在最简单的形式下，你可以使用 git stash 来记录更改（这会将它们推送到暂存栈）。大多数人使用它来在更新树之前保存更改。然后，他们使用 git stash apply 将它们重新应用到树上。stash 是一个更改栈，可以通过 git stash list 查看。更多细节可以参考 git-stash 手册页 ()。

这种方法适用于你对树所做的小改动。当你有一些不那么微小的更改时，最好还是保留一个本地分支并进行 rebase。git stash 也与 git pull 命令集成：只需在命令行上添加 --autostash 即可。

5.2.8.2. 保留本地分支

与 Subversion 不同，Git 保留本地分支更为简便。在 Subversion 中，你需要合并提交并解决冲突。虽然这可以管理，但可能导致历史记录变得复杂，在上游提交时可能困难重重，或者如果你需要重新创建该过程时也很麻烦。Git 也允许合并，存在相同的问题。这是管理分支的一种方式，但它的灵活性最差。

除了合并，Git 还支持“变基”的概念，这可以避免这些问题。git rebase 命令会将一个分支的所有提交重新播放到父分支的新位置。我们将覆盖使用它时最常见的场景。

5.2.8.2.1. 创建分支

假设你想对 FreeBSD 的 ls 命令做一个更改，让它永远不显示颜色。做这个更改有很多原因，但我们用这个作为示例。FreeBSD 的 ls 命令会时不时地更新，你需要应对这些变化。幸运的是，使用 Git rebase 通常是自动完成的。

提交会让你进入编辑器描述你所做的更改。完成后，你就有了一个本地分支。按照手册中的说明，像往常一样构建并安装它。Git 与其他版本控制系统的不同之处在于，你必须显式告诉它哪些文件需要提交。我在提交命令行上选择了文件，但你也可以使用 git add 来进行提交，许多更深入的教程会涉及到这一点。

5.2.8.2.2. 更新时

当需要引入新版本时，操作几乎与没有分支时一样。你会像上面那样更新，但在更新之前会有一个额外的命令，在更新后也有一个额外的命令。以下假设你从未修改过树。开始 rebase 操作时，必须确保树是干净的（Git 要求如此）。

这会打开一个编辑器，列出所有提交。对于这个示例，不要做任何更改。这通常是在更新基线时所做的（尽管你也可以使用 Git rebase 命令来整理分支中的提交）。

完成上述操作后，你需要将 ls.c 文件中的提交从旧版本的 FreeBSD 移动到新版本中。

有时会出现合并冲突。这是正常的，不用恐慌。你只需像处理任何其他合并冲突一样处理它们。为了简化起见，我将描述一个可能出现的常见问题。完整的处理方式可以在本节末尾找到。

假设包括文件发生了变化，且进行了一个彻底的转换，改用了 terminfo，并且选项名称发生了变化。当你更新时，可能会看到如下内容：

这看起来可能很吓人。如果你打开编辑器，你会看到这是一个典型的三方合并冲突解决方法，你可能已经熟悉了来自其他源代码管理系统的冲突处理（其余的 ls.c 被省略）：

新代码在前，你的代码在后。

正确的修复方法是：在 #ifdef 之前添加 #undef COLORLS_NEW，然后删除旧的更改：

保存文件后，rebase 操作被中断，因此你需要完成它：

这告诉 Git ls.c 已经修复，继续进行 rebase 操作。如果有冲突，你会被带入编辑器来更新提交信息。如果提交信息仍然准确，只需退出编辑器。

如果你在 rebase 时遇到困难，不用恐慌。运行 git rebase --abort 会将你带回到干净的状态。重要的是，开始时树必须是未修改的。顺便说一句，前面提到的 git reflog 在这里非常有用，因为它会列出所有（中间）提交，你可以查看或检查它们，或进行 cherry-pick。

有关此主题的更多信息，参考，它提供了相当全面的介绍。对于偶尔出现但本指南中未涉及的问题，它是一个很好的资源。

5.2.8.3. 切换到另一个 FreeBSD 分支

如果你希望从 stable/12 切换到当前分支。如果你有一个深度克隆，以下命令即可：

但是，如果你有本地分支，则有一两个注意事项。首先，rebase 会重写历史，因此你可能需要采取措施保存它。其次，切换分支通常会导致更多的冲突。如果我们假设上述示例相对于 stable/12，然后切换到 main，我建议执行以下操作：

上述操作会执行以下步骤：首先检出 no-color-ls 分支。然后创建一个新名称（no-color-ls-stable-12），以防你需要返回它。接着，你将进行 rebase，并将其应用到 main 分支上。这会查找所有当前 no-color-ls 分支中的提交（直到与 stable/12 分支合并的地方），然后将它们重新应用到 main 分支上，从而在 main 分支上创建一个新的 no-color-ls 分支（这就是为什么我让你创建一个占位名称）。

5.3. MFC（从当前合并）流程

5.3.1. 概述

MFC 工作流可以总结为 git cherry-pick -x 加 git commit --amend 来调整提交信息。对于多个提交，使用 git rebase -i 将它们压缩到一起并编辑提交信息。

5.3.2. 单个提交 MFC

对于 MFC 提交，例如供应商导入，你需要为 cherry-pick 操作指定一个父提交。通常情况下，这将是你从中进行 cherry-pick 的分支的“第一个父”：

如果出现问题，你需要通过 git cherry-pick --abort 中止 cherry-pick 操作，或者修复问题后执行 git cherry-pick --continue。

完成 cherry-pick 后，使用 git push 推送。如果由于提交竞争失败而导致错误，使用 git pull --rebase 并重新尝试推送。

5.3.3. MFC 到 RELENG 分支

向需要批准的分支执行 MFC 时需要更加小心。无论是典型的合并操作还是特殊的直接提交，过程相同：

首先将合并或直接提交到适当的 stable/X 分支，然后再合并到 releng/X.Y 分支。
使用 stable/X 分支中的哈希值执行 MFC 到 releng/X.Y 分支。

如果忘记添加 Approved by: 行，可以通过 git commit --amend 编辑提交信息，然后再推送更改。

5.3.4. 多个提交 MFC

如果由于提交竞争失败而导致推送失败，执行 rebase 并重新尝试：

MFC 完成后，你可以删除临时分支：

5.3.5. MFC 供应商导入

供应商导入是唯一会在 main 分支中创建合并提交的操作。将合并提交 cherry-pick 到 stable/XX 时会遇到额外的困难，因为合并提交有两个父提交。通常，你会希望选择第一个父提交的差异，因为它是与 main 的差异（尽管也可能有一些例外）。

通常这就是你需要的命令。这将告诉 cherry-pick 应用正确的差异。

有一些情况（希望是少数）可能是 main 分支被转换脚本反向合并了。如果是这种情况（虽然我们还没有遇到过这种情况），你应该将上述命令中的 -m 1 改为 -m 2，以获取正确的父提交。操作如下：

--abort 会清理第一次失败的尝试。

5.3.6. 重新执行 MFC

如果执行了 MFC 操作并且结果非常糟糕，你希望重新开始，最简单的方式是使用 git reset --hard，如下所示：

不过，如果你希望保留某些提交，而舍弃其他提交，使用 git rebase -i 更为合适。

5.3.7. MFC 时的注意事项

在将源代码提交到 stable 和 releng 分支时，我们有以下目标：

清晰地区分直接提交与从其他分支合并的提交。
避免在 stable 和 releng 分支中引入已知的破坏性更改。
允许开发者确定哪些更改已经从一个分支合并到另一个分支，哪些没有。

在 Subversion 中，我们使用以下做法来实现这些目标：

使用 MFC 和 MFS 标签来标记从其他分支合并的提交。
在合并更改时，将修复提交压缩到主要提交中。
记录合并信息，以便 svn mergeinfo --show-revs 可以工作。

在 Git 中，我们需要采用不同的策略来实现相同的目标。本文件旨在定义在使用 Git 合并源代码提交时的最佳实践，以实现这些目标。一般来说，我们更倾向于使用 Git 的原生支持来实现这些目标，而不是强制执行基于 Subversion 模型的做法。

一项通用说明：由于 Git 与 Subversion 存在技术差异，我们将不会在 stable 或 releng 分支中使用 Git“合并提交”（通过 git merge 创建的提交）。相反，当本文件提到“合并提交”时，它指的是最初在 main 分支上创建的提交，并通过某种方式使用 git cherry-pick 被复制或“落地”到 stable 分支，或者从 stable 分支复制到 releng 分支的提交。

5.3.8. 查找合适的哈希以进行 MFC

Git 提供了内建支持，使用 git cherry 和 git log --cherry 命令。这些命令比较提交的原始差异（但不比较其他元数据，如日志消息），以确定两个提交是否相同。当每个提交从 main 分支单独合并到稳定分支时，这些命令非常有效，但如果从 main 分支合并多个提交并将它们合并为一个提交到稳定分支时，这种方法就会失效。为了绕过这些困难，项目广泛使用 git cherry-pick -x 保留所有行，并且正在开发自动化工具以利用这一点。

5.3.9. 提交消息标准

5.3.9.1. 标记 MFC

项目采用了以下标记 MFC 的做法：

使用 git cherry-pick 的 -x 标志。这会在提交消息中添加一行，包含合并时原始提交的哈希。由于这是 Git 直接添加的，提交者在合并时不需要手动编辑提交日志。

当合并多个提交时，保留所有的 cherry picked from 行。

5.3.9.2. 是否修剪元数据？

在 Subversion（甚至 CVS）中，并未清晰记录如何为 MFC 提交格式化日志消息中的元数据。应该保留原始提交的元数据不变，还是应该修改以反映 MFC 提交本身的信息？

历史做法有所不同，尽管某些差异与字段有关。例如，涉及 PR 的 MFC 通常会在 MFC 中包含 PR 字段，以便将 MFC 提交包含在 bug 跟踪器的审核历史中。其他字段则不太明确。例如，Phabricator 显示的是最后一个提交与评审标签相关的 diff，因此如果在 MFC 中包含 Phabricator URL，会替换主提交为已落地的提交。审查人列表也不明确。如果审查人批准了对 main 的更改，这是否意味着他们也批准了 MFC 提交？如果是完全相同的代码或者仅做了微小修改，那么答案可能是肯定的。但对于更复杂的修改来说，这显然不成立。即使代码完全相同，若提交没有冲突但引入了 ABI 更改，审查人可能会因为 ABI 改变而批准 main 提交，但可能不会批准相同的提交。对此，必须根据具体情况做出判断，直到能够就清晰的指南达成一致。

对于由 re@ 管理的 MFC，增加了新的元数据字段，如 Approved by 标签，用于批准的提交。这些新元数据必须通过 git commit --amend 或类似命令添加，在原始提交经过审核和批准后添加。我们也可能希望将一些元数据字段保留在 MFC 提交中，比如 Phabricator URL，以便将来由 re@ 使用。

保留现有元数据提供了一种非常简单的工作流。开发者使用 git cherry-pick -x，无需编辑日志消息。

如果我们选择调整 MFC 中的元数据，开发者将需要显式地通过使用 git cherry-pick --edit 或 git commit --amend 来编辑日志消息。然而，与 SVN 相比，至少现有的提交消息可以预先填充，并且可以在不重新输入整个提交消息的情况下添加或删除元数据字段。

总的来说，开发者可能需要为非平凡的 MFC 提交整理其提交消息。

5.4. 使用 Git 进行供应商导入

本节详细介绍了使用 Git 进行供应商导入的过程。

5.4.1. 分支命名约定

所有供应商分支和标签都以 vendor/ 开头。这些分支和标签默认是可见的。

注意
本章遵循的约定是，freebsd 为官方 FreeBSD Git 仓库的源名称。如果你使用不同的约定，请在以下示例中将 freebsd 替换为你使用的名称。

我们将以更新 NetBSD 的 mtree 为例，说明其在我们树中的供应商分支。该供应商分支为 vendor/NetBSD/mtree。

5.4.2. 更新旧的供应商导入

供应商树通常只包含适合 FreeBSD 的第三方软件子集。这些树通常比 FreeBSD 树要小得多。因此，Git 工作树非常小且快速，且是推荐使用的方法。确保所选目录（例如 ../mtree）尚不存在。

5.4.3. 更新供应商分支中的源代码

准备一个完整、干净的供应商源代码树。导入所有内容，但只合并所需的部分。

以下示例假设 NetBSD 源代码已从其 GitHub 镜像克隆到 ~/git/NetBSD。请注意，“上游”可能已经添加或删除了文件，因此我们要确保删除操作也被传播。[net/rsync](https://cgit.freebsd.org/ports/tree/net/rsync/) 通常已安装，因此我将使用它。

至关重要的是验证你正在导入的源代码来自可信的来源。许多开源项目使用加密签名来签署代码更改、Git 标签和/或源代码 tarball。始终验证这些签名，并使用诸如 jail、chroot 等隔离机制，结合一个专用的、非特权用户账户，该账户与你日常使用的账户不同（有关详细信息，请参阅下文的“更新 FreeBSD 源树”部分），直到你确信所导入的源代码是安全的。跟踪上游开发并偶尔检查上游代码更改，有助于提高代码质量并使所有参与者受益。导入到供应商区域之前，检查 git diff 结果也是一个好主意。

始终运行 git diff 和 git status 命令，并仔细检查结果。如有疑问，使用 git annotate 查看供应商分支或上游 Git 仓库，了解是谁做了更改以及为什么。

上面的示例中我们使用了 -m 来说明，但你应该在编辑器中撰写适当的消息（使用提交消息模板）。

同样，重要的是使用 git tag -a 创建一个注解标签，否则推送将被拒绝。只有注解标签才能被推送。注解标签使你有机会输入提交消息，输入你导入的版本以及该版本中的任何重要新特性或修复。

5.4.4. 更新 FreeBSD 副本

此时，你可以将导入的供应商代码推送到我们的仓库中的 vendor 分支。

--follow-tags 告诉 git push 也推送与本地提交版本相关联的标签。

5.4.5. 更新 FreeBSD 源树

现在你需要更新 FreeBSD 中的 mtree。源代码位于 contrib/mtree 目录下，因为它是上游软件。

有时，我们可能需要对贡献的代码进行更改，以更好地满足 FreeBSD 的需求。尽可能地，请尝试将本地更改贡献回上游项目，这有助于它们更好地支持 FreeBSD，也节省了将来导入更新时解决冲突的时间。

这将生成一个子树合并提交，将 contrib/mtree 与本地的 vendor/NetBSD/mtree 分支合并。检查合并结果的 diff 和上游分支的内容。如果合并减少了本地更改，仅保留了空行或缩进更改等琐碎差异，请尝试修改本地更改以减少与上游的差异，或尝试将剩余的更改贡献回上游项目。如果有冲突，你需要在提交之前解决它们。在合并提交消息中包含有关合并更改的详细信息。

一些开源软件包含 configure 脚本，用于生成定义如何构建代码的文件；通常，这些生成的文件（如 config.h）应在导入过程中更新。在执行此操作时，始终记住这些脚本是在当前用户的凭据下运行的可执行代码。此过程应始终在隔离环境中运行，理想情况下是在没有网络访问权限的 jail 内，并使用非特权账户；或者，至少使用与你日常使用的账户不同的专用账户，这样可以最大限度地减少遇到可能导致数据丢失或更严重的恶意代码的风险。使用隔离的 jail 还可以防止 configure 脚本检测到本地安装的软件包，从而避免出现意外结果。

在测试你的更改时，首先在 chroot 或 jailed 环境中运行，甚至可以先在虚拟机中测试，尤其是对于内核或库的修改。这种方法有助于防止与工作环境发生不良交互。对于许多基本系统组件都使用的库修改，这尤其有益。

5.4.6. 将你的更改与最新的 FreeBSD 源树重新基准化

由于当前的政策建议避免使用合并，如果在你有机会推送之前，FreeBSD 的 main 已经向前移动，那么你将不得不重新执行合并。

常规的 git rebase 或 git pull --rebase 无法像合并提交那样重新基准化，因此你需要重新创建该提交。

以下步骤应帮助你轻松地重新创建合并提交，就好像 git rebase --merge-commits 正常工作一样：

进入仓库的顶层目录
创建一个包含已合并树内容的旁支 XXX
更新旁支 XXX，使其与 FreeBSD 的 main 分支合并并保持最新。

以下是使用 mtree 示例时，执行上述操作的命令（# 后面的部分是注释，用于帮助将命令与上面的描述对应起来）：

注意：如果提交出现问题，你可以通过重新执行创建分支的命令，并使用 -B 参数来重置 YYY 分支，以便从头开始：

5.4.7. 推送更改

当你认为更改已经准备好时，可以将其推送到 GitHub 或 GitLab 上的 fork 以供他人审查。Git 的一个优点是它允许你发布草稿供其他人查看。虽然 Phabricator 很适合内容审查，但发布更新后的供应商分支和合并提交使得其他人可以查看详细信息，因为这些更改最终将出现在仓库中。

经过审查后，当你确信这是一个好的更改时，你可以将其推送到 FreeBSD 仓库：

注意：我使用 XXX 和 YYY 是为了使它们显得明显，它们是糟糕的名称，应该只在你的机器上使用。如果你将这样的名称用于其他工作，那么你需要选择不同的名称，否则可能会丢失其他工作。这些名称并没有什么神奇之处。上游不会允许你推送它们，但无论如何，请注意上述命令。某些命令的语法与常规用法略有不同，而这种不同的行为对这个食谱的成功至关重要。

5.4.8. 如果需要重做操作

如果你尝试在上一节中进行推送并且失败，那么你应执行以下操作来“重做”事情。这个序列会保持提交消息始终为 XXX~1，以便简化提交过程。

然后，像之前一样检查并推送。

5.5. 创建一个新的供应商分支

有多种方式可以创建一个新的供应商分支。推荐的方式是创建一个新的仓库，然后将其与 FreeBSD 合并。如果要将 glorbnitz 导入到 FreeBSD 树中，版本为 3.1415。为了简单起见，我们不对该版本进行修剪。它是一个简单的用户命令，可以将 nitz 设备置于不同的魔法 glorb 状态，且其足够小，修剪不会节省太多空间。

5.5.1. 创建仓库

此时，你已创建了一个新的仓库，所有新的提交都将在 vendor/glorbnitz 分支上进行。

如果你更熟悉，可以直接在 FreeBSD 克隆中执行此操作，使用 git checkout --orphan vendor/glorbnitz。

5.5.2. 将源代码复制进去

由于这是一个新的导入，你可以直接使用 cp、tar 或甚至 rsync 将源代码复制进去，如上所示。假设没有点文件，我们将添加所有内容。

此时，你应该有一个干净的 glorbnitz 复制，准备提交。

如上所示，我使用了 -m 选项以简化操作，但实际上你应该创建一个解释什么是 Glorb，以及为什么要使用 Nitz 来获得它的提交消息。并非每个人都会知道，因此在实际提交时，你应该遵循部分，而不是模仿这里使用的简短风格。

5.5.3. 现在将其导入到我们的仓库

现在，你需要将分支导入到我们的仓库。

请注意，vendor/glorbnitz 分支已添加到仓库中。此时，/some/where/glorbnitz 可以删除，如果你愿意的话。它只是为了达到某个目的而存在。

5.5.4. 打标签并推送

从这里开始的步骤与更新供应商分支时类似，只是没有更新供应商分支的步骤。

“正确”意味着：

所有正确的文件都存在
没有错误的文件存在
供应商分支指向一个合理的地方
标签看起来很好，且是注释的

5.5.5. 最终将其合并到主树中

这里“正常”意味着：

所有正确的文件，并且没有错误的文件，已合并到 contrib/glorbnitz 中。
树中没有其他更改。
提交消息看起来。应该包含自上次向 FreeBSD main 分支合并以来的更改总结以及任何警告。

注意
这还没有将 glorbnitz 连接到构建中。如何做到这一点取决于被导入的软件，超出了本教程的范围。

5.5.5.1. 保持更新

随着时间的推移，现在是更新树以包含最新的上游更改的时刻。切换到 main 分支时，确保没有差异。在执行以下操作之前，最好先将更改提交到一个分支（或使用 git stash）。

如果你习惯使用 git pull，我们强烈建议使用 --ff-only 选项，并将其设置为默认选项。或者，如果你在 main 分支上有暂存的更改，git pull --rebase 会更有用。

如果你只希望此设置应用于当前仓库，可能需要省略 --global。

有一个常见的陷阱，git pull 组合命令会尝试执行合并，这有时会创建一个以前不存在的合并提交。这个过程可能更难恢复。

我们也推荐使用更长的命令形式。

这些命令会将你的树重置为 main 分支，然后从你最初拉取的源更新它。在执行此操作之前，切换到 main 非常重要，这样它才能向前推进。现在，是时候将更改推进：

这将弹出一个交互式屏幕，你可以在其中更改默认设置。现在，直接退出编辑器即可。一切应该顺利应用。如果没有，你需要解决冲突。可以帮助你解决这个问题。

5.5.5.2. 将更改推送到上游

首先，确保推送 URL 已正确配置为上游仓库。

然后，验证你的用户名和电子邮件是否配置正确。我们要求它们与 FreeBSD 集群中的 passwd 条目完全匹配。

在 freefall.freebsd.org 上使用

可以获得你可以直接使用的配方，前提是 /usr/local/bin 在 PATH 中。

下面的命令会将 working 分支合并到上游的 main 分支。重要的是在执行此操作之前，你要确保你的更改完全符合 FreeBSD 源仓库中的要求。这种语法会将 working 分支推送到 main，将 main 分支推进。只有当这导致 main 的线性更改时（例如，没有合并）时，你才可以执行此操作。

如果由于提交竞争导致你的推送被拒绝，请在重新尝试之前重新基准化你的分支：

5.5.5.3. 将更改推送到上游（替代方法）

有些人发现，在推送到远程仓库之前，将更改合并到本地 main 分支上会更容易。此外，git arc stage 会将更改从分支移到本地 main，当你只需要做分支的子集时。操作与之前部分类似：

如果你输了比赛，那么再试一次，尝试以下操作：

这些命令会获取最新的 freebsd/main，然后将本地的 main 更改基准化到其上，这是当你丢失提交竞争时所需要的。注意：使用此技巧无法合并供应商分支的提交。

5.5.5.4. 查找 Subversion 修订版

你需要确保已获取备注（有关详细信息，请参阅）。获取这些备注后，它们将在 git log 命令中显示，如下所示：

如果你有特定版本，可以使用以下构造命令：

这样可以找到特定的修订版。commit 后的十六进制数字是你可以用来引用此提交的哈希值。

5.6. Git 常见问题

本节提供了许多可能会经常出现的问题的针对性答案，适用于用户和开发人员。

注意
我们使用 FreeBSD 仓库的常规约定，源为 freebsd，而不是默认的 origin，以便让人们将其用于自己的开发，并最小化将更改错误推送到错误仓库的风险。

5.6.1. 用户

5.6.1.1. 如何用一个仓库副本跟踪 -current 和 -stable？

Q: 尽管磁盘空间不是大问题，但使用仓库副本更高效。在 SVN 镜像中，我可以从同一个仓库签出多个树。如何用 Git 来实现？

A: 你可以使用 Git 工作树。这里有多种方法可以做到，但最简单的方法是使用克隆来跟踪 -current，并使用工作树来跟踪稳定版本。虽然使用“裸仓库”作为一种应对方法已被提出，但它更为复杂，且不在此文档中介绍。

首先，你需要克隆 FreeBSD 仓库，以下示例中将其克隆到 freebsd-current 以减少混淆。$URL 是适合你的镜像源：

克隆完成后，你可以简单地从中创建一个工作树：

这将把 stable/12 签出到名为 freebsd-stable-12 的目录，它与 freebsd-current 目录平行。创建后，更新工作树的方式与预期类似：

我建议使用 --ff-only，因为它更安全，可以避免意外进入“合并噩梦”，其中树中会有额外的更改，从而迫使你进行复杂的合并，而不是简单的合并。

这里有一篇，可以更深入地探讨此话题。

5.6.2. 开发人员

5.6.2.1. 哎呀！我不小心提交到了 main 分支，而不是另一个分支

Q: 有时，我会犯错，不小心提交到了 main 分支。我该怎么办？

A: 首先，不要惊慌。

其次，不要推送。实际上，如果你没有推送，几乎所有问题都可以解决。本节的所有答案假设没有进行推送。

以下解答假设你已经提交到了 main 分支，并且想创建一个名为 issue 的分支：

5.6.2.2. 哎呀！我不小心提交到了错误的分支

Q: 我正在 wilma 分支上开发一个功能，但不小心在 wilma 中提交了与 fred 分支相关的更改。我该怎么办？

A: 这个解答与之前类似，不过是使用了 cherry-pick。假设 wilma 分支上只有一次提交，但这种方法也可以推广到更复杂的情况。假设这是 wilma 上的最后一次提交（因此使用 wilma 在 git cherry-pick 命令中），但这也可以推广。

Git 专家通常会先将 wilma 分支回退 1 次提交，然后切换到 fred，然后使用 git reflog 查看被删除的提交是什么，再将其 cherry-pick 到 fred 分支。

Q: 如果我想将一些更改提交到 main，但出于某些原因保留其余的更改在 wilma 中，怎么办？

A: 上面相同的技巧也适用于你想将当前分支的一部分更改提交到 main，而保留分支其余部分（例如发现了一个不相关的拼写错误或修复了一个偶然的 bug）。你可以将这些更改 cherry-pick 到 main，然后推送到上游仓库。完成后，清理工作也非常简单：只需要使用 git rebase -i。Git 会注意到你已经这样做了，并自动跳过相同的更改（即使你更改了提交消息或稍微调整了提交）。你无需返回 wilma 分支来调整它：只需执行 rebase 操作即可！

Q: 我想将 wilma 分支的一些更改拆分到 fred 分支中，怎么做？

A: 更一般的答案与之前相同。你需要先检出或创建 fred 分支，逐一 cherry-pick 需要的更改，然后对 wilma 分支进行 rebase，移除你已 cherry-pick 到 fred 分支的更改。使用 git rebase -i main wilma 会打开编辑器，你可以删除与 fred 分支中已复制提交对应的 pick 行。如果一切顺利，且没有冲突，那么操作完成。如果遇到冲突，你需要在过程中解决它们。

另一种做法是先检出 wilma，然后创建 fred 分支，使其指向树中的相同位置。然后，你可以对这两个分支执行 git rebase -i，在编辑器中保留要放入 fred 或 wilma 分支的更改 pick 行，删除其他行。一些人会在开始拆分之前创建一个名为 pre-split 的标签/分支，以防拆分过程中出现问题。万一需要撤销拆分操作，可以执行以下步骤：

最后一步是可选的。如果你打算重新尝试拆分，你可以省略此步骤。

Q: 但我在阅读时没有看到你的建议，没创建分支，现在 fred 和 wilma 已经完全搞乱了。我该如何找回 wilma 在开始之前的状态？我不知道我做了多少次更改。

A: 一切尚未丢失。只要不久之前做的更改太多（几百次提交的话），你依然可以找回之前的状态。

假设我创建了一个 wilma 分支并提交了一些更改，然后决定将其拆分成 fred 和 wilma。如果在拆分过程中没有出现问题，一切应该顺利。但假设有些不正常的事情发生了，你可以使用 git reflog 来查看做过的更改：

在这里，我们可以看到做过的更改。你可以通过这些信息找出哪里出错了。我想指出几点：首先，HEAD@{X} 是一个“提交点”，因此可以将它作为命令的参数。虽然如果该命令对仓库做了提交操作，X 的数字会发生变化。你也可以使用哈希值（第一列）。

接下来，“Encourage contributions” 是我在决定拆分之前提交到 wilma 的最后一次提交。你也可以看到这个哈希值在我创建 fred 分支时也出现了。我从 fred 开始执行 rebase 操作，可以看到“开始”步骤、每个步骤以及完成步骤。虽然我们在这里不需要这个信息，但它可以帮助你清楚了解发生了什么。幸运的是，修复这个问题的方法是按照之前解答中的步骤执行，但使用哈希值 869cbd3 代替 pre-split。虽然这种方法看起来有点冗长，但由于你是一次处理一件事，记住它很容易。你还可以将操作堆叠在一起：

这样，你就准备好重新尝试了。使用 checkout -B 并指定哈希值结合了检出和为其创建分支的操作。使用 -B 而非 -b 会强制移动已经存在的分支。这两种方式都可以使用，这正是 Git 强大（也有时让人头疼）的原因之一。我更倾向于使用 git checkout -B xxxx hash 来避免先检出哈希值后再创建/移动分支，因为那样会出现令人不安的“分离头”状态警告：

这将产生相同的效果，但我需要阅读更多内容，而“分离头”状态不是我喜欢思考的图像。

5.6.2.4. 混合和匹配分支

问：我有两个分支 worker 和 async，我想把它们合并成一个名为 feature 的分支，同时保留两个分支中的提交记录，应该怎么做？

答：这可以通过 cherry pick 来实现。

现在你就有了一个新的分支 feature。这个分支结合了两个分支的提交。你可以通过 git rebase 进一步修改它。

问：我有一个名为 driver 的分支，我想将其拆分为 kernel 和 userland，这样我就可以分别独立演进它们，并在每个分支准备好时提交它们。

答：这需要一些准备工作，但 git rebase 可以完成大部分工作。

现在你有了两个相同的分支。接下来是将提交拆分到这两个分支中的过程。我们假设 driver 中的所有提交都进入 kernel 或 userland，而不是两个分支。

在编辑器中，保留你想要的提交（通过 p 或 pick 行），删除不需要的提交（这看起来很吓人，但如果出错了，你可以通过 driver 分支重新开始，因为你还没有修改它）。

对 userland 分支做同样的事。

问：哇！我按照上述操作了，但忘记了 kernel 分支的一个提交。如何恢复这个提交？

答：你可以通过 driver 分支找到缺失提交的哈希，并将其 cherry-pick 到 kernel 分支。

问：好的。我的情况和上面一样，但我的提交都混在一起了。我需要将一个提交的部分内容放到一个分支，剩余部分放到另一个分支。事实上，我有好几个这样的提交。你提到的选择提交的 rebase 方法看起来有点棘手。

答：在这种情况下，你最好先整理原始分支，将提交拆分开来，然后使用上述方法将分支拆分。

假设现在只有一个干净的提交。你可以使用 git rebase 中的 edit 选项，或者直接在当前提交上使用该操作。无论哪种方式，步骤都一样。首先，我们需要备份一个提交，并将更改留在工作区：

注意：此时不要加上 --hard，因为那样会将工作区的更改删除。

现在，如果你幸运的话，需要拆分的更改完全是基于文件的。在这种情况下，你可以像平常一样使用 git add 来将每组文件提交一次。注意：当你执行重置操作时，提交消息会丢失，所以如果需要保存消息，应该先保存一份副本（不过，你可以通过 git log $HASH 恢复提交消息）。

如果不幸运，可能需要将文件拆分开来。这时你可以使用以下工具逐个处理文件：

这将逐步显示差异，并提示你是否包含或排除每个变更块。完成后，使用 git commit 提交剩余的更改。如果有多个文件需要处理，你可以多次运行这个命令，通常我发现一次处理一个文件并使用 git rebase -i 将相关提交合并会更简单些。

5.6.3. 克隆和镜像

问：我想镜像整个 Git 仓库，怎么做？

答：如果你只是想镜像仓库，可以使用以下命令：

但如果你希望用它做其他事情，那么你会需要重新克隆仓库。

首先，这会创建一个 "bare 仓库"，即只有仓库数据库，而没有已检出的工作区。这对于镜像非常好，但对于日常工作来说就不太合适了。你可以通过 git worktree 来解决这个问题：

但是，如果你不打算将镜像用于进一步的本地克隆，那它就不太适合了。

第二个缺点是，Git 通常会重写上游的引用（如分支名、标签等），使得你的本地引用可以独立于上游发展。这意味着，如果你在该仓库中提交更改，除非是私人项目的分支，否则你会丢失更改。

问：那我应该怎么办？

答：你可以将所有上游仓库的引用放入本地仓库的私有命名空间。Git 是通过 'refspec' 来克隆所有内容的，默认的 refspec 是：

这意味着它只会获取分支的引用。

然而，FreeBSD 仓库包含了很多其他内容。你可以为每个引用命名空间添加显式的 refspec，或者选择获取所有内容。要设置你的仓库来执行这一操作：

这会将上游仓库中的所有内容放入本地仓库的 refs/freebsd/ 命名空间。请注意，这也会获取所有未转换的 vendor 分支，并且它们关联的引用数量非常庞大。

你需要使用完整的名称来引用这些 "refs"，因为它们不在 Git 的常规命名空间中。

上述命令会查看 zlib 的 vendor 分支日志，从 1.2.10 开始。

5.7. 与他人合作

在像 FreeBSD 这样的大型项目中，良好的合作能力是软件开发的关键之一。在 FreeBSD 项目的 Git 仓库中，当前不允许用户创建的分支被推送到仓库中。因此，如果你希望与他人共享你的更改，你必须使用其他机制，例如托管的 GitLab 或 GitHub 来共享用户生成的分支。

以下是如何创建一个基于 FreeBSD main 分支的用户生成分支，并将其推送到 GitHub 的步骤。

在开始之前，确保你的本地 Git 仓库是最新的，并且设置了正确的远程源。

第一步是按照这些在 GitHub 上创建一个的 fork。这个 fork 的目标应该是你的个人 GitHub 账户（比如我的是 gvnn3）。

然后，在本地系统上添加一个指向你 fork 的远程源：

现在，你可以创建一个分支。

在你的分支中进行任何修改。完成后，进行构建和测试，当你准备好与他人合作时，就可以将你的更改推送到托管的分支了。在推送之前，你需要设置适当的上游分支，因为第一次尝试推送到 GitHub 时，Git 会提示你：

按照 Git 的建议设置推送上游分支后，推送就会成功：

之后对同一分支的更改将默认正确推送：

此时，你的工作已推送到 GitHub 上的分支，并且你可以与其他协作者共享该链接。

5.8. 合并 GitHub Pull 请求

本节介绍了如何将提交到 FreeBSD GitHub 镜像库的 GitHub Pull 请求合并到 FreeBSD 仓库。虽然这不是提交补丁的官方方式，但有时通过这种方式提交的修复非常有效，直接将它们合并到提交者的树上，再从那里推送到 FreeBSD 的树上是最简单的做法。类似的步骤也可以用于将其他仓库的分支合并进来。在合并他人的 Pull 请求时，特别需要小心检查所有更改，确保它们和提交时所展示的一致。

开始之前，确保本地 Git 仓库是最新的，并且正确设置了源仓库。另外，请确保本地仓库有以下远程仓库设置：

Pull 请求通常很简单：请求只包含一个提交。在这种情况下，可以使用简化的方法，尽管上一节中介绍的方法也可以使用。这里，创建一个分支，将更改 cherry-pick（挑选提交），调整提交信息，进行测试后再推送。示例中使用了 staging 分支，但它可以是任何名称。当有多个提交时，特别是需要进行小调整时，使用 git rebase -i 比 git cherry-pick 更加有效。以下是相关命令的概述：

创建一个分支；
cherry-pick Pull 请求中的更改；
测试它；
调整提交信息；

对于复杂的 Pull 请求，如果有多个提交并且有冲突，可以按照以下步骤进行：

检出 Pull 请求 git checkout github/pull/XXX
创建一个分支进行 rebase git checkout -b staging
将 staging 分支 rebase 到最新的 main

这些步骤同样适用于将其他地方开发的分支合并到本地树并提交。

完成 Pull 请求后，使用 GitHub 的 Web 界面关闭它。如果你的 github 原始库是通过 https:// 配置的，那么你只需要 GitHub 账户来关闭该 Pull 请求。

6. 版本控制历史

项目已经迁移到。

FreeBSD 源代码仓库在 2008 年 5 月 31 日从 CVS 转移到 Subversion。第一个正式的 SVN 提交是 r179447。源代码仓库在 2020 年 12 月 23 日从 Subversion 转移到 Git。最后一个正式的 SVN 提交是 r368820，第一个正式的 Git 提交哈希是 5ef5f51d2bef80b0ede9b10ad5b0e9440b60518c。

FreeBSD doc/www 仓库在 2012 年 5 月 19 日从 CVS 转移到 Subversion。第一个正式的 SVN 提交是 r38821。文档仓库在 2020 年 12 月 8 日从 Subversion 转移到 Git。最后一个 SVN 提交是 r54737，第一个正式的 Git 提交哈希是 3be01a475855e7511ad755b2defd2e0da5d58bbe。

FreeBSD ports 仓库在 2012 年 7 月 14 日从 CVS 转移到 Subversion。第一个正式的 SVN 提交是 r300894。Ports 仓库在 2021 年 4 月 6 日从 Subversion 转移到 Git。最后一个 SVN 提交是 r569609，第一个正式的 Git 提交哈希是 ed8d3eda309dd863fb66e04bccaa513eee255cbf。

7. 设置、约定与传统

作为一名新开发者，需要做一些准备工作。以下步骤仅适用于已获得提交权限的开发者。如果你没有提交权限，必须由导师来执行这些步骤。

7.1. 对于新提交者

已获得 FreeBSD 仓库提交权限的开发者，必须遵循以下步骤。

在提交每个更改之前，先获得导师的批准！
所有 src 的提交首先必须提交到 FreeBSD-CURRENT，然后才能合并到 FreeBSD-STABLE。FreeBSD-STABLE 分支必须保持与该分支早期版本的 ABI 和 API 兼容性。不要合并破坏这种兼容性的更改。

新提交者步骤

添加作者条目doc/shared/authors.adoc - 添加作者条目。后续步骤依赖于此条目，缺少此步骤会导致 doc/ 构建失败。这是一个相对简单的任务，但仍然是测试版本控制技能的好方法。
更新开发者和贡献者列表doc/shared/contrib-committers.adoc - 添加一条记录，这样就能在的“开发者”部分中看到它。条目按姓氏排序。
doc/shared/contrib-additional.adoc - 删除记录。条目按名字排序。
添加新闻项doc/website/data/en/news/news.toml

7.2. 对所有人的要求

向其他开发者介绍自己，否则没人知道你是谁，也不知道你在 FreeBSD 中的工作内容。介绍不需要是详尽的传记，只需要写一两段关于你是谁、你计划在 FreeBSD 中做什么以及你的导师是谁的内容。将此邮件发送到 FreeBSD 开发者邮件列表，这样你就可以开始了！
登录到 freefall.FreeBSD.org 并创建一个 /var/forward/user 文件（其中 user 是你的用户名），文件内容包含你希望将邮件转发到的电子邮件地址，邮件地址格式为 你的用户名@FreeBSD.org。此邮件包括所有提交消息以及任何发送到 FreeBSD 提交者邮件列表和 FreeBSD 开发者邮件列表的邮件。由于 freefall 上有些非常大的邮箱可能会在空间不足时未经警告被截断，因此请将其转发或保存到其他地方。
注意

7.2.1. SMTP 访问设置

对于那些愿意通过 FreeBSD.org 基础设施发送电子邮件的人，请按照以下说明操作：

将邮件客户端指向 smtp.FreeBSD.org:587。
启用 STARTTLS。
确保你的 From: 地址设置为 你的用户名@FreeBSD.org。

7.2.1.1. 使用本地 MTA 将电子邮件转发到 FreeBSD.org SMTP 服务

也可以使用本地 MTA 将本地发送的邮件转发到 FreeBSD.org 的 SMTP 服务器。

示例 1. 使用 Postfix

要告诉本地 Postfix 实例将来自 你的用户名@FreeBSD.org 的邮件转发到 FreeBSD.org 服务器，可以在 main.cf 文件中添加以下内容：

在 /usr/local/etc/postfix/relayhost_maps 中创建以下内容：

在 /usr/local/etc/postfix/sasl_passwd 中创建以下内容：

如果邮件服务器被其他人使用，你可能希望防止他们从你的地址发送邮件。为此，可以在 main.cf 中添加以下内容：

在 /usr/local/etc/postfix/sender_login_maps 中创建以下内容：

其中 你的本地用户名 是用于连接到本地 Postfix 实例的 SASL 用户名。

示例 2. 使用 OpenSMTPD

要告诉本地 OpenSMTPD 实例将来自 你的用户名@FreeBSD.org 的邮件转发到 FreeBSD.org 服务器，可以在 smtpd.conf 中添加以下内容：

其中 你的本地用户名 是用于连接到本地 OpenSMTPD 实例的 SASL 用户名。

在 /usr/local/etc/mail/secrets 中创建以下内容：

示例 3. 使用 Exim

要指示本地 Exim 实例将来自 [email protected] 的所有邮件转发到 FreeBSD.org 服务器，可以在 Exim 配置文件 中添加以下内容：

在 /usr/local/etc/exim/freebsd_send 中创建以下内容：

7.3. 导师

所有新开发者在前几个月都会被分配一个导师。导师的职责是教导学员项目的规则和约定，并引导他们在开发者社区的初步步骤。导师还需要对学员在这一初期阶段的行为负责。

对于提交者：在没有得到导师批准的情况下，不能提交任何内容。提交信息中必须注明 Approved by: 行，记录导师的批准。

当导师认为学员已经掌握了基础，并准备独立提交时，导师会在 mentors 文件中发布提交。这一文件位于每个代码库的 admin 孤立分支中。有关如何访问这些分支的详细信息，请参见。

8. 提交前审核

代码审查是提高软件质量的一种方式。以下准则适用于对 src 仓库的 main（-CURRENT）分支的提交。其他分支以及 ports 和 docs 树有各自的审查政策，但这些准则一般适用于需要审查的提交：

所有非琐碎的更改应在提交到仓库之前进行审核。
审核可以通过电子邮件、Bugzilla、Phabricator 或其他机制进行。尽可能地，审核应当公开进行。
负责代码更改的开发者同样负责进行所有必要的与审核相关的更改。
代码审查是一个迭代过程，直到补丁准备好提交为止。具体来说，补丁发送到审查之后，在提交前应当收到明确的“看起来不错”反馈。在这点上，只要是明确的，可以采取任何适合的反馈形式。

有时代码审查会比你预期的时间更长，尤其是对于大型功能。加速补丁审查的有效方法包括：

审查他人的补丁。如果你提供帮助，其他人也更愿意为你提供帮助；良好的合作关系是我们的货币。
提醒补丁。如果它很紧急，提供为什么这个补丁对你来说很重要的理由，并每隔几天提醒一次。如果不紧急，常见的礼貌提醒频率是每周一次。记住，你是在请求其他专业开发者宝贵的时间。
在邮件列表、IRC 等平台寻求帮助。其他人可能能够直接帮助你，或者建议合适的审查者。
将补丁分解成多个较小的补丁，这些补丁彼此依赖。补丁越小，别人快速审查它的概率越高。在做大范围更改时，从一开始就保持这一思路是有帮助的，因为事后将大改动拆分成小补丁通常很困难。

开发者应当作为审查者和被审查者参与代码审查。如果有人愿意审查你的代码，你也应该回报他人，审查他们的代码。需要注意的是，虽然任何人都可以审查并提供反馈，只有相关领域的专家才能批准更改。这通常是一个经常与相关代码一起工作的提交者。

在某些情况下，可能没有相关领域的专家。在这种情况下，由经验丰富的开发者进行审查并结合适当的测试，通常也是足够的。

9. 提交日志消息

本节提供了一些关于提交日志格式的建议和传统。

9.1. 为什么提交信息很重要？

当你在 Git、Subversion 或其他版本控制系统（VCS）中提交更改时，你需要写一段描述该提交的文本——即提交信息。这个提交信息有多重要？是否应该花费一些精力来撰写它？如果你只是写了“修复了一个 bug”，真的有关系吗？

大多数项目有多个开发者，并且持续了一段时间。提交信息是与其他开发者进行沟通的重要方式，无论是当前开发者还是未来的开发者。

FreeBSD 拥有数百名活跃开发者和数十年的历史，涉及数十万次的提交。在这段时间里，开发者社区逐渐意识到好的提交信息有多么重要；有时候，这些经验是通过痛苦的教训获得的。

提交信息至少有三个目的：

与其他开发者沟通 FreeBSD 的提交会生成邮件发送到多个邮件列表。这些邮件包括提交信息和补丁本身的副本。提交信息还可以通过如 git log 等命令查看。这些信息有助于让其他开发者了解正在进行的更改；这些开发者可能希望测试该更改、对该主题有兴趣并希望更详细地审查，或者正在进行的项目可能会受益于与之的互动。
使更改可发现在一个拥有悠久历史的大型项目中，当调查某个问题或行为变化时，可能很难找到相关的更改。详细且冗长的提交信息可以使搜索与之相关的更改变得容易。例如，使用 git log --since 1year --grep 'USB timeout' 可以查找相关的历史更改。
提供历史文档提交信息为未来的开发者提供了更改的文档，也许是多年或几十年后。未来的开发者甚至可能是你，作为原作者。当今天看似显而易见的更改，可能在将来就变得不再那么明显了。

git blame 命令会标注源代码文件中的每一行，显示将其引入的更改（哈希值和主题行）。

在明确了提交信息的重要性之后，接下来是一个好的 FreeBSD 提交信息的要素：

9.2. 从主题行开始

提交信息应以一行简短的主题开始，简要总结该更改。主题本身应该允许读者快速判断更改是否值得关注。

9.3. 保持主题行简短

主题行应尽可能简短，同时保留必要的信息。这是为了使浏览 Git 日志更高效，并确保 git log --oneline 能在一个 80 列的行内显示短哈希和主题。一个好的经验法则是保持在 63 个字符以内，并尽可能控制在 50 个字符以内。

9.4. 如果适用，前缀主题行以组件名

如果更改涉及某个特定组件，主题行可以以该组件名称和冒号（:）为前缀。

✓ foo: 添加 -k 选项以保持临时数据

将前缀包含在建议的 63 字符限制内，以便 git log --oneline 不会换行。

9.5. 主题行首字母大写

主题行的首字母应大写。前缀（如果有）除非必要，否则不需要大写（例如，USB: 需要大写）。

9.6. 不要以标点符号结尾

主题行不要以句号或其他标点符号结尾。在这方面，主题行像报纸头条一样。

9.7. 使用空行分隔主题和正文

主题和正文之间应使用空行进行分隔。

一些简单的提交不需要正文，只有主题。

✓ ls: 修复使用文本中的拼写错误

9.8. 限制消息的行宽为 72 列

git log 和 git format-patch 会将提交信息缩进 4 个空格。限制在 72 列内能确保右侧有匹配的边距。将消息限制在 72 个字符以内还能够使提交信息在格式化补丁中低于 RFC 2822 提出的电子邮件行长度限制（78 字符）。这个限制对多种工具有良好的兼容性，避免了较长行长度带来的换行不一致问题。

9.9. 使用现在时，命令式语气

这有助于简短的主题行，并保持一致性，包括自动生成的提交信息（例如，git revert 生成的提交信息）。当阅读一系列提交主题时，这一点尤为重要。将主题视作完成句子“当应用时，该更改将会……”的部分。

✓ foo: 实现 -k（keep）选项 ✗ foo: 实现了 -k 选项 ✗ 该更改在 foo 中实现了 -k 选项 ✗ 添加了 -k 选项

9.10. 聚焦于“做了什么”和“为什么做”，而不是“如何做”

解释更改实现了什么，以及为什么要做这个更改，而不是陈述具体如何实现。

不要假设读者熟悉该问题。解释更改的背景和动机。如果有基准数据，提供这些数据。

如果更改有任何限制或不完整的方面，在提交信息中描述它们。

9.11. 考虑是否可以将提交信息中的某些部分写成代码注释

有时在编写提交信息时，你可能会写下一两句话，解释某些复杂或令人困惑的更改。在这种情况下，考虑是否将这些解释作为代码中的注释，这样它们可以直接帮助未来的开发者（包括你自己）理解代码。

9.12. 为将来的自己编写提交信息

当你为一个更改编写提交信息时，你心中已经掌握了所有相关背景——是什么促使了这次更改，考虑过并拒绝的其他方案、更改的限制等等。想象一下自己在一两年后再次查看这个更改时，写提交信息的方式应该包含所有这些必要的背景信息，以帮助未来的你理解为什么做出这个更改。

9.13. 提交信息应该是自包含的

你可以在提交信息中引用邮件列表帖子、基准测试结果网页或代码审查链接。然而，提交信息应包含所有相关信息，以防这些引用在未来不再可用。

类似地，一个提交可能会引用之前的提交，比如修复 bug 或回退更改的情况。除了提交标识符（修订号或哈希值），还应包括引用提交的主题行（或其他合适的简短引用）。随着每次版本控制系统（VCS）迁移（从 CVS 到 Subversion，再到 Git），早期系统的修订标识符可能变得难以追溯。

9.14. 在脚注中包含适当的元数据

除了在每个提交中包含有意义的消息外，可能还需要附加一些额外的信息。

这些信息由一行或多行构成，每行包含关键字或短语、一个冒号、制表符进行格式化，然后是附加信息。

对于那些可以有多个值的关键字（例如，PR: 后跟以逗号分隔的 PR 列表），可以多次使用相同的关键字，以避免歧义或提高可读性。

关键字或短语如下：

示例 4. 基于 PR 的提交日志

该提交基于 John Smith 提交的 PR 中的补丁。提交消息中的 "PR" 字段已填写。

提交者使用 git commit --author "John Smith <[email protected]>" 设置补丁的作者。

示例 5. 需要审核的提交日志

虚拟内存系统正在进行更改。补丁已发布到适当的邮件列表（在此案例中为 freebsd-arch），并且更改已获得批准。

示例 6. 需要批准的提交日志

提交一个 Port，在与列出的 MAINTAINER 一起工作后，MAINTAINER 允许继续提交。

其中 abc 是批准人的账户名。

示例 7. 引入来自 OpenBSD 的代码的提交日志

提交一些基于 OpenBSD 项目工作的代码。

示例 8. 提交到 FreeBSD-CURRENT 的更改，计划在稍后日期合并到 FreeBSD-STABLE

提交一些代码，该代码将在两周后从 FreeBSD-CURRENT 合并到 FreeBSD-STABLE 分支。

其中 2 是计划进行 MFC 的天数、周数或月数。weeks 选项可以是 day、days、week、weeks、month、months。

这些信息常常需要组合在一起。

考虑以下情况：一个用户提交了包含来自 NetBSD 项目的代码的 PR。查看 PR 后，开发人员发现这是他们通常不工作的区域，因此他们让 arch 邮件列表审核了该更改。由于该更改复杂，开发人员决定在一个月后进行 MFC，以便进行充分的测试。

提交中应包含的额外信息如下：

示例 9. 组合提交日志示例

10. 新文件的首选许可证

FreeBSD 项目的完整许可证政策可以在找到。本节的其余部分旨在帮助你入门。作为一条规则，若有疑问，请询问。提供建议比修复源代码树更容易。

FreeBSD 项目建议并使用以下文本作为首选许可证方案：

FreeBSD 项目强烈不鼓励在新代码中使用所谓的 "广告条款"。由于 FreeBSD 项目有大量的贡献者，对于许多商业供应商来说，遵守该条款变得困难。如果代码中包含广告条款，请考虑将其删除。实际上，请考虑使用上述许可证为你的代码授权。

FreeBSD 项目不鼓励使用全新的许可证或标准许可证的变体。新许可证需要得到的批准才能存入 src 仓库。树中使用的许可证越多，给那些希望利用这些代码的人带来的问题就越多，通常是由于不清晰的许可证条款导致的意外后果。

项目政策要求，某些非 BSD 许可证下的代码只能放置在仓库的特定部分，在某些情况下，编译必须是有条件的，甚至默认禁用。例如，GENERIC 内核必须仅在与 BSD 许可证相同或实质上相似的许可证下编译。GPL、APSL、CDDL 等许可证的软件不得编译到 GENERIC 中。

开发者需注意，在开源中，正确处理 "开源" 和 "源代码" 一样重要，因为不当处理知识产权会带来严重后果。任何问题或疑虑应立即向核心团队报告。

11. 跟踪授予 FreeBSD 项目的许可证

FreeBSD 项目的仓库中存在一些软件或数据，已授予特殊许可证以便我们使用。一个例子是 Terminus 字体，用于。在这里，作者 Dimitar Zhekov 允许我们使用 Terminus BSD Console 字体，并为其提供了一个 2 条款 BSD 许可证，而不是他通常使用的开放字体许可证。

显然，记录所有此类许可证授权是明智的。为此，决定保持它们的档案。每当 FreeBSD 项目被授予特殊许可证时，我们要求通知。任何参与安排此类许可证授权的开发者，请将以下详细信息发送给：

授予特殊许可证的个人或组织的联系信息。
仓库中哪些文件、目录等受该许可证授权，包括提交的任何特别授权材料的修订号。
该许可证生效的日期。除非另有约定，否则此日期应为软件作者授予许可证的日期。
许可证文本。

待确认所有必要的详细信息已收集并正确无误，秘书将发送一封包含许可证详细信息的 PGP 签名确认函。此确认函将永久存档，并作为我们永久的许可证授予记录。

许可证档案应仅包含许可证授权的详细信息；此处不应讨论任何关于许可证或其他主题的内容。访问许可证档案中的数据将根据请求提供给。

12. 树中的 SPDX 标签

该项目在我们的源代码库中使用标签。目前，这些标签旨在帮助自动化工具机械地重建许可证要求。树中所有 SPDX-License-Identifier 标签应视为信息性标签。FreeBSD 源代码树中所有带有这些标签的文件也包含治理该文件使用的许可证副本。如果出现不一致，以原文许可证为准。该项目力图遵循。如何标记源文件和有效的代数表达式，见和。该项目从 SPDX 的有效中抽取标识符。该项目仅使用 SPDX-License-Identifier 标签。

截至 2021 年 3 月，树中的大约 25,000 个文件已被标记。

13. 开发者关系

当你在自己的代码上直接工作，或者在已经明确由你负责的代码上工作时，通常无需在提交前与其他提交者进行确认。当你在系统中某个明显无人维护的区域修复 bug（我们为此感到羞愧的确存在一些此类区域）时，同样适用。修改系统中由正式或非正式方式维护的部分时，可以考虑请求审查，就像开发者在成为提交者之前会做的一样。对于 ports，联系 Makefile 中列出的 MAINTAINER。

要判断某个区域是否被维护，可以查看树根目录中的 MAINTAINERS 文件。如果没有列出任何人，请扫描修订历史，查看过去谁提交了更改。要列出过去两年内给定文件的所有提交作者的名字和电子邮件地址，并按提交次数降序排列，可以使用：

如果查询没有得到回应，或者提交者以其他方式表明对该区域缺乏兴趣，可以继续提交。

重要
避免向维护者发送私人邮件。其他人可能对这次对话感兴趣，而不仅仅是最终的结果。

如果对提交有任何疑虑，请在提交之前进行审查。最好在提交前得到批评，而不是等到它已经是仓库的一部分后再遭到批评。如果提交导致争议爆发，可能需要考虑在问题解决之前撤销更改。记住，使用版本控制系统我们总是可以把它恢复回来。

不要诋毁他人的想法。如果他们看到的问题解决方案不同，甚至问题本身不同，可能并不是因为他们愚蠢，或者有可疑的出身，或者他们想摧毁辛勤的工作、个人形象或 FreeBSD，而是因为他们有不同的世界观。和而不同。

诚实地表达分歧。从解决方案的优点出发辩论，诚实地指出其不足，并且愿意以开放的心态看待他们的解决方案，甚至是他们对问题的看法。

接受修正。我们都是容易犯错的。当你犯错时，道歉并继续前进。不要自责，也不要因为错误去责怪别人。不要浪费时间在尴尬或自责上，赶紧修正问题并继续前进。

寻求帮助。寻找（并提供）同行审查。开源软件的一个优势是有更多人参与其中的审查；如果没有人愿意审查代码，那就失去了这一优势。

14. 如果有疑虑……

当你不确定某件事时，无论是技术问题还是项目约定，都要确保向他人请教。如果你保持沉默，你将永远无法取得进展。

如果是技术问题，请在公共邮件列表上提问。避免私下给知道答案的个人发送邮件。这样，所有人都可以从问题和答案中学习。

对于与项目相关的或行政性的问题，请按照以下顺序提问：

你的导师或前导师。
在 IRC、邮件等平台上的有经验的提交者。
任何拥有“帽子”的团队，他们能给你一个权威的答案。
如果仍然不确定，可以在 FreeBSD 开发者邮件列表上提问。

如果你的问题得到解答，而且没有人指出有文档明确回答了你的问题，请记录下来，因为其他人也会有同样的问题。

15. Bugzilla

FreeBSD 项目使用 Bugzilla 来追踪 bug 和变更请求。如果你提交了一个修复或建议，并且该内容已经在 PR 数据库中存在，请确保关闭该 PR。如果你有时间，也可以考虑关闭与你的提交相关的其他 PR。

拥有非 FreeBSD.org Bugzilla 账户的提交者，可以通过以下步骤将旧账户与 FreeBSD.org 账户合并：

使用旧账户登录。
打开一个新的 bug，选择 Services 作为产品，选择 Bug Tracker 作为组件。在 bug 诉说中列出你希望合并的账户。
使用 FreeBSD.org 账户登录，并在新开 bug 中发表评论以确认所有权。有关如何为 FreeBSD.org

你可以在以下链接了解更多关于 Bugzilla 的信息：

16. Phabricator

FreeBSD 项目使用来处理代码审查请求。详细信息请参见。

拥有非 FreeBSD.org Phabricator 账户的提交者，可以通过以下步骤将旧账户重命名为 FreeBSD.org 账户：

将你的 Phabricator 账户电子邮件更改为你的 FreeBSD.org 邮件。
使用你的 FreeBSD.org 账户，在我们的 bug 跟踪系统中打开一个新的 bug，更多信息请参见。选择 Services 作为产品，选择 Code Review 作为组件。在 bug 描述中请求将你的 Phabricator 账户重命名，并提供你的 Phabricator 用户链接。例如，https://reviews.freebsd.org/p/bob_example.com/

重要
Phabricator 账户不能合并，请勿创建新账户。

17. 谁是谁

除了仓库管理者之外，还有其他 FreeBSD 项目成员和团队，你可能会在作为提交者的过程中接触到。简要介绍如下（并非全面列举）：

Documentation Engineering Team ([email protected])：doceng 团队负责文档构建基础设施，批准新的文档提交者，并确保 FreeBSD 网站和 FTP 站点上的文档与 Subversion 树保持同步。该团队不处理冲突解决问题。绝大多数与文档相关的讨论发生在上。关于 doceng 团队的更多信息，请参见其。希望参与文档工作的提交者应熟悉。

Konstantin Belousov ([email protected]), Dave Cottlehuber ([email protected]), Marc Fonvieille ([email protected]), John Hixson ([email protected]), Xin Li ([email protected]), Ed Maste ([email protected]), Mahdi Mokhtari ([email protected]), Colin Percival ([email protected]), Doug Rabson ([email protected]), Muhammad Moinur Rahman ([email protected])：这些成员属于 Release Engineering Team ([email protected])。该团队负责设置发布截止日期和控制发布过程。在代码冻结期间，发布工程师对即将发布版本的系统更改拥有最终权力。如果你希望从 FreeBSD-CURRENT 合并更改到 FreeBSD-STABLE（无论在任何给定时刻这些值为何），这些人是你应该联系的对象。

Gordon Tetlow ([email protected])：Gordon Tetlow 是，负责管理 Security Officer Team ([email protected])。

FreeBSD 提交者邮件列表 {dev-src-all}、{dev-ports-all} 和 {dev-doc-all} 是版本控制系统用来发送提交消息的邮件列表。永远不要直接向这些列表发送邮件。只有在邮件简短且与提交直接相关时，才可以回复这些列表。

FreeBSD 开发者邮件列表：所有提交者都已订阅该列表。这个列表是为提交者的“社区”问题设立的论坛。举例来说，核心投票、公告等。

FreeBSD 开发者邮件列表仅供 FreeBSD 提交者使用。为了开发 FreeBSD，提交者必须能够公开讨论将要解决的问题，直到它们公开发布之前。正在进行中的工作讨论不适合公开发布，否则可能会对 FreeBSD 产生不利影响。

所有 FreeBSD 提交者应确保未经所有作者许可，不将 FreeBSD 开发者邮件列表的消息公开或转发给列表外的人。违规者将被从 FreeBSD 开发者邮件列表中移除，从而暂停提交权限。反复或严重违反者可能会被永久撤销提交权限。

该列表不是用于代码审查或任何技术讨论的地方。实际上，使用该列表进行此类讨论会对 FreeBSD 项目造成伤害，因为它给人一种错误印象，认为所有影响到 FreeBSD 使用社区的决策都是在一个封闭的列表中做出的，而没有做到“公开”。最后但同样重要的是 绝对不要 向 FreeBSD 开发者邮件列表发送电子邮件并将其他 FreeBSD 邮件列表作为抄送/密件抄送对象。这样做会极大地削弱该列表的作用。

18. SSH 快速入门指南

如果你不希望每次使用时都输入密码，并且你使用密钥进行身份验证，可以为你提供便利。如果你想使用，请确保在运行其他应用程序之前先启动它。例如，X 用户通常会在他们的 .xsession 或 .xinitrc 中执行此操作。有关详细信息，请参阅。
使用生成密钥对。密钥对将保存在你的 $HOME/.ssh/ 目录中。
重要
仅支持 ECDSA、Ed25519 或 RSA 密钥。

现在，你可以使用进行一次会话的身份验证。它会提示输入私钥的密码短语，然后将其存储在身份验证代理（）中。使用 ssh-add -d 可以从代理中移除存储的密钥。

通过一个简单的远程命令进行测试：ssh freefall.FreeBSD.org ls /usr。

有关更多信息，请参阅、、、、和。

有关添加、修改或删除密钥的信息，请参阅。

19. FreeBSD 提交者的 Coverity® 可用性

所有 FreeBSD 开发者都可以访问 FreeBSD 项目软件的 Coverity 分析结果。所有有兴趣获取自动化 Coverity 运行的分析结果的人，可以在注册。

FreeBSD 维基包含了一个小指南，供有兴趣使用 Coverity® 分析报告的开发者参考：。请注意，此小指南仅供 FreeBSD 开发者阅读，因此如果你无法访问此页面，你需要请求某人将你添加到适当的 Wiki 访问列表中。

最后，所有打算使用 Coverity® 的 FreeBSD 开发者都应随时通过向 FreeBSD 开发者的邮件列表提问来获取更多的详细信息和使用信息。

20. FreeBSD 提交者的详细规则清单

所有参与 FreeBSD 项目的人员都应遵守 行为规范，可以从获取该规范。作为提交者，你是项目的公众面貌，你的行为对公众对该项目的看法有着至关重要的影响。本指南扩展了 行为规范 中与提交者相关的部分。

尊重其他提交者。
尊重其他贡献者。
在提交之前讨论任何重大更改。
尊重现有的维护者（若在 Makefile 中的 MAINTAINER

如上所述，违反这些规则可能会导致暂停提交权限，或者在多次违规后永久撤销提交权限。核心成员有权暂时暂停提交权限，直到核心小组有机会审查该问题。在“紧急情况”（如提交者对代码库造成损害）下，代码库管理员也可以暂时暂停权限。只有 2/3 多数的核心成员有权暂停提交权限超过一周，或永久撤销权限。此规则的存在并不是为了让核心成为一群残酷的独裁者，而是为了给项目提供一种安全保护措施。如果某人失控，能够立即采取行动而不被辩论拖延是非常重要的。在所有情况下，提交者的权限被暂停或撤销时，有权要求由核心进行“听证”，暂停的总时长将在那时确定。提交者在暂停权限后还可以在 30 天后请求复审，并且每 30 天复审一次（除非暂停期少于 30 天）。完全撤销权限的提交者可以在 6 个月后请求复审。该复审政策是 严格非正式的，在所有情况下，核心小组保留在认为原决策正确时可以选择是否审理复审请求的权利。

在项目运营的其他方面，核心小组是提交者的一个子集，必须遵守 相同的规则。仅仅因为某人是核心成员，并不意味着他们可以越过任何已定的规则；核心小组的“特别权力”仅在作为小组行动时才生效，而非个人行为。作为个体，核心团队成员首先是提交者，其次才是核心成员。

20.1. 细节

尊重其他提交者。这意味着你需要将其他提交者视为同行开发者。尽管我们偶尔会试图证明相反的事情，但成为提交者并不是因为愚蠢，而最让人不爽的事情就是被同行如此对待。无论我们是否总是感到彼此尊重（每个人都有情绪低落的时候），我们仍然必须始终以尊重的态度对待其他提交者，无论是在公开论坛上还是在私人邮件中。
长期合作的能力是这个项目最宝贵的资产，它远比任何代码更重要，将关于代码的争论转化为影响我们长期和谐合作的问题，是无法接受的。
为了遵守这一规则，当你生气时，不要发送电子邮件，或者以可能让他人感到不必要对抗的方式行事。先冷静下来，然后思考如何以最有效的方式沟通，来让对方相信你的论点是正确的，而不是为了短期内的宣泄而进行一场长期的争论。这不仅是非常不好的“能量经济学”，反复在公众场合表现出攻击性行为会严重影响我们合作的能力，项目领导层会严肃处理，并可能导致提交权限的暂停或终止。项目领导层会考虑到公开和私下的沟通，但不会主动披露私人沟通，除非相关提交者自愿提供。
这些都不是项目领导层希望看到的，但团结至上。没有任何代码或好建议值得为此做出妥协。
尊重其他贡献者。你曾不是提交者。曾几何时，你也是位贡献者。请始终记住这一点。记住曾经尝试寻求帮助和关注的感受。不要忘记你作为贡献者时的感受。记住那个时候，自己是多么重要。不要打击、贬低或轻视贡献者。尊重他们。他们是我们未来的提交者。与提交者一样，他们对项目的贡献同样重要。毕竟，在成为提交者之前，你也是如此贡献过。切记这一点。

上述目录用于通常从供应商分支导入的第三方软件。将内容提交到这些目录可能会在导入新版本的软件时带来不必要的麻烦。一般来说，考虑将补丁发送到上游供应商。补丁可以在维护者许可下先提交到 FreeBSD。

修改上游软件的原因包括希望对紧密耦合的依赖关系进行严格控制，或是上游代码的可移植性问题。无论原因如何，尽量减少复刻的维护负担对其他维护者是有益的。避免提交琐碎或外观上的更改，因为这些会使之后的合并变得更加困难：这些补丁需要在每次导入时手动重新验证。

如果某个软件没有维护者，建议你承担起责任。如果不确定当前的维护者是谁，可以发送邮件至进行询问。

20.2. 多架构政策

FreeBSD 在最近的发布周期中新增了多个架构 Port，真正不再是一个以 i386™ 为中心的操作系统。为了使 FreeBSD 在我们支持的平台上保持良好的可移植性，核心团队制定了以下规定：

我们的 32 位参考平台是 i386，64 位参考平台是 amd64。重大设计工作（包括重大 API 和 ABI 更改）必须在至少一个 32 位平台和一个 64 位平台上证明其可行性，最好是在主要参考平台上，才能提交到源码树中。

开发者还应了解我们的架构长期支持的 Tier 政策。这里的规则是为了在开发过程中提供指导，并且与发布时列出的特性和架构的要求不同。在开发过程中，架构的支持规则比发布时的规则要宽松得多。

20.3. 多编译器政策

FreeBSD 使用 Clang 和 GCC 进行构建。该项目以一种谨慎且可控的方式进行，以最大化这种额外工作的好处，同时将额外工作的量降到最低。支持 Clang 和 GCC 提高了我们用户的灵活性。这些编译器有不同的优缺点，支持这两者让用户可以根据自己的需求选择最佳的编译器。Clang 和 GCC 支持类似的 C 和 C++ 方言，只需相对较少的条件代码。该项目通过使用两种编译器的特性，增加了代码覆盖率并提高了代码质量。通过支持这种范围，项目能够在更多用户环境中构建并利用更多 CI 环境，从而提高了用户的便利性，并为他们提供了更多测试工具。通过严格限制支持的版本范围为这些编译器的现代版本，项目避免了过度增加测试矩阵。旧的和冷门的编译器以及旧的语言方言有极其有限的支持，允许用户程序使用它们进行构建，但不要求基本系统必须使用这些编译器进行构建。具体的平衡仍在不断演变，以确保额外工作的好处大于它所带来的负担。该项目曾经支持非常旧的 Intel 编译器或旧版本的 GCC，但我们用精心选择的现代编译器替代了对这些过时编译器的支持。本节记录了我们在哪里使用不同的编译器，以及对此的期望。

FreeBSD 项目提供了一个内嵌的 Clang 编译器。由于它在源码树中，因此这是最受支持的编译器。所有更改在提交之前必须与它编译通过。根据更改的性质，应使用此编译器进行完整的测试。

在任何时候，FreeBSD 项目也支持一个或多个树外编译器。目前，这个编译器是 GCC 12.x。理想情况下，提交者应使用该编译器进行编译测试，尤其是对于大规模或风险较高的更改。此编译器作为 ${TARGET_ARCH}-gcc${VERSION} 包提供，例如或。该项目运行自动化 CI 任务，以使用这些编译器构建所有内容。提交者应修复他们的更改破坏的 CI 任务。提交者可以在必要时使用 CROSS_TOOLCHAIN=aarch64-gcc12 或 CROSS_TOOLCHAIN=llvm15 进行测试。

FreeBSD 项目还在 GitHub 上拥有一些 CI 管道。对于 GitHub 上的拉取请求和推送到 GitHub 分支的某些代码，运行了一些交叉编译作业。这些作业测试 FreeBSD 使用一个可能比内嵌编译器版本落后一个大版本的 Clang 版本进行构建。

FreeBSD 项目还在升级编译器。Clang 和 GCC 都是快速发展的目标。一些更改可能会在编译器到达之前先在源码树中实施，例如移除旧式的 K&R 函数声明和定义。提交者应尽量注意这一点，并乐于调查新编译器可能带来的代码问题或更改。此外，在新的编译器版本加入源码树后，若怀疑存在未被检测的回归，可能需要使用旧版本进行编译。

除了编译器，LLVM 的 LLD 和 GNU 的 binutils 也由编译器间接使用。提交者应注意汇编语法和链接器特性的差异，并确保两者的变种都能正常工作。这些组件将作为 FreeBSD CI 任务的一部分进行测试，适用于 Clang 或 GCC。

FreeBSD 项目提供了头文件和库，允许使用其他编译器来构建非基本系统中的软件。这些头文件支持将环境尽可能严格地与标准一致，支持 ANSI-C 先前方言，直到 C89，并处理我们庞大的 Ports 中所发现的其他边缘情况。这个支持限制了旧标准在头文件中的淘汰，但不限制基本系统更新到更新的方言，也不要求基本系统整体上使用这些旧标准进行编译。破坏这一支持将导致 Ports 中的软件包构建失败，因此应尽量避免，并在容易修复时尽快修复。

FreeBSD 构建系统目前适应这些不同的环境。随着编译器中新警告的加入，项目尝试修复它们。然而，有时这些警告需要大量重构，因此会通过使用根据编译器版本评估的 make 变量某种方式被抑制。开发者应注意这一点，确保任何特定于编译器的标志都能正确地进行条件处理。

20.3.1. 当前编译器版本

目前，内嵌的编译器是 Clang 15.x。目前，GCC 12 和 Clang 12、13、14、15 在 GitHub 和项目的 CI Jenkins 任务中进行了测试。相关工作正在进行，以准备将 Clang 16 版本加入源码树。最旧的项目支持分支使用 Clang 12，因此构建的引导部分必须适用于 Clang 12 至 15 的主版本。

20.4. 其他建议

在提交文档更改时，在提交之前使用拼写检查工具。对于所有 XML 文档，通过运行 make lint 和验证格式化指令是否正确。

对于手册页，运行和来验证所有交叉引用和文件引用是否正确，并且手册页是否安装了所有适当的 MLINKS。

不要将样式修复与新功能混合。样式修复是指不修改代码功能的任何更改。混合这些更改会在询问修订差异时混淆功能性更改，这可能会隐藏任何新引入的 bug。不要在提交 doc/ 时将空白更改与内容更改混合。差异中的额外杂乱会使翻译人员的工作更加困难。相反，请将任何样式或空白更改放在单独的提交中，并在提交消息中明确标明这些更改。

20.5. 弃用功能

当需要从基本系统中删除功能时，请尽可能遵循以下指南：

在手册页和可能的发布说明中提到该选项、工具或接口已弃用。使用弃用的功能会生成警告。
该选项、工具或接口在下一个主要（零点版本）发布之前保留。
该选项、工具或接口被移除且不再文档化。它现在已过时。通常，最好在发布说明中指出其移除。

20.6. 隐私与保密

大多数 FreeBSD 的事务是公开的。 FreeBSD 是一项开源项目。这意味着不仅任何人都可以使用源代码，而且大多数开发过程都向公众开放，接受公众审查。
某些敏感事项必须保持私密或处于禁运状态。不幸的是，无法实现完全透明。作为 FreeBSD 开发者，你将拥有一定程度的特权信息访问权限。因此，你需要遵守某些保密要求。有时保密的需求来自外部合作者或具有特定时间限制的要求。大多数情况下，这是关于不公开私人通信的。
安全官员单独控制安全公告的发布。当有影响多个操作系统的安全问题时，FreeBSD 经常依赖提前获取信息，以便为协调发布准备安全公告。除非可以信任 FreeBSD 开发者维护安全性，否则不会提前提供此类信息。安全官员负责控制漏洞信息的预发布访问，并决定所有公告的发布时机。如果有相关知识的开发者能够在保密条件下提供帮助，安全官员可以请求协助准备安全修复。

21. 支持多种架构

FreeBSD 是一个高度可移植的操作系统，旨在支持多种不同类型的硬件架构。保持机器相关（MD）代码与机器无关（MI）代码的清晰分离，并尽量减少 MD 代码，是我们保持对当前硬件趋势灵活性的战略重要组成部分。每增加一种硬件架构的支持，都会显著增加代码维护、工具链支持和发布工程的成本。它还会大幅提高对内核更改进行有效测试的成本。因此，强烈的动机是区分各种架构支持的不同级别，同时在一些被视为 FreeBSD “目标受众”的关键架构上保持强大的支持。

21.1. 一般意图声明

FreeBSD 项目专注于“生产质量的商业现货（COTS）工作站、服务器和高端嵌入式系统”。通过将重点保持在这些环境中感兴趣的有限架构集上，FreeBSD 项目能够维持高水平的质量、稳定性和性能，同时最小化项目中各个支持团队的负担，如 Port 团队、文档团队、安全官员和发布工程团队。硬件支持的多样性通过提供新特性和使用机会，拓宽了 FreeBSD 用户的选择，但这些好处必须始终仔细考虑与额外平台支持相关的实际维护成本。

FreeBSD 项目将平台目标分为四个级别。每个级别包括消费者可以依赖的保证清单，以及项目和开发者为履行这些保证所承担的义务。这些清单定义了每个级别的最低保证。项目和开发者可能提供超出最低保证的额外支持，但这些额外支持不作保证。每个平台目标会根据每个稳定分支分配到一个特定的级别。因此，某个平台目标可能会在并行的稳定分支中分配到不同的级别。

21.2. 平台目标

硬件平台的支持由两个组件组成：内核支持和用户空间应用程序二进制接口（ABI）。内核平台支持包括使 FreeBSD 内核能够在硬件平台上运行所需的内容，如机器相关的虚拟内存管理和设备驱动程序。用户空间 ABI 指定了用户进程与 FreeBSD 内核和基本系统库进行交互的接口。用户空间 ABI 包括系统调用接口、公共数据结构的布局和语义、以及传递给子程序的参数的布局和语义。某些 ABI 组件可能由规范定义，如 C++ 异常对象的布局或 C 函数的调用约定。

FreeBSD 内核也使用 ABI（有时称为内核二进制接口（KBI）），包括公共数据结构的语义和布局，以及内核中公共函数的参数的语义和布局。

FreeBSD 内核可以支持多个用户空间 ABI。例如，FreeBSD 的 amd64 内核支持 FreeBSD amd64 和 i386 用户空间 ABI，以及 Linux x86_64 和 i386 用户空间 ABI。FreeBSD 内核应支持一个“本地” ABI 作为默认 ABI。本地 ABI 通常与内核 ABI 共享某些特性，如 C 调用约定、基本类型的大小等。

内核和用户空间 ABI 都有相应的级别定义。在常见的情况下，平台的内核和 FreeBSD ABI 被分配到相同的级别。

21.2.1. 第一层：完全支持的架构

第一层平台是最成熟的 FreeBSD 平台。它们由安全官员、发布工程和 Ports 管理团队支持。第一层架构预计在 FreeBSD 操作系统的所有方面（包括安装和开发环境）都具有生产质量。

FreeBSD 项目为第一层平台的消费者提供以下保证：

发布工程团队将提供官方的 FreeBSD 发布镜像。
将为受支持的版本提供安全通告和勘误通知的二进制更新和源代码补丁。
将为受支持的分支提供安全通告的源代码补丁。
跨平台的安全通告的二进制更新和源代码补丁通常会在公告时提供。

为了保持第一层平台的成熟，FreeBSD 项目将维护以下资源来支持开发：

在 FreeBSD.org 集群或其他易于所有开发者访问的位置提供构建和测试自动化支持。嵌入式平台可能使用 FreeBSD.org 集群中的仿真器代替实际硬件。
包含在 make universe 和 make tinderbox 目标中。
在 FreeBSD 集群中为包构建提供专用硬件（无论是本地构建还是通过 qemu-user）。

为了维持第一层平台的状态，开发者需要提供以下内容：

对源代码树的更改不得故意破坏第一层平台的构建。
第一层架构必须拥有成熟、健康的用户生态系统和活跃的开发者。
开发者应该能够在常见的非嵌入式第一层系统上构建包。这可以意味着，如果平台在该平台上常见，使用本地构建，或者可以意味着在其他第一层架构上进行交叉构建。
更改不能破坏用户空间 ABI。如果需要更改 ABI，应通过符号版本控制或共享库版本提升提供对现有二进制文件的 ABI 兼容性。

21.2.2. 第二层：开发性和小众架构

第二层平台是功能性存在，但成熟度较低的 FreeBSD 平台。它们不受安全官员、发布工程和 Ports 管理团队的支持。

第二层平台可能是仍在积极开发中的第一层平台候选者。达到生命周期终结的架构也可能从第一层状态转为第二层状态，因为持续保持系统在生产质量状态下的资源可用性减少。受到良好支持的小众架构也可以是第二层。

FreeBSD 项目为第二层平台的消费者提供以下保证：

Port 基础设施应包括对第二层架构的基本支持，足以支持构建 Port 和包。这包括对基本包（如 ports-mgmt/pkg）的支持，但不能保证所有 Port 都能够构建或正常运行。
不特定于平台的新功能，如果未实现，应该在所有第二层架构上可行。
第二层平台将包含在源代码树中。
第二层平台应该能够自我托管，无论是通过内建工具链还是外部工具链。如果需要外部工具链，将提供外部工具链的官方二进制包。

为了保持第二层平台的成熟，FreeBSD 项目将维护以下资源来支持开发：

包含在 make universe 和 make tinderbox 目标中。

为了维持第二层平台的状态，开发者需要提供以下内容：

对源代码树的更改不得故意破坏第二层平台的构建。
第二层架构必须拥有活跃的用户和开发者生态系统。
虽然允许更改破坏用户空间 ABI，但不应无故破坏 ABI。重大用户空间 ABI 更改应限制在主版本中。
尚未在第二层架构上实现的新功能，应提供在这些架构上禁用它们的方式。

21.2.3. 第三层：实验性架构

第三层平台至少有部分 FreeBSD 支持。它们不受安全官员、发布工程和 Ports 管理团队的支持。

第三层平台是处于开发初期的架构，面向非主流硬件平台，或者是被认为不太可能在未来广泛使用的遗留系统。第三层平台的初步支持可能存在于一个独立的仓库中，而非主源代码仓库。

FreeBSD 项目不为第三层平台的消费者提供任何保证，也不承诺维护支持开发的资源。第三层平台可能并不总是可构建的，内核或用户空间 ABI 也不被视为稳定的。

21.2.4. 不支持的架构

其他平台在任何形式上都不受项目支持。项目以前将这些平台称为第四层系统。

平台转为不受支持后，所有对该平台的支持将从源代码、Ports 和文档树中移除。请注意，Ports 支持应在平台仍受 Ports 支持的分支中保持。

21.3. 改变架构层级的政策

系统只能在获得 FreeBSD 核心团队批准后，才能从一个层级移动到另一个层级。核心团队将与安全官员、发布工程和 Ports 管理团队合作做出这一决定。要将平台晋升到更高的层级，必须在晋升完成之前满足任何缺失的支持保证。

22. Port 相关常见问题

22.1. 添加新 Port

22.1.1. 如何添加新 Port ？

将 Port 添加到树中相对简单。Port 准备好添加后，如后文所述，你需要在该类别的 Makefile 中添加 Port 的目录条目。在该 Makefile 中， Port 按字母顺序列出，并添加到 SUBDIR 变量中，如下所示：

Port 及其类别的 Makefile 准备好后，可以提交新 Port ：

22.1.2. 添加新 Port 时需要注意的其他事项？

检查 Port，最好确保它能够正确编译和打包。

中的测试章节包含更详细的说明。请参阅和部分。

你不必消除所有警告，但请确保修复简单的警告。

如果 Port 来自于一个之前没有为项目做过贡献的提交者，将该人的名字添加到部分的 FreeBSD 贡献者列表中。

如果 Port 是通过 PR 提交的，请关闭 PR。关闭 PR 时，状态改为 Issue Resolved，并将解决方案设为 Fixed。

注意
如果由于某些原因无法使用来测试新 Port，则最基本的测试包括以下步骤：# make install
请注意，poudriere 是包构建的参考工具，如果无法在 poudriere 中构建 Port，Port 将被移除。

22.2. 移除现有 Port

22.2.1. 如何移除现有 Port？

首先，请阅读关于仓库副本的章节。在移除 Port 之前，你需要验证是否没有其他 Port 依赖于它。

确保该 Port 在 Ports 中没有依赖：
- 该 Port 的 PKGNAME 在最近的 INDEX 文件中只出现一次。
- 没有其他 Port 在其 Makefile 中包含该 Port 的目录或 PKGNAME。
  技巧

另外，你也可以使用 ports/Tools/scripts 中的 rmport 脚本。此脚本由 Vasil Dimov 编写 []。如有关于此脚本的问题，请将问题发送到，并请抄送当前维护者 Chris Rees []。

22.3. 如何将 Port 移到新位置？

对 Ports 进行彻底检查，确保没有其他 Port 依赖于旧的 Port 位置/名称，并更新它们。仅运行 grep 在 INDEX 上是不够的，因为一些 Port 的依赖项是通过编译时选项启用的。建议对 Ports 执行完整的。
从旧类别的 Makefile 中移除 SUBDIR 条目，并将 SUBDIR 条目添加到新类别的 Makefile 中。

22.4. 如何将 Port 复制到新位置？

使用 cp -R old-cat/old-port new-cat/new-port 复制 Port。
将新 Port 添加到 new-cat/Makefile 中。
修改 new-cat/new-port 中的内容。

22.5. Port 冻结

22.5.1. 什么是“ Port 冻结”？

“Port 冻结”是指在发布之前将 Port 树置于受限状态。这是为了确保发布的包具有更高的质量，通常持续几周。在此期间，修复构建问题并构建发布包。这个做法现在不再使用，因为发布包是从当前稳定的季度分支构建的。

有关如何将提交合并到季度分支的更多信息，请参阅。

22.6. 季度分支

22.6.1. 请求将提交合并到季度分支的程序是什么？

自 2020 年 11 月 30 日起，无需明确请求批准即可提交到季度分支。

22.6.2. 如何将提交合并到季度分支？

将提交合并到季度分支的过程（我们称之为 MFH，历史原因）与将提交合并到 src 仓库的 MFC 非常相似，因此基本流程如下：

其中 $HASH 是你希望复制到季度分支的提交的哈希值。-x 参数确保将 main 分支的 $HASH 哈希值包含在季度分支的新提交信息中。

22.7. 创建新类别

22.7.1. 创建新类别的程序是什么？

请参阅以了解在 Porter’s Handbook 中的详细步骤。完成该程序并将 PR 分配给 Port 管理团队 [] 后，是否批准该请求由他们决定。如果他们批准了，责任在于：

执行任何必要的迁移（仅适用于物理类别）。
更新 ports/Mk/bsd.port.mk 中的 VALID_CATEGORIES 定义。
将 PR 返还给你。

22.7.2. 我需要做什么来实现一个新的物理类别？

升级每个已迁移 Port 的 Makefile。此时不要将新类别连接到构建。要做到这一点，你需要：
1. 修改 Port 的 CATEGORIES（记住，这是该步骤的目标）。将新类别列在第一位。这样有助于确保 PKGORIGIN 正确。
2. 运行 make describe

22.7.3. 我需要做什么来实现一个新的虚拟类别？

这比物理类别简单得多，仅需进行一些修改：

在 Porter’s Handbook 中更新。

22.8. 杂项问题

22.8.1. 是否可以在没有维护者批准的情况下提交更改？

对于大多数 Port ，以下类型的修复可以在没有维护者批准的情况下提交：

Port 的基础设施更改（即现代化，但不改变功能）。例如，涵盖了转换为新的 USES 宏、启用详细构建以及切换到新的 Port 系统语法。
微小且已测试的构建和运行时修复。
Port 的文档或元数据更改，如 pkg-descr 或 COMMENT。

以下情况除外：由 Ports 管理团队 <> 或安全官员团队 <> 维护的任何内容。永远不允许未经授权的提交对这些团队管理的 Port 进行更改。

22.8.2. 我如何知道我的 Port 是否构建正确？

每周会多次构建包。如果 Port 失败，维护者将收到来自 [email protected] 的电子邮件。

所有包构建的报告（官方的、实验性的和非回归的）都汇总在。

22.8.3. 我添加了一个新 Port 。是否需要将其添加到 INDEX 文件中？

不需要。可以通过运行 make index 来生成该文件，或者通过 make fetchindex 下载一个预生成的版本。

22.8.4. 是否还有其他我不能触碰的文件？

任何直接位于 ports/ 下的文件，或者位于以大写字母开头的子目录中的文件（如 Mk/、Tools/ 等）。特别是， Port 管理团队 [] 非常在意 ports/Mk/bsd.port.mk* 文件，因此除非你愿意面对他们的怒火，否则不要对这些文件进行提交更改。

22.8.5. 当分发文件更改但版本没有改变时，更新 Port 的校验和的正确程序是什么？

当由于作者更新文件而不更改 Port 修订时，更新分发文件的校验和，提交信息中应包含原始文件和新文件之间相关差异的摘要，以确保分发文件没有被损坏或恶意更改。如果当前版本的 Port 已经在 Port 树中存在较长时间，通常可以在 ftp 服务器上找到旧的分发文件；否则，应联系作者或维护者了解为何分发文件发生更改。

22.8.6. 如何请求 Port 树的实验性测试构建（exp-run）？

在提交对 Port 树有重大影响的补丁之前，必须完成 exp-run。补丁可以针对 Port 树或基本系统。

使用提交者提供的补丁将进行完整的包构建，提交者需要在提交前修复检测到的问题（fallout）。

访问。
选择补丁涉及的产品。
像往常一样填写缺陷报告，记得附上补丁。
如果顶部显示“Show Advanced Fields”，点击它。它现在会显示为“Hide Advanced Fields”。此时将有更多的字段可用。如果已经显示为“Hide Advanced Fields”，则无需进行任何操作。

23. 非提交者开发者的特定问题

一些有权访问 FreeBSD 机器的人没有提交权限。几乎本文件的所有内容同样适用于这些开发者（除非是特定于提交的内容以及与提交相关的邮件列表成员资格）。特别是，我们建议你阅读：

注意
请确保你的导师将你添加到“附加贡献者”（doc/shared/contrib-additional.adoc）中——如果尚未列出你。

24. 关于 Google Analytics 的信息

自 2012 年 12 月 12 日起，FreeBSD 项目网站启用了 Google 分析，以收集关于网站使用的匿名统计数据。

注意
自 2022 年 3 月 3 日以降，FreeBSD 项目从网站中移除了 Google 分析。

25. 杂项问题

25.1. 如何访问 people.FreeBSD.org 来发布个人或项目信息？

people.FreeBSD.org 就是 freefall.FreeBSD.org。只需创建一个 public_html 目录。你放入该目录中的任何内容将自动显示在下。

25.2. 邮件列表归档存储在哪里？

邮件列表归档存储在 freefall.FreeBSD.org 上的 /local/mail 目录下。

25.3. 我想指导一位新提交者。我需要遵循什么流程？

请参阅内部页面上的文档。

26. FreeBSD 提交者的福利和特权

26.1. 认可

作为一名优秀的软件工程师的认可是最持久的价值。此外，有机会与每个工程师梦寐以求的最佳人合作，亦是巨大的特权！

26.2. FreeBSD 商城

FreeBSD 提交者可以在会议上从获得免费的 4-CD 或 DVD 套件。

26.3. `Gandi.net`

提供网站托管、云计算、域名注册和 X.509 证书服务。

Gandi 向所有 FreeBSD 开发者提供 E-rate 折扣。为了简化获取折扣的过程，首先设置 Gandi 账户，填写账单信息并选择货币。然后，使用你的 @freebsd.org 邮件地址发送邮件至，并注明你的 Gandi 账户。

26.4. `rsync.net`

提供针对 UNIX 用户优化的云存储服务，适用于外部备份。其服务完全在 FreeBSD 和 ZFS 上运行。

rsync.net 向 FreeBSD 开发者提供免费的 500 GB 永久账户。只需使用你的 @freebsd.org 邮件地址在上注册，即可获得此免费账户。

文章

编辑日志

hashtag点击页面左上角的“文章”可以选择其他内容

FreeBSD 中文文章翻译项目

目录

hashtag文章

文章

使用 FreeBSD 开发产品

hashtag摘要

hashtag1. 简介

hashtag1.1. 目标读者

hashtag1.2. 文章目标

hashtag1.3. 文章结构

hashtag2. FreeBSD 作为构建模块集

hashtag2.1. 使用 FreeBSD 构建

hashtag2.2. 技术

hashtag2.3. 组织结构

hashtag2.4. FreeBSD 发布工程流程

hashtag3. 与 FreeBSD 协作

hashtag3.1. 理解 FreeBSD 文化

hashtag3.2. 与 FreeBSD 项目合作的最佳实践

hashtag4. 结论

hashtag参考文献

FreeBSD 上的打印服务器（CUPS）

hashtag摘要

FreeBSD 状态报告流程

hashtag1. 为作者提供的写作指南

hashtag1.1. 介绍你的工作

hashtag1.2. 显示你工作的意义

hashtag1.3. 告诉我们一些新信息

hashtag1.4. 赞助

hashtag1.5. 待办事项

hashtag1.6. 提交报告

hashtag2. 编辑指南

hashtag2.1. 时间线

hashtag2.2. 征集报告

hashtag2.3. 构建报告

hashtag2.4. 发布报告

FreeBSD 对闰秒的支持

hashtag1. 介绍

hashtag2. FreeBSD 默认的闰秒处理

hashtag3. 注意事项

hashtag4. 测试

hashtag5. 结论

Port 导师指南

hashtag1. 导师/学员关系指南

hashtag1.1. 为什么做导师？

hashtag1.2. 导师/共同导师

hashtag1.3. 期望

hashtag1.4. 选择学员

hashtag1.5. 导师关系的持续时间

hashtag1.6. 导师/共同导师辩论

hashtag1.7. 期望

使用 FreeBSD 开发产品

hashtag摘要

hashtag1. 简介

hashtag1.1. 目标读者

hashtag1.2. 文章目标

hashtag1.3. 文章结构

hashtag2. FreeBSD 作为构建模块集

hashtag2.1. 使用 FreeBSD 构建

hashtag2.2. 技术

hashtag2.3. 组织结构

hashtag2.4. FreeBSD 发布工程流程

hashtag3. 与 FreeBSD 协作

hashtag3.1. 理解 FreeBSD 文化

hashtag3.2. 与 FreeBSD 项目合作的最佳实践

hashtag4. 结论

hashtag参考文献

FreeBSD 状态报告流程

hashtag1. 为作者提供的写作指南

hashtag1.1. 介绍你的工作

hashtag1.2. 显示你工作的意义

hashtag1.3. 告诉我们一些新信息

hashtag1.4. 赞助

hashtag1.5. 待办事项

hashtag1.6. 提交报告

hashtag2. 编辑指南

hashtag2.1. 时间线

hashtag2.2. 征集报告

点击页面左上角的“文章”可以选择其他内容

文章

摘要

1. 简介

1.1. 目标读者

1.2. 文章目标

1.3. 文章结构

2. FreeBSD 作为构建模块集

2.1. 使用 FreeBSD 构建

2.2. 技术

2.3. 组织结构

2.4. FreeBSD 发布工程流程

3. 与 FreeBSD 协作

3.1. 理解 FreeBSD 文化

3.2. 与 FreeBSD 项目合作的最佳实践

4. 结论

参考文献

摘要

1. 为作者提供的写作指南

1.1. 介绍你的工作

1.2. 显示你工作的意义

1.3. 告诉我们一些新信息

1.4. 赞助

1.5. 待办事项

1.6. 提交报告

2. 编辑指南

2.1. 时间线

2.2. 征集报告

2.3. 构建报告

2.4. 发布报告

1. 介绍

2. FreeBSD 默认的闰秒处理

3. 注意事项

4. 测试

5. 结论

1. 导师/学员关系指南

1.1. 为什么做导师？

1.2. 导师/共同导师

1.3. 期望

1.4. 选择学员

1.5. 导师关系的持续时间

1.6. 导师/共同导师辩论

1.7. 期望

摘要

1. 简介

1.1. 目标读者

1.2. 文章目标

1.3. 文章结构

2. FreeBSD 作为构建模块集

2.1. 使用 FreeBSD 构建

2.2. 技术

2.3. 组织结构

2.4. FreeBSD 发布工程流程

3. 与 FreeBSD 协作

3.1. 理解 FreeBSD 文化

3.2. 与 FreeBSD 项目合作的最佳实践

4. 结论

参考文献

1. 为作者提供的写作指南

1.1. 介绍你的工作

1.2. 显示你工作的意义

1.3. 告诉我们一些新信息

1.4. 赞助

1.5. 待办事项

1.6. 提交报告

2. 编辑指南

2.1. 时间线

2.2. 征集报告

2.3. 构建报告

2.4. 发布报告

点击页面左上角的“文章”可以选择其他内容

文章

1. 介绍

2. FreeBSD 默认的闰秒处理

3. 注意事项

4. 测试

5. 结论

1. 导师/学员关系指南

1.1. 为什么做导师？

1.2. 导师/共同导师