Chrome for iOS: Forward Declarations & Self-Healing Optimization Guide

This guide documents the Automated Forward Declarations Optimization & Compiler Self-Healing workflow for Chrome for iOS. It is designed to guide future engineering agents and human developers in optimizing C++ and Objective-C++ headers, decoupling interface dependencies, and resolving compilation issues automatically.

📖 Overview

C++ #include and Objective-C #import statements in header files (.h) create tight compile-time coupling. When a header file is modified, all files transitively including it must be recompiled.

By replacing full header imports with lightweight C++ forward declarations (class / struct) and Objective-C forward declarations (@class / @protocol), we:

1. Decouple Interface Dependencies — Reducing downstream build breaks.
2. Speed up Compilation — Siso/Ninja spend less time parsing redundant AST nodes.
3. Maintain Clean Scope — Move implementation imports directly to .mm and .cc files where they belong.

🛠️ The Tool Suite

Located in ios/tools/forward_declarations/, the optimization toolchain consists of:

1. check_forward_declarations.py:
   • Recursively scans directories or Git modified files (--git option) to identify header files with optimization opportunities.
   • Flags redundant imports and recommends exact forward declaration signatures.
2. fix_forward_declarations.py:
   • Automatically patches headers by removing redundant #import lines and inserting appropriate forward declaration blocks. Supports individual files, full recursive directory walking, or Git modified files (--git option).
   • Shifts the original imports into corresponding implementation (.mm/.cc) and test (_unittest.mm) files to satisfy compiler usage.
3. forward_declarations_lib.py:
   • The core lexical parsing library that handles code style formatting. Loads highly common base/system header definitions from a customizable core_header_mapping.json configuration file.
   • Includes Style Healers to merge adjacent duplicate namespaces, clean up spacing, and convert includes to imports.
4. self_heal_branch.py:
   • A compiler-driven automated healing loop.
   • Runs customizable compilation targets (defaults to chrome, ios_chrome_unittests) recursively, parses Clang compiler diagnostics, resolves incomplete type errors via intelligent symbol caching, and automatically allowlists GN/DEPS include boundary violations.

🚀 The Optimization Workflow (Step-by-Step)

Follow this systematic workflow to optimize any folder under //ios/chrome/:

Step 1: Branch Setup

Always isolate your optimization work inside a clean Git branch.

git checkout -b fwd-decl-<feature-name>-pilot

Step 2: Scan and Analyze Opportunities

Run the scanner on your target subdirectory (e.g., ios/chrome/browser/enterprise) or on files modified in your git branch to see recommended optimizations:

# Scan a specific directory
python3 ios/tools/forward_declarations/check_forward_declarations.py ios/chrome/browser/enterprise

# Or scan files modified in your branch compared to origin/main automatically
python3 ios/tools/forward_declarations/check_forward_declarations.py --git

Step 3: Apply Automatic Header Replacements

Apply the scan recommendations to auto-replace header imports with forward declarations and move imports into implementation files:

# Fix a specific directory
python3 ios/tools/forward_declarations/fix_forward_declarations.py ios/chrome/browser/enterprise

# Or fix files modified in your branch compared to origin/main automatically
python3 ios/tools/forward_declarations/fix_forward_declarations.py --git

This will stage initial changes across your header and source files.

Step 4: Commit the Initial Layout

Create an initial commit containing the basic layout transformations:

git add -A
git commit -m "[ios] Optimize forward-declarations in <feature> (pilot)"

Step 5: Run the Automated Self-Healing Loop

Because header decoupling can lead to missing transitive includes inside downstream files, launch the Self-Healing compiler loop to automatically diagnose and patch compilation failures:

python3 ios/tools/forward_declarations/self_heal_branch.py fwd-decl-<feature-name>-pilot out/Debug-iphonesimulator --targets chrome ios_chrome_unittests

• What it does:
  1. Runs buildtools/checkdeps/checkdeps.py to identify illegal includes, automatically allowlisting them inside local DEPS files.
  2. Runs gn check to detect missing target dependencies.
  3. Compiles specified Ninja build targets.
  4. If Clang throws incomplete type failures, it resolves the correct header defining the type via core_header_mapping.json or efficient repository scanning, inserts the import into the implementation file, and auto-commits the healing step onto the branch!
  5. Repeats until a 100% spotless compilation is achieved.

Step 6: Run Formatting & Verification

Format the code and run unit tests to ensure everything is 100% pristine:

# Apply clang-format to all touched lines
git cl format
git add -u
git commit --amend --no-edit

# Run affected unit tests
python3 ios/tools/run_cl_tests.py

Step 7: Upload the CL

Finally, upload the optimized CL to Gerrit for review:

GIT_EDITOR=true git cl upload

💡 Critical Lessons & Edge Cases (For Future Agents)

When modifying the script logic or performing manual interventions, pay attention to these core rules:

1. Template Incomplete Types: C++ template constructors (such as std::unique_ptr<Type> or absl::variant<Type>) require the full C++ type definition rather than just a forward declaration. If Clang throws an incomplete type failure inside a constructor/destructor, import the header inside the .mm file rather than trying to forward declare it in the .h.
2. DEPS Allowlist Boundaries: Under Chromium's architecture, directories restrict imports to enforce clean layers. If you move an import to an implementation file and checkdeps raises an Illegal include error, add the correct import pattern (+path/to/header.h) to the directory's local DEPS file.
3. Alphabetical Spacing & Sorting: Keep all #import and DEPS lines sorted alphabetically. Our style healer heal_spacing dynamically maintains this formatting.
4. Adjacent Namespace Merging: When forward declarations are generated, they are placed inside a namespace block matching their type (e.g., namespace enterprise_idle { class IdleService; }). Ensure adjacent duplicate namespaces are merged into a single block for maximum readability.