Bazel C++ 构建系列文档(一):Bazel 简介与安装

1. 什么是 Bazel？

Bazel 是由 Google 开源的一款高性能、可扩展、多语言的构建与测试工具。它源自 Google 内部的构建系统 Blaze，于 2015 年开源，目前已被众多大型项目广泛采用，包括 TensorFlow、Kubernetes、Angular 等。

1.1 Bazel 的核心特性

特性	说明
增量构建	只重新编译发生变化的部分，大幅缩短构建时间
正确性保证	严格的依赖声明与沙箱隔离，确保构建结果可重现
多语言支持	原生支持 C++、Java、Python、Go、Rust 等 20+ 语言
可扩展性	支持大规模代码库（百万级文件）的高效构建
远程缓存与执行	支持分布式缓存和远程执行，实现团队级构建加速
可重现构建	通过沙箱和严格依赖，确保不同机器上的构建结果一致

1.2 为什么选择 Bazel 构建 C++？

C++ 项目构建长期以来面临诸多痛点，Bazel 针对性地解决了这些问题：

传统构建痛点                     Bazel 的解决方案─────────────────────────       ─────────────────────────头文件依赖管理混乱      →       严格的 hdrs 声明与依赖图增量编译不可靠          →       基于内容哈希的精确增量构建第三方依赖难以管理      →       声明式依赖（http_archive, git_repository）跨平台构建复杂          →       工具链（toolchain）与平台（platform）抽象构建结果不可重现        →       沙箱执行 + Hermetic 构建项目规模增长后变慢      →       远程缓存 + 远程执行 + 增量构建

1.3 Bazel vs 其他 C++ 构建工具

对比维度	Bazel	CMake	Make/Ninja	Meson
增量构建	✅ 精确（内容感知）	⚠️ 依赖配置	⚠️ 时间戳	⚠️ 依赖配置
远程缓存	✅ 原生支持	❌ 需第三方	❌ 需第三方	❌ 需第三方
远程执行	✅ 原生支持	❌ 不支持	❌ 不支持	❌ 不支持
多语言	✅ 20+ 语言	⚠️ 以 C/C++ 为主	❌ 仅构建	⚠️ 有限
依赖管理	✅ 声明式	⚠️ ExternalProject	❌ 手动	✅ Wrap 系统
学习曲线	⚠️ 较陡	⚠️ 中等	✅ 简单	✅ 较低
IDE 集成	⚠️ 改善中	✅ 广泛	⚠️ 一般	✅ 良好
大规模项目	✅ 优秀	⚠️ 一般	❌ 较差	⚠️ 一般

2. 安装 Bazel

2.1 系统要求

操作系统
：Windows 10/11、macOS 12+、Linux（glibc 2.17+）
JDK
：Bazel 7.x 需要 JDK 17+（Bazelisk 管理的 Bazel 自带 JDK）
C++ 编译器
：

Windows: MSVC (Visual Studio 2019+) 或 ClangCL
macOS: Xcode Command Line Tools
Linux: GCC 8+ 或 Clang 10+

2.2 推荐：使用 Bazelisk 安装

Bazelisk 是 Bazel 官方推荐的版本管理工具，它能根据项目配置自动选择正确的 Bazel 版本。

Windows

# 方法一：通过 winget 安装winget install Bazel.Bazelisk# 方法二：通过 Chocolatey 安装choco install bazelisk# 方法三：通过 Scoop 安装scoop install bazelisk# 方法四：手动下载# 从 https://github.com/bazelbuild/bazelisk/releases 下载 bazelisk-windows-amd64.exe# 重命名为 bazel.exe 并加入 PATH

macOS

# 方法一：通过 Homebrew 安装（推荐）brew install bazelisk# 方法二：通过 MacPorts 安装port install bazelisk

Linux

# 方法一：通过 Bazelisk 的 npm 包安装npm install -g @bazel/bazelisk# 方法二：手动安装# 1. 下载最新版本wget https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64# 2. 设置可执行权限chmod +x bazelisk-linux-amd64# 3. 移动到 PATH 中并重命名sudo mv bazelisk-linux-amd64 /usr/local/bin/bazel

