Menu
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.
Guidelines and SOP for synchronizing public C++ API changes (methods, enums, options structs) to Java (Android JNI) and JavaScript/TypeScript (Web/WASM Embind).
Standard verification pipeline to execute after modifying C++ source or header files. Use this skill to format includes, build the engine, and run core tests.
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.
| 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/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.