QA/Bibisect/Linux/zh-cn

此页面描述了在 GN/Linux 操作系统下使用我们提供的 Bibisect 仓库进行“二进制二分查找” 的详细指导. 如果您想了解 bibisect 的基础知识及简单原理，或者想要在其他操作系统上进行 bibisect, 请首先阅读 Bibisect 二进制二分查找.

简介
我们的 bibisect 仓库起初是在 buntu 64位机器上编译生成的. 一般情况下，这些仓库都可以在其它最新的现代化64位 GNU/Linux 发行版上运行（比如，Fedora, SuSE, Debian, 等等），尽管可能需要安装额外的软件包.

如果您是在跨平台进行测试，那么一个好的办法是使用虚拟机运行目标操作系统，然后进行 bibisect 测试. 请参考下面的部分.

选择一个 Bibisect 仓库（repository）
从下方的 表格中可以看出，bibisect 仓库有好多个，涵盖不同的源代码 commit 范围. 如果您在 LibreOffice 4.4.4 中发现了一个 bug，您可能需要下载 50max 仓库，因为它涵盖了 "从 4.4 分支点到 5.0 分支点之间的范围".

另外，通过测试您很有可能会发现在 LO 4.4.4 中发现的这个 bug 早在 4.4 分支点之前就已经存在了. 此时，您就需要下载其他更老的 bibisect 仓库. 我们将 bibisect 仓库拆分成多个，一方面是能提升 bibisect 时的操作速度，另一方面是避免下载过多不相关的范围.

有了 bibisect 仓库，但是不知道从哪个 bug 下手？您可以从这个清单中找到需要进行 bibisect 的 bug 报告.

环境搭建
下载 bibisect 仓库之前，请确保您已安装了必要的软件. 对于所有平台，您都需要安装：
 * git

下表列出了对于不同的操作系统以及不同的 bubisect 仓库，您需要额外安装的软件包：

下载 Bibisect 仓库
由于我们是分布式的、基于社区的项目，因此 bibisect 仓库分布于多个服务器上. 尽管下载每个仓库的方式可能有细微的差异，但是大部分 bibisect 仓库都可以使用常规的下载方式从网上下载，或者直接通过 git clone 下载. 下载链接可从下方的 版本列表 中找到.

从 Web 服务器上下载
以 50max 仓库为例，首先下载该仓库对应的 .tar.xz 文件，然后通过如下 linux 的解压缩命令将该 git 仓库解压：

校验
To verify one of our repos, you'll need the gpg-key of the person/organization who produced it.

For example, to verify the 43all repo, you'll need the gpg-key from https://launchpad.net/~bjoern-michaelsen and will want to check the signature as follows:

使用 git 克隆的方式下载
举个例子，bibisect-linux-64-7.0-CN 可从中文社区志愿者的服务器上获得. 您可以像克隆任何其他的 git 仓库一样来克隆它：

