Skip to content

SYSTEM Cited by 1 source

Include What You Use (IWYU)

What it is

Include What You Use (IWYU) is an open-source Clang-based static-analysis tool originally from Google that minimizes unnecessary #include directives in C++ code. IWYU's signature policy: each file should #include exactly the headers that export the symbols it directly uses — no more, no less. It follows the Clang AST to map each symbol reference to its defining header and produces a suggested diff of include changes per file.

Why it's referenced here

IWYU is the prior art that Figma's DIWYDU was designed against. Figma attempted to adopt IWYU twice on their existing C++ codebase; both attempts had "limited success" before the team concluded its strictness was the blocker, built DIWYDU with a weaker invariant, and succeeded.

The strictness trade-off

IWYU's "exact minimal set" rule is provably correct — if a file uses std::vector, it must include <vector> directly rather than rely on some other header having pulled it in transitively. This is great for a greenfield codebase where every file starts with only the includes IWYU suggests.

For retrofitting a large existing codebase the strictness reverses:

[IWYU] strives for each file to have the precise set of includes, which makes it challenging to apply retroactively to a substantial codebase. (Source: sources/2024-04-27-figma-speeding-up-c-build-times)

The failure mode Figma hit: every file needs a non-trivial diff on the first IWYU run (add missing direct includes, remove unnecessary ones), and each diff is a debate about which header is the "real" home of a symbol — often non-obvious under the STL's private-include structure, or when multiple headers export the same symbol. These per-file debates stopped the rollout.

DIWYDU's relaxation — "each #include must be directly used, but you may rely on transitive includes for symbols whose specific home-header isn't included" — eliminates the debate. Any include that's currently doing work stays; only the dead-weight ones are flagged. Much smaller diff per file. Enabled codebase-wide rollout.

IWYU also struggles with private includes

Both IWYU and DIWYDU skip analyzing standard-library headers because STL public headers frequently re-export symbols defined in private includes (e.g., vector.h doesn't literally define std::vector — that's in an internal header). Figma's article notes this explicitly as a shared limitation. Figma mitigates by gating stdlib usage to one wrapper directory.

Seen in

Last updated · 200 distilled / 1,178 read