The Invisible Type: Three Escapes of size_t from Linux CI
· 4 min read
Unlike int or float, in C++ the size_t type is not a built-in language keyword. It is a regular typedef that lives in system header files (for example, <cstddef>). However, in real projects, developers often use size_t “naked,” without an explicit #include, relying on transitive inclusion from other files.

The old Doxygen parser we were stuck on before didn’t care about this—it worked like a regular expression and simply read text. But when we switched to a true AST parser (via libclang), the compiler demanded strictness. And so began one of the most ridiculous quests in the history of our CI.
Escape One: Silent Annihilation
We wrote tests for the new parser, ran them locally on Windows—everything was green. Over 1200 tests passed successfully, the operator size_t() method parsed perfectly. We pushed the code to GitHub Actions.
The build on the Linux runner failed.
It turned out that on Windows, the libclang library uses the auto-discovery “magic” of the built-in MSVC toolchain—it implicitly pulls in environment definitions, so size_t always exists there, even in a completely empty file.
But on Linux, libclang is brutally honest: didn’t find an #include — means the type doesn’t exist. Encountering the unknown size_t type, the parser panicked, went into error-recovery mode, and simply silently deleted the entire method from the final Abstract Syntax Tree (AST). A whole chunk of the API literally dissolved into thin air.
Escape Two: The Empty Container Trap


The solution seemed obvious: we needed to force the parser to include the header file! We added the -include stddef.h compiler flag to all the files we parse.
Local tests passed. The documentation generation job in CI also went green. But the baseline CI job with unit tests blew up with a fatal error: 'stddef.h' file not found.
The answer lay in the infrastructure. The unit tests ran in a lightweight, minimalist Docker image. It had Python, it had the old Doxygen, but it did not have the GCC compiler and the build-essential package. The stddef.h file physically did not exist on the disk.
Our “fix” broke the parsing of absolutely all files in the project, even those where the size_t type had never existed.
Escape Three: A Stab in the Back from Mypy
We needed a solution that completely bypasses the need for an installed compiler in the operating system. And we found an elegant hack.
We forced Python to dynamically create a fake header file in the temporary directory (/tmp) with the following code:
typedef __SIZE_TYPE__ size_t;
The secret is that __SIZE_TYPE__ is an internal built-in macro of Clang/GCC that always exists in the compiler’s memory, regardless of headers. We fed this temporary file to libclang via the same -include flag.
We push the commit to CI. And it… fails again!
This time, it wasn’t C++ that broke, but the Python static analyzer—mypy. The developer’s local machine had a fresh Python version that inferred types correctly. But the CI had a slightly stricter version that tripped over a triviality: we declared a variable for the temporary file path as None, and then tried to put a string into it. The analyzer threw an Incompatible types in assignment error.
Caught
We had to make a third commit: appease mypy by explicitly writing the annotation Optional[str] = None in the Python code.
And only then, on the third try, did the pipeline finally turn green.
We spent an entire day teaching a C++ AST parser to understand the most basic data type on an operating system that doesn’t have a compiler. Developing cross-platform toolchains is when Windows hides your own bugs from you, Linux slaps your hands for system dependencies, and a strict linter from a completely different language finishes you off.
However, the conflicts with C++ didn’t end there. When a real compiler encounters legacy Doxygen virtual grouping tags (like @addtogroup), a war breaks out between real C++ namespaces and the virtual documentation structure. How we reconciled these two worlds in the AST—read about it in the next episode.