Reconcile provided Bazel targets with our installation instructions

[hoffbrinkle]

Our current installation guide for Bazel indicates that the @au//au target provides a significant number of headers:

Dependency	Headers provided	Notes
@au//au	"au/au.hh" "au/fwd.hh" "au/units/*.hh" "au/units/*_fwd.hh" "au/constants/*.hh"

However, our BUILD.bazel file doesn't really reflect this:

cc_library(
    name = "au",
    hdrs = ["au.hh"],
    visibility = ["//visibility:public"],
    deps = [
        ":chrono_interop",
        ":constant",
        ":constants",
        ":math",
        ":units",
    ],
)

The only header we provide from the au target is au.hh. The rest of the headers are transitively provided. We should reconcile this and provide "everything" (e.g. googletest) or provide headers via more granular targets (e.g. abseil-cpp).

[chiphogg]

Hmm. I definitely like having a single target for external users for ~99% of use cases. But I wouldn't want to put more than "au.hh" in hdrs, and I definitely wouldn't want to repeat a header file in multiple targets.

Is there a way in bazel to say "this target intentionally transitively provides the following headers also"? That seems like it would express what I am trying to say here.

[hoffbrinkle]

I don't have any great answers (otherwise this likely would've been a PR vs. an issue)...

I think we're just in an odd middle ground where we provide individual unit headers so that they can be included individual and not pay the cost for the ones that aren't needed. But we don't have individual targets so that the dependencies can be similarly explicit.

The downside of individual cc_library targets (say for each unit) is that then the user has to keep their deps up to date with what they #include. Which, I think, is the generally accepted practice for using Bazel. There are tools that can parse your source and keep your BUILD files up to date (e.g. Gazelle), and there's at least one C++ plugin available for that.

Some combination of things are rolling around in my head:

• We could still provide a top level target that provides multiple things with the caveat (note to the user) that things are provided transitively through that target.
• We provide an all_hh type target that just puts everything in one target or even one .hh file.
• We have a release process that generates a specific BUILD.bazel file that has the types of targets we expect users be able to use. I believe when we do a BCR release we could even specify that BUILD.bazel file as the one that gets presented when Au gets imported.