需要注意的是，原始的仓库可能有好几个 GB 大小，因此您需要有很好而且可靠的互联网连接. 由于 git clone 自身不支断点续传，所以如果由于网络问题而下载中断，您将不得不重新开始克隆. :-( 为了避免这一点，您可以：

# 使用 --depth=1 进行首次克隆， # 通常情况下这将下载小于 1GB 的内容，对于某些仓库可能只有 300MB 左右： > git clone --depth=1 git://go.suokunlong.cn/lo/bibisect-linux-64-7.0-CN # 然后使用 git 一点一点拉取剩余的内容（这类似于变相地断点续传）： > cd linux-64-6.2 > git pull --depth=1000 # 然后再 2000, 5000, 10000... # 之后，如果您对网络连接比较放心，可以直接将下载的这个仓库转换为 unshallow 版本： git pull --unshallow

首次克隆之后，后续如果该仓库有更新，那么可以通过 git pull 来获取，此时的下载量将会很小，这取决于 Tinderbox 添加新的编译包的频率，以及您多久进行一次 git pull.

开始 bibisect”
找到一个需要进行“倒退“测试的 bug, 以及重现该 bug 的明确步骤，并且有了下载好并已解压缩的 bibisect 仓库，现在您就可以随时进行 bibisect 操作了.

从现在开始， latest 指向您所用的 bibisect 仓库中最新的版本，oldest 指向该仓库中最老的版本. 很多仓库都已经标记好了 latest/oldest 对应的tag标记，如果没有这些tag，那么您可以使用对应的 hash 值来表示最新和最老的版本. hash 值可以使用如下的 git 命令获得，这两个命令所显示的第一个 hash值，分别对应的是最新的和最老的版本：

（提示：在 git log 界面中，按下 q 键可退出 log 显示）

然后，打开命令行终端，切换到相应的 git bibisect 仓库所在的目录，检出 latest 提交，然后运行 soffice:

在 bibisect-linux-64-5.3, bibisect-linux-64-5.4 以及其他比较新的仓库中，您需要使用以下命令：

如果 bug 在当前检出的版本中不存在，那么请在 bug 里添加如下评论："Regression does not appear in latest version of <您使用的 bibisect 仓库名称>, 比如 bibisect-43all.tar.xz and must be younger"，并在 Keywords 字段添加标签 bibisected 以及 bibisectedNewer. 至此，您已经完成了 bibisect! 如果还有其它更新的 bibisect 仓库可用，那么您可以下载它，并在这个更老新的仓库中继续 bibisect 这个 bug.

如果 bug 在 latest 版本中存在，那么接下来我们检出 oldest 版本，看看 bug 在该仓库所包含的最早版本中是否存在：

在 bibisect-linux-64-5.3, bibisect-linux-64-5.4 以及其他比较新的仓库中，您需要使用以下命令：

如果此时 bug 已经存在，说明这个 bug 不是在您所用的这个仓库所涵盖的范围中产生的，而是一个更老的 bug，需要在更老的 bibisect 仓库中进行测试. 因此：

首先，在 bug 中添加一则评论，写明 "Regression does appear in oldest version of <您所用的 bibisect 仓库名称> and must be older"

如果您用的是 43all 仓库，那么：
 * 1) 在 Keywords 字段添加 preBibisect 关键词，然后
 * 2) 将 bug 的 Version 字段修改为 3.5beta0（这个是您能设置的最老版本）.

如果 bug 在 oldest 版本中不存在（但是在 latest 版本中存在），这表明 bug 是在您正在使用的这个仓库所涵盖的某个范围内产生的，此时您需要进行下一步，以缩小范围（这时候您应该很开心，离成功不远了！）. 接下来，我们需要借助 git 的一个强大的工具进行非常高效率的 二分查找（binary search）:

在 bibisect-linux-64-5.3, bibisect-linux-64-5.4 以及其他比较新的仓库中，您需要使用以下命令：

然后重复以下命令：

在 bibisect-linux-64-5.3, bibisect-linux-64-5.4 以及其他比较新的仓库中，您需要使用以下命令：

提示：很多时候，检查的某个 LibreOffice 版本可能根本无法正常启动. 这可能是由于：虽然 bibisect 仓库最大程度上确保仅包含能正常启动的版本，但是所包含进来的某些版本可能实际上根本无法运行. 在这种情况下，您可能需要 跳过 这个不能运行的版本：

经过几次重复，git 将会显示如下的输出信息： 9625329ea5a7e3e8475cd21c07726beec20573bd is the first bad commit commit 9625329ea5a7e3e8475cd21c07726beec20573bd Author: Bjoern Michaelsen  Date:  Thu Dec 8 12:29:59 2011 +0100

source-hash-2d19e9bb07ccff3134f855812dddfda5c07b1fe4 commit 2d19e9bb07ccff3134f855812dddfda5c07b1fe4 Author:    Jan Holesovsky  AuthorDate: Wed Nov 16 14:17:03 2011 +0100 Commit:    Jan Holesovsky  CommitDate: Wed Nov 16 14:21:33 2011 +0100 Kill one usage of chrel.sed to fix build.

我们需要将这条重要的输出信息添加到 bug 报告的评论里. 这条信息里，最重要的部分是 source-hash-2d19e9bb07ccff3134f855812dddfda5c07b1fe4 这一行，它代表了“第一个坏版本”对应的源代码的 hash 值. 但是，请在 bug 报告中包含完整的信息.

如果您能同时将 git log 也添加到 bug 的评论里（与上面的输出信息放到一起添加），对开发者可能会更有帮助：

下面是一个 git log 的输出示例（选择这些文字，右键单击，然后复制. 按下 q 键退出）：

