Bazel项目目录结构

Bazel 是由 Google 开发的一款高效的构建和测试工具，广泛应用于大型项目中。Bazel 使用一套特定的文件结构和配置文件来描述项目的构建过程。以下是 Bazel 常见的文件结构及各个文件的详细作用介绍：

1. 项目根目录结构

一个典型的 Bazel 项目根目录结构可能如下所示：

my_project/
├── WORKSPACE
├── .bazelrc
├── BUILD
├── src/
│   ├── BUILD
│   ├── main/
│   │   ├── BUILD
│   │   ├── app/
│   │   │   ├── BUILD
│   │   │   └── ...
│   │   └── lib/
│   │       ├── BUILD
│   │       └── ...
│   └── test/
│       ├── BUILD
│       └── ...
├── third_party/
│   ├── BUILD
│   └── ...
└── README.md

1.1. 根目录文件

• WORKSPACE

  • 作用：WORKSPACE 文件位于项目的根目录，用于定义项目的外部依赖和工作区信息。通过此文件，Bazel 知道如何获取和管理项目所依赖的第三方库、工具链等。

  • 内容示例：

    workspace(name = "my_project")
    
    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
    
    http_archive(
        name = "rules_python",
        url = "https://github.com/bazelbuild/rules_python/archive/refs/tags/0.1.0.tar.gz",
        strip_prefix = "rules_python-0.1.0",
    )
    
    load("@rules_python//python:repositories.bzl", "py_repositories")
    
    py_repositories()
    

• .bazelrc

  • 作用：.bazelrc 文件用于配置 Bazel 的构建选项和参数。通过此文件，用户可以为不同的构建命令（如 build、test 等）设置默认参数，简化命令行操作。

  • 内容示例：

    common --copt=-O2
    build --jobs=4
    test --test_output=errors
    

• BUILD

  • 作用：根目录下的 BUILD 文件用于定义项目的顶层构建规则。虽然通常在子目录中定义具体的 BUILD 文件，但根目录的 BUILD 文件适用于需要在整个项目级别管理的构建目标。

  • 内容示例：

    load("//src/main:defs.bzl", "my_app")
    
    my_app(
        name = "my_app",
        srcs = glob(["src/main/app/**/*.java"]),
        deps = [
            "//src/main/lib:lib",
        ],
    )
    

1.2. 子目录文件

• src/

  • 作用：存放源代码的目录。通常会按照功能模块或组件进一步划分子目录，如 main/ 和 test/。

• src/BUILD

  • 作用：定义 src 目录下的一些通用构建规则或聚合性规则，便于管理子模块的依赖关系。

• src/main/BUILD

  • 作用：定义主应用程序的构建规则，包括应用程序的源代码、依赖库等。

• src/main/app/

  • 作用：存放应用程序具体实现的目录。

• src/main/app/BUILD

  • 作用：定义应用程序模块的具体构建规则，如编译 Java 文件、打包等。

• src/main/lib/

  • 作用：存放库代码的目录，供应用程序或其他模块依赖。

• src/main/lib/BUILD

  • 作用：定义库模块的构建规则，如编译库代码、生成库文件等。

• src/test/

  • 作用：存放测试代码的目录。

• src/test/BUILD

  • 作用：定义测试模块的构建规则，如编译测试代码、运行测试用例等。

• third_party/

  • 作用：存放第三方依赖库的目录。这些依赖通常通过 WORKSPACE 文件中定义的规则进行管理，但部分手动添加的第三方库也会放在此目录。

• third_party/BUILD

  • 作用：定义第三方库的构建规则，指定如何编译和链接这些外部库。

1.3. 其他文件

• README.md

  • 作用：项目的说明文档，介绍项目的功能、使用方法、构建流程等信息。

2. 主要 Bazel 文件详细介绍

2.1. WORKSPACE 文件

WORKSPACE 文件是 Bazel 项目的入口文件，用于定义工作区的根，并管理外部依赖。它的主要职责包括：

• 定义工作区名称：通过 workspace(name = "my_project") 指定工作区的名称。
• 引入外部依赖：使用 http_archive、git_repository 等规则下载和管理第三方库。
• 加载规则和工具链：通过 load 语句引入自定义规则或工具链配置。

常见用法示例：

workspace(name = "my_project")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rules_go",
    urls = ["https://github.com/bazelbuild/rules_go/releases/download/v0.29.0/rules_go-v0.29.0.tar.gz"],
    strip_prefix = "rules_go-0.29.0",
)

load("@rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")

go_rules_dependencies()
go_register_toolchains()

2.2. BUILD 文件

BUILD 文件定义了项目中的构建目标和规则。每个 BUILD 文件对应一个目录，并描述该目录下的源代码如何被构建。

主要构建规则类型：

• cc_library / cc_binary：用于 C++ 库和可执行文件的构建。
• java_library / java_binary：用于 Java 库和可执行文件的构建。
• py_library / py_binary：用于 Python 库和可执行文件的构建。
• go_library / go_binary：用于 Go 语言库和可执行文件的构建。
• genrule：用于自定义生成命令的构建规则。

BUILD 文件示例：

cc_library(
    name = "math_lib",
    srcs = ["math.cpp"],
    hdrs = ["math.h"],
    visibility = ["//visibility:public"],
)

cc_binary(
    name = "app",
    srcs = ["main.cpp"],
    deps = [":math_lib"],
)

BUILD 文件中的关键字段：

• name：目标名称。
• srcs：源文件列表。
• hdrs：头文件列表（主要适用于 C/C++ 项目）。
• deps：依赖的其他构建目标。
• visibility：定义目标的可见性范围。

2.3. .bazelrc 文件

