Skip to content

Make public headers self-contained and stop relying on PCH - #40

Open
TrueBrain wants to merge 1 commit into
carbonengine:mainfrom
TrueBrain:include-self-containment
Open

Make public headers self-contained and stop relying on PCH#40
TrueBrain wants to merge 1 commit into
carbonengine:mainfrom
TrueBrain:include-self-containment

Conversation

@TrueBrain

@TrueBrain TrueBrain commented Aug 22, 2026

Copy link
Copy Markdown
Contributor

Summary

Initially I wanted to make an issue first, to talk this over. But code speaks louder than any words, so I ended up making this PR instead. But this PR is much more a "do you want to go in this direction?" question that should have been asked in an issue.
Sorry :(

When compiling this (and many of the other carbon) repositories on Linux, you run into the issue that a bunch of include headers are missing. And this totally make sense, as these repositories use PCH with <windows.h>. Which means on Windows, a ton of system headers are added without people realizing (as windows.h is a terrible header in this regard).

Building on MacOS will tell about most: but not all. And this is because GCC has a different opinion about system headers than others do: it minimizes them as much as it can. Famously, since GCC 13 they removed the inclusion of cstdint by their headers. To take this as example, it means:

  • On Windows, <windows.h> will transitively include this header.
  • On MacOS, the fact you use libc++ will transitively include this header (for now at least).
  • On Linux/GCC: it will not.

So we run into compiler-errors on Linux. Fixing this can be done in several ways, but it also highlights a bigger problem: something that works on one platform, fails on another. And those can be annoying to deal with after-the-fact.

While delving into this further, I noticed a bit of a more tricky problem to deal with:

No file in the "include" folder includes StdAfx.h, but some do depend on its context via PCH. This means there is a knock-on effect through all repositories that depend on core: they all need a PCH to at least cover the include files in the PCH of core. And that can be unexpected.

So this PR sets out to fix these issues:

  • Make public headers self-contained (and validate that with a self-test)
  • Make this repository build without PCH

Additionally, I let Claude write some code for the CI, so it covers that non-PCH keeps on building. Just to prevent regression on this front.

After this PR you end up with public-headers that don't implicitly need a PCH to contain some includes. In other words: this fixes that silently the StdAfx.h leaked into the public headers, although StdAfx.h itself wasn't made public. This also means that after this PR PCH becomes a compile-performance optimization again, and not a dependency of its own.

That all said and done, the actual requirement to build on Linux is a much smaller change: https://github.com/carbonengine/core/compare/main...TrueBrain:carbonengine-core:push-xkzzrvtkskxx?expand=1. I am also fine if that is the route to take.

PS: of course if this PR is accepted, I can do the same work on other repositories that have the same issue. About 50% of them currently fail on missing headers, in different degrees.
PPS: the no-PCH build most likely fails on MacOS till #41 lands.

AI assistance disclosure

Claude wrote the code; I instructed what I wanted to achieve. Verified it is matching up with my expectations.

Type of change

  • Bug fix
  • New feature
  • Refactor / cleanup (no behaviour change)
  • Documentation
  • Build, CI, or tooling
  • Breaking change (public API or ABI)
  • Other (describe below)

Linked issue (optional)

What changed

  • Ensure public headers are including all files they depend on
  • Ensure Linux doesn't fail on missing headers (it will still fail on other issues; but that is for other PRs)
  • Ensure CI prevents regression

Testing

  • Build with PCH on Linux and Windows
  • Build without PCH on Linux and Windows

Platforms tested

  • Windows
  • macOS
  • Linux

Screenshots / captures

Checklist

  • I've read CONTRIBUTING.md.
  • My commits follow the commit-message style described there.
  • I've added or updated tests where it made sense.
  • I've updated docs / inline API comments for any behaviour change.
  • My CLA / ICLA is signed (the bot will let you know if it isn't).

Full disclosure: I am employed by Fenris Creations, although I have no involvement with the Carbon project. I work on this in my free time under my own name.

Every public header now compiles on its own, and every source states its
own dependencies rather than inheriting them (implicit) from StdAfx.h.

Additionally, extend the CI to check if compiling without PCH still works.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@TrueBrain
TrueBrain force-pushed the include-self-containment branch from 2415707 to 16df0e4 Compare August 22, 2026 09:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant