Enforce the strict topological header inclusion layering and reordering rules in Filament. Use this skill when adding or modifying `#include` directives in C++ source or header files.
| name | cpp-header-inclusion |
| description | Enforce the strict topological header inclusion layering and reordering rules in Filament. Use this skill when adding or modifying `#include` directives in C++ source or header files. |
Filament enforces a strict, acyclic include layering hierarchy to optimize compile times, prevent header pollution, and identify missing dependencies.
Includes must be grouped and separated by exactly one blank line in the following order (top to bottom):
#include "details/Foo.h" (isolated at the very top).#include <utils/unwindows.h> (always second, only if needed).#include "PrivateStuff.h" (using double quotes " " strictly for private local headers located under the local target's src/ folder).<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.<tsl/...>, <absl/...>, <jni.h>.<algorithm>, <vector>, <cstddef> (including standard <c...> wrappers).<unistd.h>, <sys/stat.h> (C system headers below C++ std, but above C std)..h (e.g., <stdint.h>, <stddef.h>)."Allocators.h") are sorted above nested subdirectory includes (e.g., "components/Foo.h").AI agents must never manually sort includes or guess target dependencies. Always run the repository's dynamic topological include formatter after modifying C++ files:
./tools/reorganize_headers.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.
Enforce C++ static thread safety annotations and correct synchronization primitives. Use this skill when designing multi-threaded classes or editing guarded member fields.
Build, deploy, run, and benchmark Filament binaries on connected Android devices or emulators. Use this skill for compiling, pushing, and executing Android tests or benchmarks.
Clean and build Filament targets for development, debugging, and production. Use this skill whenever you need to clean the workspace or compile desktop targets.
Execute unit tests and performance benchmarks for Filament on desktop platforms. Use this skill to run and filter tests or benchmarks locally.
Enforce strict header self-containment so that every header file compiles independently. Use this skill when creating or modifying C++ header files.
Enforce preprocessor guard rules and macro-dependent inclusion hygiene in C++. Use this skill when modifying conditional imports or preprocessor directives.