22.3 FreeBSD 开发参与指南

方法概述

翻译文档、提交 Port 都是不错的方法，提交 Bug 也是可行的方案。

首先需要阅读一下：https://wiki.freebsd.org/Phabricator

文档中说明得很清楚，需要先注册一个账号，并且可以关联 GitHub。但关联后你的用户名可能会显示得不太常见。

对于代码问题，一种较简单的解决方案是通过 GitHub Fork 原仓库的主分支（main），保持主分支不变，然后创建一个新的分支 B，用于开发和修改。

在完成修改或开发后，将 main 分支和 B 分支同步到最新状态（可在网页上点击更新按钮），然后在分支 B 下执行以下命令：

git pull   # 在当前分支下拉取远程更新
git checkout B   # 切换到分支 B
git diff -U999999 origin/main > 2023-1-24.diff   # 在分支 B 下生成与远程 main 分支的差异，并保存到 2023-1-24.diff 文件

完整的 git 提交操作示例

root@generic:~ # git clone https://github.com/ykla/freebsd-ports # 克隆 ykla/freebsd-ports 仓库到本地
you have mail
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 文件，将其上传到 此链接 备份（字体较小，请注意右上角位置），然后点击右上角的 Create 并填写相关信息，即可进行代码审阅。

这是一个相对简单的方法。需要注意，每次提交的修改量不宜过大。

提交完成后，在 https://bugs.freebsd.org/bugzilla 新建一个 Bug，说明修改内容，并附上 https://reviews.freebsd.org 备份 的链接。完成后，再在 https://reviews.freebsd.org 备份 中附上该 Bug 页面链接，否则可能长时间无人处理。

技巧

diff 文件不会被视为修改产生的文件，下次生成 diff 时无需提前删除上一次的 diff 文件。

上述操作适用于 FreeBSD 文档源（doc src）和 Ports，还有少部分操作需要在 GitHub 上进行，例如状态报告。

技巧

与相对封闭的 Linux 内核开发不同，任何人都可以参与修改 FreeBSD 的源代码。而 Linux 内核开发则需要向内核维护邮件列表发送邮件，并且必须得到负责人的审核和接受。

附录：一些可能用得到的命令

• 配置全局 Git HTTP 代理：

$ git config --global http.proxy http://192.168.1.169:7890

• 列出本地和远程的所有分支：

$ git branch -a

• 切换到本地分支 A：

$ git checkout A

如何开发 Port

建议阅读《FreeBSD Port 开发者手册》

FreeBSD 的软件以 Port 提供，开发者不需要考虑如何打包成二进制软件包等问题。Port 本身也不包含软件源代码，类似于 Gentoo（Gentoo 的 Portage 脱胎于 Ports），因此理论上移植难度并不高。

当你完成移植后，可以向 Bug 报告系统提交请求合并的报告（也可以直接发送到 https://reviews.freebsd.org/ 备份），具体格式可以参考列表中其他软件的示例。如果长时间无人响应，可以向邮件列表发送询问，确认是否有人能够协助提交。如果仍无人回应，可在一周后再次发送。

参考文献

• FreeBSD 镜像构建状态网页：https://ci.freebsd.org/ 备份。

• FreeBSD pkg 二进制软件包构建状态网页：https://pkg-status.freebsd.org/ 备份。

利用脚本自动生成 BSD libc 库文本

首先安装需要的软件包。

• 使用 pkg 安装：

# pkg install groff ghostscript10

• 或者使用 Ports 安装：

# cd /usr/ports/textproc/groff/ && make install clean
# cd /usr/ports/print/ghostscript10/ && make install clean

运行脚本即可在同路径文件夹下找到 PDF 文档。脚本和现成的文档参见：

https://github.com/FreeBSD-Ask/BSDlibc 备份

参考文献

• 原方案地址：where's bsd libc documentation? 备份。作者 mrclksr。原方案已失效。

对原方案的改进：

• if zgrep -q '.Lb libc' $i && zgrep -q '.Sh LIBRARY' $i; then 这一句的问题在于 .Lb libc 不仅匹配 libc，还会匹配 libcalendar 等以 libc 开头的库。可以改写为 .Lb libc$ 来解决此问题

• 正文的组织和排序不够合理，并未按功能模块或其他逻辑组合，因此用于学习并不合适，但用于快速查阅倒是可行。