Make public headers self-contained and stop relying on PCH

[TrueBrain]

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.

[CCP-Aporia]

Hi,

as you mentioned, this is more of a discussion. 😄 In general, pre-compiled headers are here to stay, and we are not going to move away from them.
That being said, any public headers ought to include everything that is needed for the public header file to be usable, but not more than that (especially no third-party headers). As such, fixes for that are more than welcome. 😄

I wonder if the way CMake does PCH masks any such missing include issues because it force includes the precompiled header via the compiler's command-line (e.g. no more requirement for `#include "stdafx.h" in the .cpp file). However, testing this through a CMake build option is probably not a good way to go about it. Every build option for this kind of balloons the build matrix, which is already quite large and something we want to reduce in the mid to long term.

[TrueBrain]

Yeah, so currently PCH does mask.
And I understand adding more CI targets isnt ideal.

Two alternatives that come to mind:

• use a current build to run without PCH (like "internal" or something)
• use clang-tidy to staticly detect these issues

Edit: thinking some more, I could remove the CI part, then this PR would ensure public headers are self-contained at least. It adds a new cmake target for that which runs the headers without PCH. Would that be a good step?

[CCP-Aporia]

The clang-tidy path is something that would be very much welcomed. 👍 It's currently on the list to integrate it anyway (for example, to add the naming convention check according to our style guide), and that might be a good first step.