bazelbuild / bazelbuild/rules_cc

Question about Clang Header Module support

Open
#784 6 comments 0 reactions 0 assignees View on GitHub
Dominant language
Starlark
Stars
247
Forks
196
PR merge metrics
No merged PRs in 30d

Description

### 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:

```python
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:

```python
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:

```python
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:

```python
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](https://clang.llvm.org/docs/StandardCPlusPlusModules.html#using-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?

Contributor guide

Open the contributing guide

Research direction

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.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
build-system, compilers
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.