2.3 版本固定：`.bazelversion` 文件

在项目根目录创建 .bazelversion 文件，Bazelisk 会自动使用该版本：

7.3.1

这确保团队所有成员使用相同的 Bazel 版本，避免版本不一致导致的构建问题。

2.4 验证安装

# 查看版本bazel --version# 输出示例：# bazel 7.3.1

注意：如果你的系统同时安装了 Bazel 和 Bazelisk，运行 bazel 时 Bazelisk 优先。你可以通过 which bazel（Linux/macOS）或 where bazel（Windows）确认实际使用的可执行文件。

3. Windows 环境特殊配置

由于你当前使用的是 Windows 环境，这里提供一些额外的配置建议：

3.1 安装 Visual Studio Build Tools

Bazel 在 Windows 上默认使用 MSVC 编译器：

# 使用 winget 安装 Visual Studio Build Toolswinget install Microsoft.VisualStudio.2022.BuildTools# 或通过 Chocolateychoco install visualstudio2022buildtools

确保安装了以下组件：

MSVC v143 - VS 2022 C++ x64/x86 生成工具
Windows 11 SDK

3.2 配置环境变量

# 设置 Bazel 的输出目录（默认在 %USERPROFILE%\_bazel_<username>）# 可选：将输出目录放到其他位置（如 SSD）env:BAZEL_DISK_CACHE = "D:\bazel_cache"

3.3 常见 Windows 问题

问题	解决方案
路径长度超限	在 `.bazelrc` 中添加 `startup --output_base=D:\b`
MSVC 找不到	确保 Visual Studio 安装了 C++ 工具集
符号链接权限不足	以管理员身份运行或启用开发者模式
中文路径问题	避免在含中文/空格的路径下构建

3.4 启用开发者模式（推荐）

开发者模式允许创建符号链接而无需管理员权限，这对 Bazel 很重要：

打开设置 → 系统 → 开发者选项
开启 开发人员模式

4. Bazel 项目结构概览

在开始深入之前，先了解一个典型 Bazel C++ 项目的目录结构：

my-project/├── WORKSPACE           # 工作区根标记 & 外部依赖声明├── .bazelversion       # Bazel 版本固定├── .bazelrc            # Bazel 配置选项├── BUILD               # 根包的构建规则（可选）├── MODULE.bazel        # Bazel 模块依赖（Bzlmod，Bazel 6+）├── src/│   ├── BUILD           # src 包的构建规则│   ├── hello.cc│   └── greet.h├── lib/│   ├── BUILD           # lib 包的构建规则│   ├── math.cc│   └── math.h└── tests/    ├── BUILD           # tests 包的构建规则    └── math_test.cc

关键文件说明：

文件	作用	是否必需
`WORKSPACE`	标记工作区根目录，声明外部依赖	✅ 必需
`BUILD`	定义包内的构建目标（target）	✅ 必需（每个包至少一个）
`MODULE.bazel`	Bzlmod 模块依赖声明	⚠️ 可选（推荐）
`.bazelversion`	固定 Bazel 版本	⚠️ 推荐
`.bazelrc`	构建选项配置	⚠️ 推荐

5. 第一个构建命令

即使还没有创建项目，你也可以验证 Bazel 是否正确安装：

# 初始化一个新项目目录mkdir hello-bazel && cd hello-bazel# 创建最简单的 WORKSPACE 文件echo "" > WORKSPACE# 创建最简单的 BUILD 文件cat > BUILD << 'EOF'cc_binary(    name = "hello",    srcs = ["hello.cc"],)EOF# 创建源文件cat > hello.cc << 'EOF'#include <iostream>int main() {    std::cout << "Hello, Bazel!" << std::endl;    return 0;}EOF# 构建bazel build //:hello# 运行bazel run //:hello

如果看到 Hello, Bazel! 输出，恭喜你，Bazel 已经可以正常工作了！

6. 小结

本篇介绍了：

✅ Bazel 的核心特性与优势
✅ Bazel 与其他构建工具的对比
✅ Bazel/Bazelisk 的安装方法
✅ Windows 环境的特殊配置
✅ 项目结构概览
✅ 第一个构建命令