git bisect start 'latest' 'oldest' # good: [2faf4bc12ab490370d2196dedbc8091f9b09d0a5] source-hash-418a35f4861e863feb39eec73f4a39a87fbcb1f3 git bisect good 2faf4bc12ab490370d2196dedbc8091f9b09d0a5 # bad: [b6fca7e58854bc617c5fc9a75d1c1720b0d7e1a4] source-hash-ce60138d339a5eb2a174a5d27063249acf2cac42 git bisect bad b6fca7e58854bc617c5fc9a75d1c1720b0d7e1a4 # good: [0a28a62d53e996cf66d86e9bfb63ddc6ade75b7e] source-hash-71cbcb62028295a98ceee60cb4c4ee425bafcd2e git bisect good 0a28a62d53e996cf66d86e9bfb63ddc6ade75b7e # bad: [9625329ea5a7e3e8475cd21c07726beec20573bd] source-hash-2d19e9bb07ccff3134f855812dddfda5c07b1fe4 git bisect bad 9625329ea5a7e3e8475cd21c07726beec20573bd # good: [89d91bb6074026dc0894bcdc6aaf8f6124102da7] source-hash-fb754a0df859e30255c25af8fa19bfaa75f257e7 git bisect good 89d91bb6074026dc0894bcdc6aaf8f6124102da7

至此，您已经完整完成了这个 bug 的 bibisect. 您需要添加 bibisected 关键词到 bug 的 Keywords 字段，这样别人就能知道这个 bug 已经 bibisect 过了，并且不会再显示在需要 bibisect 的 bug 清单里.

通过 bibisect 找到修复了某个 bug 的 commit（逆向 bibisect）
要找到修复了某个问题的 commit，您可以使用以下方法：

测试时，请根据情况使用  或者

bibisect 仓库中的 git tag 标记
在 43all 仓库中，有诸如,   这样的 git 标记 (tag), 这些标记对应的是该版本在 master 分支上被分离的时点（分支点）的提交. 如果有一个 bug 是在 4.0 和 4.1 之间产生的，那么您可以进行如下查找：

这个命令限定了 git 仅在  和   之间进行二分查找. 需要注意，某个版本的分支点会比这个版本首个正式发布的时间点要早很多（正式发布的版本在分支点之后至少要经历多次的 alpha 和 beta 阶段）. 这意味着，某个 bug 在某个版本的分支点是好的，但是 bug 很可能在这个版本分支点之后的阶段产生. 但是这种 bug 仍然可以在 master 分支上被 bibisect 查找出来（在两个主版本分支点之间的范围内），这是因为几乎所有的源代码提交都会首先在 master 分支上体现. 所有，对于这样的情况您需要有些耐心，并保持头脑清醒.

针对 daily dbgutil 仓库的特殊考虑
El每个版本中都有 build-info.txt 文件，这个文件的第一行包含了这个编译版本对应的源代码希哈值（source-hash）. 请将第一个好的版本以及第一个坏的版本分别对应的 source hash 与 bibisect 结果一起包含在 bug 报告的评论里，这些信息很有用.

使用 max 仓库系列
请务必阅读这些仓库中的 README 文件，该文件中指出在首次运行前需要执行以下 git 命令：

这些 "max" 仓库 (43max, 44max, 50max) 中，对于每一个 master 分支上的源代码提交 (commit) 都对应有一个编译的二进制提交，但有如下的例外情况：
 * 忽略仅影响除64位体系结构之外的架构的 commit；
 * 损坏的编译会与后续成功的编译合并为一个 commit.

如果某个损坏的编译被跳过，则这条提交的消息中会包含如下的说明： (Bibisect: This commit covers source commit(s) ...... which failed to build)

在这种情况下，特定的源代码无法范围无法准确定位，需要进行进一步的调查分析.

在所有其他情况下（指没有已跳过的已损坏的编译），则 bibisect 所得到的结论与在源代码层面进行 git bisect 是一致的（这是因为这种仓库里一个源代码对应一个编译）. 此时，您完全可以在 bug 报告的 Keywords 字段同时加入 bisected 和 bibisected 两个关键词.

Youtube 视频教程
一部简短的视频教程 (Youtube，墙外)，由 Florian Reisinger 提供.
 * （非常抱歉，这部视频的音频质量不太好）. 

VM 虚拟机
考虑到 bibisect 仓库的庞大体积，以及在 Windows 或者 macOS 主机下测试 GNU/Linux 系统上的 bug 的需要，使用虚拟机是个好主意.

环境建议：
 * 虚拟机软件：VirtualBox
 * Guest 系统：Ubuntu 14.04 x86_64 （桌面版）
 * (虚拟) 磁盘空间：至少 40GB (有些 bibisect 仓库每个可能有 10GB 大小)

