Bear 编译数据库工具安装全指南：从发行版包管理器到 Rust 源码编译与打包定制

• 开发工具
• CLI

Bear（Build EAR）是一款为 Clang 工具链生成compile_commands.json编译数据库的开源工具，适用于任何无法原生导出编译数据库的 C/C++ 构建系统。本文以仓库根目录的 INSTALL.md 为主线，系统讲解 Bear 的四种落地方式：发行版包安装、Rust 源码编译安装、自定义前缀与库目录安装，以及面向发行版维护者的打包流程，并结合 scripts/install.sh、bear/src/installation.rs 等源码说明其安装布局的底层机制。读完本文，你将掌握在任何主流平台把 Bear 装好、配好、打包好，并能够独立排查安装布局相关的路径问题。

安装方式总览：先包管理器，再源码

Bear 已经存在较长时间，许多发行版都提供了经过充分测试的软件包，这是首选安装途径。只有在发行版仓库中找不到最新版本时，才推荐从源码编译。安装后即可以bear -- <构建命令>方式使用，工具会在当前工作目录写出compile_commands.json（详见 README.md 的用法说明）。

一、发行版包管理器安装

如果你所在发行版的仓库中已有 Bear 包，直接使用包管理器即可，无需关心 Rust 工具链、预加载库等底层细节。常见发行版的安装命令如下：

# Debian / Ubuntu sudo apt install bear # Fedora sudo dnf install bear # Arch Linux sudo pacman -S bear # macOS (Homebrew) brew install bear # FreeBSD pkg install bear

需要留意的是，部分包管理器可能仍分发 2.4.x 旧版本，其命令行风格与新版不同：旧版调用bear <构建命令>无需--分隔符，而新版要求bear -- <构建命令>。如果安装后执行报错或行为异常，请先核对本地包版本，必要时省略--或查阅随包文档。

二、从源码安装

前提条件

Bear 目前以 Rust 实现，因此源码构建需要 Rust 工具链，具体包括：

• Rust 工具链（1.85 或更高）：Bear 使用 Rust 2024 edition（见仓库根目录 Cargo.toml 中的edition = "2024"），最低要求 Rust 1.85+。可通过 rustup 安装，随后确认cargo与rustc已加入PATH：

  rustc --version # 必须 >= 1.85 cargo --version

• C 编译器：构建预加载库（intercept-preload）需要 C 编译器，cccrate 通常会自动探测到，请确保系统已安装gcc或clang。

• lld 链接器（Linux/ELF 平台）：这是很多用户容易忽略的一点。构建 Linux/ELF 平台的预加载库时，必须安装lld，因为 GNUld缺少构建所需的版本脚本多版本标签支持（详见 intercept-preload/build.rs 中的注释与-fuse-ld=lld链接参数）。

简单安装步骤

1. 克隆仓库：

   git clone https://gitcode.com/gh_mirrors/be/Bear.git cd Bear

2. 构建：

   cargo build --release

   工作区会产出bear-driver、bear-wrapper两个二进制（见 bear/Cargo.toml 的[[bin]]声明），以及 Unix 平台上的预加载库libexec.so（或 macOS 上的libexec.dylib）。

3. （可选）生成 shell 补全：

   target/release/generate-completions target/release/completions

   该命令来自 bear-completions crate，会为 bash、zsh、fish、elvish 四种 shell 分别生成补全脚本（bear.bash、_bear、bear.fish、bear.elv），核心实现在 bear-completions/src/bin/generate_completions.rs。

4. 安装：

   ./scripts/install.sh

   若第 3 步生成的completions目录存在于构建产物目录下，安装脚本会自动把四种 shell 的补全安装到各自的标准位置。

5. 验证安装：

   bear --version bear -- true # 冒烟测试——应生成一个空的 compile_commands.json

   bear -- true会在当前目录写出空的compile_commands.json，是验证安装是否可用的快速手段。

卸载

