Question about Clang Header Module support

Start by reading cc/private/compile/cc_compilation_helper.bzl and cc/private/compile/compile.bzl, then compare feature declarations in cc/private/toolchain/unix_cc_toolchain_config.bzl, windows_cc_toolchain_config.bzl, unix_cc_configure.bzl, and windows_cc_configure.bzl. Check the test toolchain configurations for existing coverage; done means establishing whether public auto-configured toolchains support the requested .pcm and module_files flow, and documenting the evidence.

Description

While investigating C++ module map generation, I found that rules_cc has code paths for real Clang header-module compilation, but they appear to be gated behind toolchain features that are not defined by the production auto-configured Clang toolchains.

In cc/private/compile/cc_compilation_helper.bzl, generated module maps switch between compiled headers and textual headers based on:

compiled = _enabled(feature_configuration, "header_modules") or \
           _enabled(feature_configuration, "compile_all_modules")

This controls whether headers in the generated .cppmap are emitted as compiled header entries or as textual header entries.

In cc/private/compile/compile.bzl, actual header-module action creation is gated by:

def _should_provide_header_modules(feature_configuration, private_headers, public_headers):
    return (
        feature_configuration.is_enabled("header_modules") and
        (private_headers or public_headers)
    )

and later:

if _should_provide_header_modules(feature_configuration, private_headers, public_headers):
    modules = _create_module_action(...)

There is also logic that treats use_header_modules specially when constructing compile variables / dependency discovery. For example, %{module_files} is only initialized when use_header_modules is enabled.

However, searching the production toolchain configs, I could not find header_modules or use_header_modules declared as feature(...) in the public auto-configured toolchain path, including:

• cc/private/toolchain/unix_cc_toolchain_config.bzl
• cc/private/toolchain/windows_cc_toolchain_config.bzl
• toolchains generated through unix_cc_configure.bzl / windows_cc_configure.bzl

The only definitions I found are in test toolchain configs.

By contrast, module_maps is defined and enabled by default for Unix toolchains, and layering_check implies use_module_maps. This seems to support module maps for declared-use / layering checks, but not real header-module .pcm compilation.

For Clang, unix_cc_configure.bzl may also add:

extra_flags_per_feature["use_module_maps"] = ["-Xclang", "-fno-cxx-modules"]

which further suggests that module maps in this path are intended for static checking rather than implicit Clang C++ module compilation.

Background

I'm continuing to work on Bazel support for C++20 Modules, specifically around Using a Clang module map to avoid mixing include and import problems, which relies on Clang module maps.

This is related to https://github.com/bazelbuild/rules_cc/pull/777.

Question

For a plain open-source Bazel + rules_cc setup using an auto-configured Clang toolchain, is there any supported way to enable real C++ header-module compilation for ordinary cc_library targets, such that:

1. cc_library headers are compiled into real Clang header modules (.pcm), and
2. dependents consume those .pcm files via module_files / -fmodule-file=...-style flags instead of textually including headers?

Or is header_modules effectively an internal/test-only or legacy hook that is not currently supported by the public auto-configured C++ toolchains?