如何在Bazel中搜索包外头文件及配置cc_library的hdrs与includes

一、搜索包外头文件的核心思路 #

Bazel的构建基于**包（Package）**边界，要访问包外的头文件，必须满足两个前提：

1. 头文件所在目录是合法的Bazel包（即目录下存在BUILD文件，哪怕是空文件）；
2. 当前包对目标头文件或其所在规则有访问权限（通过visibility控制）。

常见实现方式分为两种：

• 依赖其他包中封装头文件的cc_library规则；
• 在当前规则中直接指定包外头文件路径并配置搜索目录。

二、cc_library规则中指定包外hdrs和includes属性 #

1. 直接指定包外hdrs #

通过普通文件系统相对路径直接引用包外头文件，比如../other_pkg/header.h。

示例目录结构：

workspace/
├── my_pkg/
│   └── BUILD
└── external_pkg/
    ├── BUILD  # 必须存在，哪怕内容为空
    └── common/
        └── utils.h

my_pkg/BUILD配置：

cc_library(
    name = "my_lib",
    hdrs = ["../external_pkg/common/utils.h"],
    # 配置搜索目录，代码中可直接#include "utils.h"
    includes = ["../external_pkg/common"],
)

2. 结合strip_include_prefix简化路径 #

针对长路径的头文件，用strip_include_prefix去掉路径前缀，配合includes简化代码中的引用写法。

示例：

cc_library(
    name = "my_lib",
    hdrs = ["../external_pkg/include/project/utils.h"],
    # 去掉前缀后，头文件有效路径为project/utils.h
    strip_include_prefix = "../external_pkg/include",
    # 设置搜索根目录，代码中可#include "project/utils.h"
    includes = ["."],
)

3. 依赖其他包的cc_library（推荐） #

将包外头文件封装为独立的cc_library，通过依赖引入，这是Bazel推荐的模块化做法，便于维护可见性和依赖关系。

external_pkg/BUILD配置：

cc_library(
    name = "common_headers",
    hdrs = ["common/utils.h"],
    # 允许my_pkg访问该规则
    visibility = ["//my_pkg:__pkg__"],
    # 配置搜索目录，依赖它的规则可直接引用utils.h
    includes = ["common"],
)

my_pkg/BUILD配置：

cc_library(
    name = "my_lib",
    srcs = ["my_code.cc"],
    # 通过依赖引入外部头文件
    deps = ["//external_pkg:common_headers"],
)

此时my_code.cc中直接写#include "utils.h"即可引用目标头文件。

三、注意事项 #

• 所有涉及的包外目录必须存在BUILD文件，否则Bazel会拒绝访问该目录下的文件；
• 跨多包共享头文件时，建议将头文件放在独立包中，并设置合适的visibility（比如visibility = ["//visibility:public"]允许所有包访问）；
• 避免在hdrs中使用过于宽泛的glob（比如glob(["../**/*.h"])），会增加Bazel分析负担，不利于依赖管理。

内容的提问来源于stack exchange，提问作者rerenlx