cpp-header-inclusion

# Dynamic C++ Header Inclusion & Reordering Filament enforces a strict, acyclic include layering hierarchy to optimize compile times, prevent header pollution, and identify missing dependencies. ## 1. Logical Layer Hierarchy Includes must be grouped and separated by **exactly one blank line** in the following order (top to bottom): 1. **Layer 0 (Corresponding Header):** `#include "details/Foo.h"` (isolated at the very top). 2. **Layer 0.5 (Windows Cleanup):** `#include <utils/unwindows.h>` (always second, only if needed). 3. **Layer 1 (Private/Local Headers):** `#include "PrivateStuff.h"` (using double quotes `" "` strictly for private local headers located under the local target's `src/` folder). 4. **Layer 2 (Internal Proprietary Libraries):** Public and private includes for other internal libraries (e.g. `<filaflat/...>`, `<backend/...>`, `<utils/...>`, `<math/...>`). All proprietary library includes **must** use `< >` syntax (including `private/` sub-folders). The layering priority order of these libraries is dynamically computed based on `CMakeLists.txt` target linkages. 5. **Layer 3 (Third-Party Libraries):** `<tsl/...>`, `<absl/...>`, `<jni.h>`. 6. **Layer 4 (C++ Standard Library):** `<algorithm>`, `<vector>`, `<cstddef>` (including standard `<c...>` wrappers). 7. **Layer 5 (POSIX System Headers):** `<unistd.h>`, `<sys/stat.h>` (C system headers below C++ std, but above C std). 8. **Layer 6 (C Standard Library):** Legacy C system headers ending in `.h` (e.g., `<stdint.h>`, `<stddef.h>`). --- ## 2. Sorting & Spacing Rules for Private Includes (Layer 1) * **Flat-First:** Flat/top-level includes (without a subdirectory prefix, e.g., `"Allocators.h"`) are sorted **above** nested subdirectory includes (e.g., `"components/Foo.h"`). * **Visual Grouping:** Private includes must be grouped by their first subdirectory path prefix, separated by **exactly one blank line**. --- ## 3. Running the Automated Include Formatter AI agents **must never manually sort includes** or guess target dependencies. Always run the repository's dynamic topological include formatter after modifying C++ files: ```bash ./tools/reorganize-headers/run.py <file_or_directory> ``` *Note: The tool dynamically parses `CMakeLists.txt` files to topologically sort proprietary libraries and includes preprocessor safety checks to avoid breaking platform-conditional include guards.*