Why bazel add -iquote for all cpp deps

[fausturs]

I'm using bazel with bzlmod build my c++ project. I found that bazel add -iquote external/xxx-lib~versionfor all my deps.

From some [discussion](RobotLocomotion/drake#8197), I found that if the lib use hdrs to publish headers, then bazel will add a -iquote to the libs root path.

This seems a bit redundant to me, the other headers in the libs root path should be invisible to the outside world.

I have write an example to explain this

For my lib

.
├── BUILD
├── include
│   └── lib_header.h
├── MODULE.bazel
├── util
│   ├── util.cpp
│   └── util.h
└── WORKSPACE

# BUILD
cc_library(
    name = "my-lib",
    srcs = glob(["util/*"]),
    hdrs = ["include"],
    strip_include_prefix = "include",
    include_prefix = "my-lib",
    visibility = ["//visibility:public"],
)

// util/util.h
#ifndef LIB_UTIL_UTIL_H
#define LIB_UTIL_UTIL_H
#define UTIL_VALUE_STR "util.h in lib"
#endif

For my bin

.
├── BUILD
├── main.cpp
├── MODULE.bazel
├── src
│   └── util
│       └── util.h
└── WORKSPACE

# BUILD
cc_binary(
    name = "my-bin",
    srcs = ["main.cpp", "src/util/util.h"],
    copts = ["-Isrc"],
    linkopts = [
        "-static-libstdc++",
        "-static-libgcc",
    ],
    visibility = ["//visibility:public"],
    deps = [
        "@bazel_remote_test//:my-lib"
    ]
)

// util/util.h
#ifndef LIB_UTIL_UTIL_H
#define LIB_UTIL_UTIL_H
#define UTIL_VALUE_STR "util.h in bin"
#endif

// main.cpp
#include <iostream>
#include "util/util.h"
int main() {
    std::cout << UTIL_VALUE_STR << std::endl;
    return 0;
}

The output of my binary is

util.h in lib

It is not difficult to find the reason from the compilation command given by bazel.

/usr/bin/clang \
	-U_FORTIFY_SOURCE \
	-std=c++17 \
	-MD -MF bazel-out/k8-fastbuild/bin/_objs/my-bin/main.pic.d \
	-frandom-seed=bazel-out/k8-fastbuild/bin/_objs/my-bin/main.pic.o \
	-iquote . \
	-iquote bazel-out/k8-fastbuild/bin \
	-iquote external/bazel_remote_test~20231204.1-test-iquote \
	-iquote bazel-out/k8-fastbuild/bin/external/bazel_remote_test~20231204.1-test-iquote \
	-iquote external/bazel_tools \
	-iquote bazel-out/k8-fastbuild/bin/external/bazel_tools \
	-Ibazel-out/k8-fastbuild/bin/external/bazel_remote_test~20231204.1-test-iquote/_virtual_includes/my-lib \
	-Isrc \
	-c main.cpp \
	-o bazel-out/k8-fastbuild/bin/_objs/my-bin/main.pic.o

-iquote external/bazel_remote_test~20231204.1-test-iquoteis before than -Isrc.

so compiler will find the util/util.h in the external folder.

But from the https://bazel.build/reference/be/c-cpp#hdrs

Headers in srcs must only be directly included from the files in hdrs and srcs of the library itself.

(To be honest, it seems to me that Headers in srcs should only be directly included by files in srcs.)

Of course I could use #include "src/util/util.h" to circumvent this problem in this example.

But when the number of my dependencies increases rapidly, I still need to care about file path conflicts between this repo and other dependencies, which is obviously not elegant enough.

I don’t know if I missed some key documents. Is there any way to solve this problem?

[meteorcloudy]

/cc @oquenchil @buildbreaker2021