简要指南 - 仅 Linux 下

 * 1) 下载仓库（有好几个G大小，不要担心，您只需要下载一次）- 见
 * 2) 将下载得到的仓库解压缩的磁盘上的某个位置.
 * 3) 打开命令行终端，并确保 git 及 libjpeg62 已安装. 在 Ubuntu 系统上，可通过 sudo apt-get install git libjpeg62 安装.
 * 4) 进入到解压缩得到的仓库的位置： cd [下载后解压缩得到的仓库位置]
 * 5) 开始”二进制二分查找“. git bisect start latest oldest 注意此处的"latest"和"oldest"是bibisect仓库中git tag的名称，但是在某些仓库中可能并没有标记这些名称的tag，此时您需要通过 git log 定位最新和最老的 commit. 另请注意，此处用的是"bisect", 而不是"bibisect"，因为bibisect根本不是git中的一个指令，git中只有bisect. 其本质是，基于 LibreOffice 的源代码先进行编译，然后将编译得到的二进制程序做成了一个git仓库，在该git仓库中进行bisect，与git本身的bisect类似，不同支出在于您不用在二分查找时先编译再运行.
 * 6) 在当前的 revision 处运行 LibreOffice: ./opt/program/soffice
 * 7) 尝试在当前 revision 上重现 bug.
 * 8) 如果不能重现该 bug, 则标记为： git bisect good
 * 9) 如果能重现该 bug，则标记为： git bisect bad
 * 10) 重复第6和第7步，直到您得到类似这样的信息： 5a52acff89c733acbd4be6896748c76a010cb507 is the first bad commit
 * 11) 得到您bibisect操作的日志信息，并将其复制粘贴到 bug 报告中： git bisect log

版本
下表中包含了从 3.5beta0 到 当前 master 分支范围内的各个 bibisect 仓库.

较老的 dbgutil daily 仓库

 * 5.4 -> 6.0: [git://dev-downloads.libreoffice.org/lo-linux-dbgutil-daily-till60.git repo] (5.1G)
 * 5.3 -> 5.4: [git://dev-downloads.libreoffice.org/lo-linux-dbgutil-daily-till54.git repo] (4.8G)
 * 5.2 -> 5.3: [git://dev-downloads.libreoffice.org/lo-linux-dbgutil-daily-till53.git repo] (4.3G)
 * 5.1 -> 5.2: [git://dev-downloads.libreoffice.org/lo-linux-dbgutil-daily-till52.git repo] (4.1G)
 * 5.0 -> 5.1: [git://dev-downloads.libreoffice.org/lo-linux-dbgutil-daily-till51.git repo] (4.5G)
 * 4.4 -> 5.0: [git://dev-downloads.libreoffice.org/lo-linux-dbgutil-daily-till50.git repo] (4.7G)
 * 4.3 -> 4.4: [git://dev-downloads.libreoffice.org/lo-linux-dbgutil-daily-till44.git repo] (4.5G)
 * 4.2 -> 4.3: [git://dev-downloads.libreoffice.org/lo-linux-dbgutil-daily-till43.git repo] (4.3G)
 * 4.1 -> 4.2: [git://dev-downloads.libreoffice.org/lo-linux-dbgutil-daily-till42.git repo] (3.4G)
 * 更更老的版本

解决 'librtmp.so.0: cannot open shared object file' 错误
I experienced this problem with bibisect-50max repository

1. 检查 librtmp 是否已安装 locate librtmp

/usr/lib/x86_64-linux-gnu/librtmp.so.1 /usr/share/doc/librtmp1 /usr/share/doc/librtmp1/changelog.Debian.gz /usr/share/doc/librtmp1/copyright /var/lib/dpkg/info/librtmp1:amd64.list /var/lib/dpkg/info/librtmp1:amd64.md5sums /var/lib/dpkg/info/librtmp1:amd64.postinst /var/lib/dpkg/info/librtmp1:amd64.postrm /var/lib/dpkg/info/librtmp1:amd64.shlibs /var/lib/dpkg/info/librtmp1:amd64.symbols

2. 创建符号链接 sudo ln -s /usr/lib/x86_64-linux-gnu/librtmp.so.1 /usr/lib/x86_64-linux-gnu/librtmp.so.0

解决 'libboost_filesystem-mt.so.1.53.0: cannot open shared object file' 错误
这个问题会在 bibisect-linux-64-5.3 仓库中发生，是由于在这个仓库中从 开始将 liborcus-0.11.so.0 链接到了这个动态库中.

1. 安装您的发行版的 libboost_filesystem

2. 创建符号链接 sudo ln -s /usr/lib/x86_64-linux-gnu/libboost_filesystem.so /usr/lib/x86_64-linux-gnu/libboost_filesystem-mt.so.1.53.0