安装脚本不会生成卸载脚本。需要卸载时，手动删除已安装的文件即可，安装布局详见本文第五节末尾的目录树。删除对象主要包括：$PREFIX/bin/bear、$PREFIX/libexec/bear/整个目录、$PREFIX/share/doc/bear/、$PREFIX/share/man/man1/bear.1，以及各 shell 补全文件。

三、自定义安装

使用 PREFIX 指定安装前缀

默认情况下，安装脚本会根据执行身份自动选择前缀（见 scripts/install.sh 中的判断逻辑）：

• 以 root 身份运行时默认安装到/usr/local；
• 非 root 用户默认安装到$HOME/.local。

你可以通过环境变量PREFIX覆盖默认值：

sudo PREFIX=/usr ./scripts/install.sh

PREFIX是最终安装位置（如/usr、/usr/local、$HOME/.local），各组件会落入其下：二进制进入$PREFIX/bin/，库文件进入$PREFIX/libexec/bear/，依此类推。需要注意，安装脚本会拒绝PREFIX=/（避免覆盖根文件系统），并要求DESTDIR必须是绝对路径。

使用 INTERCEPT_LIBDIR 指定预加载库目录

预加载库目录名默认是lib。在需要不同目录名的系统上，必须在构建和安装两个阶段都设置INTERCEPT_LIBDIR，保持值一致：

# 构建时把正确的库目录编译进二进制 INTERCEPT_LIBDIR=lib64 cargo build --release # 安装时使用相同值，使文件被放到 bear-driver 期望的位置 INTERCEPT_LIBDIR=lib64 ./scripts/install.sh

之所以要"两阶段一致"，是因为bear-driver在编译期就把INTERCEPT_LIBDIR内嵌进了程序。从 bear/src/installation.rs 的源码可以看到，该值通过env!("INTERCEPT_LIBDIR")在编译时固化，默认值为lib，并由此推导预加载库的相对路径../<INTERCEPT_LIBDIR>/libexec.so。也就是说，运行时定位依赖的是编译期值，若构建与安装使用的目录名不一致，bear-driver将找不到libexec.so。

在基于 glibc 的 Linux 上，INTERCEPT_LIBDIR可以使用特殊值$LIB，动态链接器会在运行时将其展开为实际库目录（参见man ld.so）。在其他平台（macOS、musl、FreeBSD）上，请使用具体的目录名。

用户本地安装时的 shell 补全配置

当 Bear 安装到/usr、/usr/local这类系统前缀时，shell 通常会自动发现补全脚本。但安装到$HOME/.local时，需要手动告知 shell 补全位置：

Bash—— 在~/.bashrc中添加：

source "$HOME/.local/share/bash-completion/completions/bear"

Zsh—— 在~/.zshrc中（compinit之前）添加：

fpath=("$HOME/.local/share/zsh/site-functions" $fpath)

Fish—— 在~/.config/fish/config.fish中添加：

set -p fish_complete_path $HOME/.local/share/fish/vendor_completions.d

四、面向发行版维护者的打包指南

构建、生成补全、安装的标准流程

如果你是发行版打包维护者，推荐按以下步骤执行，三个环境变量各司其职：

INTERCEPT_LIBDIR=lib64 cargo build --release target/release/generate-completions target/release/completions DESTDIR=$pkgdir PREFIX=/usr INTERCEPT_LIBDIR=lib64 ./scripts/install.sh

三个变量的语义必须区分清楚：

• DESTDIR：构建 chroot / 打包阶段使用的暂存根目录，会被前置到所有安装路径之前（例如$DESTDIR/usr/bin/bear）；
• PREFIX：最终安装在目标系统上的前缀（如/usr）；
• INTERCEPT_LIBDIR：预加载库目录名（如lib64），构建与安装阶段必须一致。

