Sometimes users don't want to follow the DWYU rules for all targets or have to work with external dependencies not following the DWYU principles. While one can completely exclude targets from the DWYU analysis (e.g. via tags), one might not want to disable DWYU completely, but define custom rules for specific dependencies. One can do so by defining exceptions where includes can be provided by selected transitive dependencies instead of direct dependencies. In other words, one can virtually change which header files are treated as being available from direct dependencies.
One example use case for this are unit tests based on gtest. Following strictly the DWYU principles each test using a gtest header should depend both on the gtest library and the gtest main:
cc_test(
name = "my_test",
srcs = ["my_test.cc"],
deps = [
"@com_google_googletest//:gtest",
"@com_google_googletest//:gtest_main",
],
)This can be considered superfluous noise without a significant benefit.
The mapping feature described here allows defining that @com_google_googletest//:gtest_main offers the header files from @com_google_googletest//:gtest.
Then a test can specify only the dependency to @com_google_googletest//:gtest_main without DWYU raising an error while analyzing the test.
load("@depend_on_what_you_use//dwyu/cc/cc_info_mapping:cc_info_mapping.bzl", "dwyu_make_cc_info_mapping")
dwyu_make_cc_info_mapping(name, mapping)
Map include paths available from one or several targets to another target.
Create a mapping allowing treating targets as if they themselves would offer header files, which in fact are coming from their dependencies. This enables the DWYU analysis to skip over some usage of headers provided by transitive dependencies without raising an error.
Using this rule and the various mapping techniques is demonstrated in the target_mapping example.
PARAMETERS