Would a C counterpart to -stdlib++-isystem be an acceptable addition to Clang? It would let us supply explicit libc header roots while the driver preserves its target-specific ordering relative to C++ and builtin headers.
Motivation
I maintain hermetic-llvm, a hermetic LLVM-based Bazel toolchain for cross-compilation. Its compiler, libc, Linux UAPI, and C++ library headers are separate build inputs, rather than a preassembled target sysroot. It is also the @llvm toolchain selected by LLVM’s own Bazel overlay’s hermetic-toolchain configuration.
We prefer supplying those headers explicitely to clang over a sysroot construction because creating a sysroot requires duplicating and aligning with driver expectations per target, and requires creating directory artifacts which are opaque to bazel and against bazel total expliciteness goal.
After long investigation, my understanding is that there doesn’t seem to be a way of achieving this today with full explicit driver include flags in a non tedious and brittle way. Like without using internal -Xclang flags and without duplicating ordering decision that belong in the driver.
This especially true given that the right include search diverge per target and environment, like for musl vs gnu for instance:
x86_64-linux-gnu= C++ library → Clang builtins → C libraryx86_64-linux-musl= C++ library → C library → Clang builtins
This discussion is about providing C library headers only. Examples below assume that Clang builtin headers are provided by -resource-dir.
-stdlib++-isystem already expresses the C++ part of this requirement, and -resource-dir expresses the builtin-header part
We lack an equivalent for C library headers.
The current workaround
For GNU/Linux, we disable default standard-library header discovery and supply the libc and Linux UAPI header directories using private frontend options:
-nostdlibinc \
-stdlib++-isystem <some_path>/libcxx/include/c++/v1 \
-Xclang -internal-externc-isystem -Xclang <some_path>/libc/include \
-Xclang -internal-externc-isystem -Xclang <some_path>/linux-uapi/include
This places the C headers after Clang’s builtin headers, as the GNU/Linux driver normally does.
For musl, the Linux driver currently places C headers before builtin headers. Forwarding only the C paths through -Xpreprocessor also puts them before the C++ paths supplied by -stdlib++-isystem, which is incorrect.
To preserve the driver’s builtin-header handling, our current workaround therefore forwards both C++ and C header paths through private -Xpreprocessor arguments, with C++ first. This also means those C++ paths bypass -nostdinc++.
Another workaround is to disable builtin-header discovery and insert those headers ourselves. Either approach requires us to reproduce part of Clang’s include policy. I would much rather tell Clang where each set of headers lives and let the driver handle their ordering.
Proposed direction
A repeatable driver option, provisionally -cstdlib-isystem, would replace implicit C library header discovery with explicit roots, preserving their supplied order and the target’s existing builtin ordering and C-header classification. For example:
clang++ --target=x86_64-linux-musl \
-stdlib++-isystem <some_path>/libcxx/include/c++/v1 \
-cstdlib-isystem <some_path>/libc/include \
-cstdlib-isystem /linux-uapi/include \
-c example.cc
The same header arguments would work for GNU/Linux: the driver would choose the different builtin position. This would allow hermetic C header inputs without encoding that distinction in the build system. Library linking remains a separate concern.
This proposal would follow the driver’s policy, allowing that policy to evolve without corresponding changes in the build system.
Prototype checks
I have a prototype for GNU/Linux, musl Linux, and Darwin. Tests confirm that Clang uses the supplied C header directories instead of its defaults, while preserving their order relative to C++ and builtin headers. They also check #include_next and the flags that disable header searches.
That prototype follows -stdlib++-isystem’s explicit-root behavior by preserving supplied C roots under -nostdinc. It proposes -nostdlibinc as the cancellation switch; -nostdinc++ leaves C roots active. This is an intentional C adaptation: the C++ override survives -nostdlibinc, and that switch also suppresses default C++ discovery.
Feedback requested
- Would a flag for replacing Clang’s default C library header directories be useful and acceptable? Is there an existing direction I missed?
- Are the proposed ordering and interactions with -nostdinc, -nostdlibinc, and -nostdinc++ appropriate?
- This likely has implication to various Toolchains (as per driver language) and targets. Should this apply to all targets from the get go ?
- What would be the acceptable next steps ? I was thinking of doing a complete due dilligence of all per Toolchains change in driver behavior to account for all candidates for which to test non regression.
@MaskRay I’m cc’ing you given your recent involvment in the the CC toolchains ruleset of bazel.