不要把DESTDIR与PREFIX合并成一个值传入PREFIX。原因在于入口脚本会把PREFIX作为字面量运行时路径内嵌：安装脚本生成的$PREFIX/bin/bear只是一个 shell 脚本，内容形如$PREFIX/libexec/bear/bin/bear-driver "$@"（见 scripts/install.sh 的 ENTRY_SCRIPT 片段）。因此PREFIX必须与目标系统上的最终路径一致，而不能包含打包环境的 chroot 路径，否则安装到目标系统后脚本将指向不存在的路径。

平台差异：预加载库只在 Unix 构建

预加载库（libexec.so）仅在 Unix 平台上构建。Windows 构建只会产出bear-driver与bear-wrapper两个二进制。具体实现可查阅 intercept-preload/build.rs：Unix 分支会编译 C shim（intercept-preload/src/c/shim.c）并链接为共享库，非 Unix 平台则直接输出"不支持该平台"的警告。同样的平台判断也体现在安装脚本中：Linux/各 BSD 使用libexec.so，macOS 使用libexec.dylib，其他平台则跳过预加载库安装。

值得一提的构建细节是：macOS 使用-force_load与-exported_symbols_list控制符号导出并设置@loader_pathrpath；Linux/ELF 平台使用--whole-archive、动态生成的 version script，以及-fuse-ld=lld与$ORIGINrpath——这正是前文强调必须安装lld的原因。

相对路径定位机制

bear-driver在运行时通过相对路径定位它的兄弟工件：

• ./bear-wrapper：与bear-driver位于同一bin/目录；
• ../$INTERCEPT_LIBDIR/libexec.so：位于bin/上一级目录的INTERCEPT_LIBDIR子目录内。

这一约定在 bear/src/installation.rs 中被完整编码：InstallationLayout结构从bear-driver的可执行路径（current_executable）推导wrapper_path()与preload_path()。整个安装树中，唯一使用绝对路径的工件是$PREFIX/bin/bear入口脚本（它内嵌了PREFIX）。这意味着安装树内部可以整体搬移而不破坏相对定位，只要PREFIX与入口脚本中的字面量一致即可。

预期安装布局

完整安装后，目录结构应如下（摘自 INSTALL.md，与安装脚本实际行为一致）：

$PREFIX/ ├── bin/ │ └── bear (shell 脚本) ├── libexec/ │ └── bear/ │ ├── bin/ │ │ ├── bear-driver │ │ └── bear-wrapper │ └── $INTERCEPT_LIBDIR/ │ └── libexec.so └── share/ ├── bash-completion/ │ └── completions/ │ └── bear (可选) ├── zsh/ │ └── site-functions/ │ └── _bear (可选) ├── fish/ │ └── vendor_completions.d/ │ └── bear.fish (可选) ├── elvish/ │ └── lib/ │ └── bear.elv (可选) ├── doc/ │ └── bear/ │ ├── README.md │ └── COPYING └── man/ └── man1/ └── bear.1

其中各补全文件与文档、man 页均为可选组件：补全仅在构建产物目录存在completions/时才安装；man 页依赖 man/bear.1 的存在；文档来自 README.md 与 COPYING。打包时可依据此布局核对产物完整性。

安装后的验证与常见排查

完成安装后，建议按以下顺序做最终确认：

1. bear --version：确认可执行文件与版本正常；
2. bear -- true：确认拦截链路工作（应生成空的compile_commands.json）；
3. 若运行时报错提示找不到预加载库或bear-wrapper，优先检查两点：
   • 构建与安装阶段的INTERCEPT_LIBDIR是否一致；
   • 安装树是否符合上文第五节的标准布局（bear-driver与bear-wrapper是否同处bin/、libexec.so是否位于其上一级的$INTERCEPT_LIBDIR/中）。

掌握包管理器、源码编译、自定义前缀与打包四个层面的安装方法后，你便可以在任何目标环境中快速落地 Bear，并为后续的编译数据库生成工作奠定可靠的运行基础。更深入的使用参数与拦截原理，可继续阅读仓库中的 bear.1.md 与 requirements 目录下的相关设计文档。

• 开发工具
• CLI