# 22.3 FreeBSD 开发参与指南 ## 方法概述 FreeBSD 作为历史悠久的开源操作系统项目，其开发流程与贡献机制体现了分布式协作的最佳实践。参与 FreeBSD 开发不仅是技术贡献，更是融入全球技术共同体的过程。 参与 FreeBSD 开发有多种方式：翻译文档、提交 Port、提交 Bug 报告等都是可行的方案。 首先需要阅读 FreeBSD 项目代码评审与协作开发平台说明文档：。 文档中说明得很清楚，需要先注册一个账号，并且可以关联 GitHub。但关联后用户名可能会显示得不太常见。 对于代码问题，一种较简单的解决方案是通过 GitHub Fork 原仓库的主分支（main），保持主分支不变，然后创建一个新的分支 B，用于开发和修改。 在完成修改或开发后，将 main 分支和 B 分支同步到最新状态（可在网页上点击更新按钮），然后在分支 B 上执行以下命令： ```sh git pull # 在当前分支上拉取远程更新 git checkout B # 切换到分支 B git diff -U999999 origin/main > 2023-1-24.diff # 在分支 B 下生成与远程 main 分支的差异，并保存到 2023-1-24.diff 文件 ``` ## 完整的 git 提交操作示例 ```sh root@generic:~ # git clone https://github.com/freebsd/freebsd-ports # 克隆 freebsd-ports 仓库到本地 Cloning into 'freebsd-ports'... remote: Enumerating objects: 6264931, done. remote: Counting objects: 100% (15563/15563), done. remote: Compressing objects: 100% (9249/9249), done. remote: Total 6264931 (delta 6507), reused 14986 (delta 6260), pack-reused 6249368 (from 1) Receiving objects: 100% (6264931/6264931), 2.12 GiB | 10.73 MiB/s, done. Resolving deltas: 100% (3615966/3615966), done. Checking objects: 100% (16777216/16777216), done. Updating files: 100% (161546/161546), done. root@generic:~ # cd freebsd-ports/ root@generic:~/freebsd-ports # git branch -a # 查看分支 * main remotes/origin/HEAD -> origin/main remotes/origin/main remotes/origin/rpi-firmware root@generic:~/freebsd-ports # git checkout rpi-firmware # 切换到 rpi-firmware 分支，这是我自己通过 Github 网页创建的分支 branch 'rpi-firmware' set up to track 'origin/rpi-firmware'. Switched to a new branch 'rpi-firmware' root@generic:~/freebsd-ports # git diff -U999999 origin/main > 2024.diff # 生成与远程 main 分支的差异，并保存到 2024.diff 文件中 root@generic:~/freebsd-ports # ls -l 2024.diff -rw-r--r-- 1 root wheel 18021 Oct 6 03:59 2024.diff ``` 这样会在分支 B 的根目录下生成 .diff 文件，将其上传到 [此链接](https://reviews.freebsd.org/differential/) （字体较小，请注意右上角位置），然后点击右上角的 Create 并填写相关信息，即可进行代码审阅。 这是一个相对简单的方法。需要注意，每次提交的修改量不宜过大。 提交完成后，在 新建一个 Bug，说明修改内容，并附上 的链接。完成后，再在 中附上该 Bug 页面链接，否则可能长时间无人处理。 > **技巧** > > diff 文件不会被视作修改产生的文件，下次生成 diff 时无需提前删除上一次的 diff 文件。 上述操作适用于 FreeBSD 文档源（doc src）和 Ports，还有少部分操作需要在 GitHub 上进行，例如状态报告。 > **技巧** > > FreeBSD 源代码的修改参与方式较为灵活，任何人都可以通过代码评审系统提交修改。Linux 内核开发则主要通过内核维护邮件列表进行，提交的补丁需要经过负责人的审核和接受。 ### 附录：一些可能用得到的命令 * 配置全局 Git HTTP 代理： ```sh $ git config --global http.proxy http://192.168.1.169:7890 ``` * 列出本地和远程的所有分支： ```sh $ git branch -a ``` * 切换到本地分支 A： ```sh $ git checkout A ``` ## 如何开发 Port 建议阅读《FreeBSD Port 开发者手册》。 FreeBSD 的软件以 Port 提供，开发者不需要考虑如何打包成二进制软件包等问题。Port 本身也不包含软件源代码，类似于 Gentoo（Gentoo 的 Portage 脱胎于 Ports），因此理论上移植难度并不高。 当完成移植后，可以向 Bug 报告系统提交请求合并的报告（也可以直接发送到 ），具体格式可以参考列表中其他软件的示例。如果长时间无人响应，可以向邮件列表发送询问，确认是否有人能够协助提交。如果仍无人回应，可在一周后再次发送。 ### 参考文献 * FreeBSD Project. FreeBSD Jenkins\[EB/OL]. . 提供 FreeBSD 持续集成构建与测试状态的实时监控。 * FreeBSD Project. FreeBSD pkg 二进制软件包构建状态网页\[EB/OL]. . 提供了 Ports 包构建状态与失败分析的可视化界面。 ## 利用脚本自动生成 BSD libc 库文本 首先，安装需要的软件包。 * 使用 pkg 安装： ```sh # pkg install groff ghostscript10 ``` * 或者使用 Ports 安装： ```sh # cd /usr/ports/textproc/groff/ && make install clean # cd /usr/ports/print/ghostscript10/ && make install clean ``` ```sh /usr/ └── ports/ ├── textproc/ │ └── groff/ # groff 排版工具 Port └── print/ └── ghostscript10/ # Ghostscript 10 Port ``` 运行脚本即可在同路径文件夹下找到 PDF 文档。脚本和现成的文档参见：BSDlibc\[EB/OL]. \[2026-03-26]. . ### 参考文献 * FreeBSD Forums. mrclksr. where's bsd libc documentation?\[EB/OL]. 探讨 BSD libc 文档生成方法。原方案已失效。 对原方案的改进： * `if zgrep -q '.Lb libc' $i && zgrep -q '.Sh LIBRARY' $i; then` 这一句的问题在于 `.Lb libc` 不仅匹配 libc，还会匹配 libcalendar 等以 libc 开头的库。可以改写为 `.Lb libc$` 来解决此问题 * 正文的组织和排序不够合理，并未按功能模块或其他逻辑组合，因此用于学习并不合适，但用于快速查阅倒是可行。 ## 课后习题 1. Fork FreeBSD 源代码仓库，修复一个文档中的小问题，生成 diff 文件并提交代码审阅流程。 2. 分析 FreeBSD 与 Linux 内核贡献机制的差异，探讨其对社区参与门槛的影响。 3. 改进 BSD libc 文档生成脚本，按功能模块重新组织文档结构并生成新的 PDF 文档。