header-cycle-breaker

# Header Cycle Breaker Skill This skill outlines the systematic approach to breaking cyclic dependencies in V8 headers, specifically focusing on moving heavy inline includes to more localized `.cc` files or non-inline headers, and resolving the resulting cascade of "undefined inline function" errors (IWYU - Include What You Use style). ## When to Use Use this skill when: - You are tasked with breaking a header cycle in V8 (e.g., core-to-wasm cycle). - You need to remove an `-inl.h` include from another `-inl.h` or `.h` file. - You encounter a flood of `[-Werror,-Wundefined-inline]` errors after modifying a heavy header. ## Workflow ### Phase 1: Identification and Cycle Breaking 1. **Identify the cycle**: Use tools or subagents to map the include graph and find the cyclic path. 2. **Plan the break**: Identify a point where an `-inl.h` can be replaced with its non-inline counterpart (`.h`) or where an include can be moved entirely to implementation files. 3. **Apply the break**: Modify the header file to break the cycle. ### Phase 2: Resolving the Cascade (IWYU) Breaking a heavy include chain will cause many implementation files (`.cc`) and even generated files to fail because they were relying on transitive includes for inline definitions. 1. **Do not panic**: Expect tens or hundreds of compilation errors initially. 2. **Aggressive Delegation**: Spawn subagents for independent file failures. Prompt them to identify missing headers for specific undefined symbols. 3. **IWYU Application**: For each failing file: - Identify which inline method is undefined. - Find which `-inl.h` file defines it. - Include that `-inl.h` file directly in the failing `.cc` file, preferably within appropriate guards (e.g., `#if V8_ENABLE_WEBASSEMBLY`). 4. **Repeat until clean**: Build, fix, and build again. This is an iterative process. ### Phase 3: Special Case - Generated Files If a generated file (e.g., `objects-printer.cc`) fails with undefined inline methods: 1. **Trace to generator**: Realize that editing the generated file is temporary. Find the source generator (e.g., in `src/torque/`). 2. **Modify the generator**: Update the generator code to emit the necessary `#include` statements in the files it generates. 3. **Rebuild the generator**: Recompile the tool (e.g., Torque) and let the build system regenerate the files. ## Best Practices - **Keep files isolated**: Do not revert the cycle-breaking change when you see cascade errors. Push through by fixing the files. - **Use guards**: Always wrap Wasm-specific includes in `#if V8_ENABLE_WEBASSEMBLY`. - **Check trait caching**: Be aware of C++ trait caching issues if you encounter weird subtyping errors during header reorganization.