.bazelrc 文件用于配置 Bazel 构建的默认参数和选项。可以定义不同的构建模式（如 debug、release）、优化选项、并行构建设置等。

常见配置示例：

# 全局通用选项
build --copt=-O2
build --host_copt=-O2

# 调试模式
build:debug --compilation_mode=dbg
build:debug --strip=never

# 发布模式
build:release --compilation_mode=opt
build:release --strip=always

# 测试配置
test --test_output=errors
test --cache_test_results=no

# 并行构建
common --jobs=8

# 限制 Bazel 的内存使用， HOST_RAM 表示系统总内存（需替换为实际值），*.5 表示使用总内存的 50%
# 限制 CPU 核心数：可并行使用的 CPU 核心数为 6
build --local_ram_resources=HOST_RAM*.5 --local_cpu_resources=6
# 启用磁盘缓存：将构建中间结果（如编译的 .o 文件、生成的代码）缓存到指定目录（~/bazel-cache）
build --disk_cache=~/bazel-cache

使用方法：
可以通过命令行指定使用特定的配置，例如：

bazel build --config=release //src/main:app

2.4. WORKSPACE 之外的常见文件

• .gitignore

  • 作用：列出应被 Git 忽略的文件和目录，通常包括 Bazel 的输出目录（如 bazel-bin/、bazel-out/ 等）和临时文件。

  • 示例：

    bazel-*
    *.launch
    *.log
    

• BUILD.bazel

  • 作用：与 BUILD 文件功能类似，Bazel 也支持使用 BUILD.bazel 作为构建文件的名称，以避免与目录中的其他 BUILD 文件混淆。

3. Bazel 构建过程中的文件结构

在 Bazel 的构建过程中，Bazel 会维护一组中间文件和输出文件，这些文件主要存储在 Bazel 的输出目录（默认是 bazel-out/）中。以下是相关目录及其作用：

• bazel-out/

  • 作用：存放 Bazel 构建过程中的所有中间文件和最终输出。例如，编译生成的二进制文件、生成的中间对象文件、缓存文件等。

• bazel-bin/

  • 作用：存放最终可执行文件和库文件的符号链接，指向 bazel-out/ 中对应的实际文件。

• bazel-genfiles/

  • 作用：存放通过生成规则（如 genrule、proto_library 等）生成的文件。

• bazel-testlogs/

  • 作用：存放测试运行的日志和报告文件。

这些目录通常会被自动管理，用户无需手动干预。

4. 示例项目说明

以下是一个简单的 Bazel 项目示例，帮助理解上述文件结构及其作用：

my_project/
├── WORKSPACE
├── .bazelrc
├── BUILD
├── src/
│   ├── BUILD
│   ├── main/
│   │   ├── BUILD
│   │   ├── app/
│   │   │   ├── BUILD
│   │   │   ├── main.cpp
│   │   │   └── ...
│   │   └── lib/
│   │       ├── BUILD
│   │       ├── math.cpp
│   │       └── math.h
│   └── test/
│       ├── BUILD
│       ├── test_main.cpp
│       └── ...
└── third_party/
    ├── BUILD
    └── external_lib/
        ├── lib.cpp
        └── lib.h

4.1. WORKSPACE 文件

workspace(name = "my_project")

# 引入第三方 C++ 库示例
http_archive(
    name = "external_lib",
    urls = ["https://example.com/external_lib.tar.gz"],
    strip_prefix = "external_lib-1.0.0",
)

load("@external_lib//:defs.bzl", "external_lib_rules")

external_lib_rules()

4.2. 根目录 BUILD 文件

# 定义顶层应用程序目标
cc_binary(
    name = "my_app",
    srcs = ["src/main/app/main.cpp"],
    deps = [
        "//src/main/lib:math_lib",
        "@external_lib//:external_lib",
    ],
)

4.3. src/main/lib/BUILD 文件

cc_library(
    name = "math_lib",
    srcs = ["math.cpp"],
    hdrs = ["math.h"],
    visibility = ["//visibility:public"],
)

4.4. src/test/BUILD 文件

cc_test(
    name = "math_test",
    srcs = ["test_main.cpp"],
    deps = [
        "//src/main/lib:math_lib",
        "@external_lib//:external_lib",
    ],
)

4.5. .bazelrc 文件

# 优化构建选项
build --copt=-O2
build --host_copt=-O2

# 并行构建设置
common --jobs=8

# 测试配置
test --test_output=errors

5. 自定义规则和扩展

Bazel 允许用户通过 Starlark（Bazel 的配置语言）自定义构建规则和扩展功能。这些自定义规则通常放在 defs.bzl 或类似的 .bzl 文件中，并在 BUILD 文件中加载和使用。

5.1. 自定义规则示例

defs.bzl 文件内容：

def my_app(name, srcs, deps=[]):
    cc_binary(
        name = name,
        srcs = srcs,
        deps = deps + ["//src/main/lib:math_lib"],
    )

BUILD 文件中的使用：

load("//src/main:defs.bzl", "my_app")

my_app(
    name = "my_custom_app",
    srcs = ["app/custom_main.cpp"],
    deps = [
        "@external_lib//:external_lib",
    ],
)

通过自定义规则，可以简化构建过程，避免在多个 BUILD 文件中重复定义相似的构建逻辑。

6. 总结

Bazel 通过明确的文件结构和配置文件，实现了高效、可重复和可扩展的构建流程。

• WORKSPACE：定义工作区和外部依赖。
• BUILD（或 BUILD.bazel）：定义构建目标和规则。
• .bazelrc：配置构建选项和参数。
• 源代码目录结构：根据项目需求组织源代码和模块。
• 第三方依赖目录：管理外部库和工具。