In a C++ robotics codebase, editing one header triggers a 30-minute rebuild; how do you find why and cut that dependency?
answer
- who includes it, transitively
- dependency files and the include tree
- include what you use
- pimpl as a compile firewall
- destructor defined where Impl is complete
basics
~20 sFind every translation unit that reaches the header, directly or transitively, and why. Then cut edges: remove unused includes, forward-declare instead of including, move bodies and private members into .cpp files, split catch-all headers, and use pimpl for classes whose private parts churn.
solid answer
~50 sThe build tool recompiles every `.cpp` whose recorded dependencies include the edited header, so start by measuring the **fan-in**: which translation units reach it, through which chain of includes. The compiler's include tree (`-H` with GCC or clang) and the build tool's explanation of what it rebuilt show the chain. Then cut edges. Remove includes nothing uses, which the include-what-you-use tool automates. Replace includes of types a header only points at with forward declarations. Move inline bodies and private helpers into `.cpp` files. Split a catch-all `robot_types.h` into small headers. For a class whose private members change often, use **pimpl**: the class holds a `std::unique_ptr<Impl>`, `Impl` is defined in the `.cpp`, and private changes recompile one file. Declare the destructor in the header and define it in the `.cpp`, or every includer fails on an incomplete `Impl`.
code
cpp · 28 lines#include <cstdio>
#include <memory>
// ---- planner.h: what every includer sees ----
class Planner {
public:
Planner();
~Planner(); // declared here, defined after Impl
Planner(Planner&&) noexcept;
Planner& operator=(Planner&&) noexcept;
int plan(int goal) const;
private:
struct Impl; // private details live in the .cpp
std::unique_ptr<Impl> impl_;
};
// ---- planner.cpp: the only file that changes when Impl changes ----
struct Planner::Impl { int cost_per_step = 3; };
Planner::Planner() : impl_(std::make_unique<Impl>()) {}
Planner::~Planner() = default; // Impl is complete here
Planner::Planner(Planner&&) noexcept = default;
Planner& Planner::operator=(Planner&&) noexcept = default;
int Planner::plan(int goal) const { return goal * impl_->cost_per_step; }
int main() {
Planner p;
std::printf("%d\n", p.plan(4));
}go deeper
Know that changing a header recompiles every .cpp file that includes it, even indirectly, and that headers should include only what they need.
Explain forward declarations and pimpl as ways to stop private details from leaking into includers, including why the destructor must be defined where Impl is complete.
Show the diagnosis: measure the fan-in from build-tool output and include trees, rank headers by fan-in times churn, then cut edges with forward declarations, splits and pimpl where it pays.
Treat include hygiene as an ongoing practice with a checker in CI and a budget for heavy headers, weighing pimpl's run-time cost against developer time lost to rebuilds.
## Why one header costs thirty minutes An incremental build recompiles a translation unit when any file it depends on is newer than its object file. The compiler records those dependencies, every header the `.cpp` file reached directly or **transitively**, in dependency files that the build tool reads. So the cost of editing `motion_types.h` equals the number of translation units that reach it, times their compile time. In a robotics codebase where `motion_types.h` is included by `robot.h`, and `robot.h` by nearly every node, controller and test, one edit recompiles almost everything. The fix is never to make the compiler faster; it is to make fewer files depend on the header. ## Measure the fan-in first 1. **Ask the build tool why.** Ninja's `-d explain` prints, for each rebuilt object, that it is older than the edited header. That gives you the list of victims. 2. **Read the include chain.** GCC and clang both accept `-H`, which prints every header a translation unit opens, indented by nesting depth, so you see *through which* header the edited one arrived. 3. **Find the heavy headers.** Clang's `-ftime-trace` writes a JSON time profile for each translation unit, with a separate entry for each source file it parsed, so expensive headers stand out. 4. **Rank by damage.** A header with a high fan-in that also changes often is the one to fix first; a stable header with high fan-in mostly costs clean builds instead. ## Cut the edges - **Include what you use.** Remove includes nothing in the file needs, and include directly what it does need instead of relying on a transitive include. The include-what-you-use tool proposes these edits automatically. - **Forward-declare instead of including** wherever a header only uses pointers or references to a type, or declares functions that mention it. - **Move bodies out of headers.** An inline member function that calls into another subsystem forces that subsystem's header into every includer. Move the body into the `.cpp` file and the include goes with it. - **Split catch-all headers.** A `robot_types.h` holding forty unrelated structs makes every user depend on all forty. Small, focused headers keep the fan-in of each one honest. - **Keep templates and constexpr code lean.** They must stay visible in headers, so keep their dependencies minimal, or use explicit instantiation, which belongs with templates. ## Pimpl as a compile firewall When a class's **private** section is what keeps changing, every includer recompiles even though it cannot see those members. **Pimpl**, the pointer-to-implementation idiom, moves them out of sight: ```cpp // planner.h #include <memory> class Planner { public: Planner(); ~Planner(); // declared, not defined here Planner(Planner&&) noexcept; Planner& operator=(Planner&&) noexcept; int plan(int goal) const; private: struct Impl; // incomplete in every includer std::unique_ptr<Impl> impl_; }; ``` `planner.cpp` defines `struct Planner::Impl` with the real members and then `Planner::~Planner() = default;`. Now adding a member to `Impl`, or changing its types, recompiles `planner.cpp` alone. The destructor rule is the part interviewers probe. `std::unique_ptr` allows an incomplete `T`, but its default deleter **requires `T` to be complete** where it deletes. Without a declared destructor the compiler defines one implicitly, inline, in every file that destroys a `Planner`, where `Impl` is incomplete. With libc++ the error reads `invalid application of 'sizeof' to an incomplete type 'Planner::Impl'`, from a `static_assert` whose message is `cannot delete an incomplete type`. Declaring the destructor moves its definition into `planner.cpp`. Because a user-declared destructor suppresses the implicit move operations, declare and default those in the `.cpp` too. ## What pimpl costs | Gain | Cost | |---|---| | private changes recompile one file | a heap allocation per object | | includers no longer see the private members' headers | an extra pointer indirection on every call | | the class's layout stops depending on its internals | more boilerplate: destructor and moves out of line | Use it for classes with a high fan-in and churning internals, not for small value types in hot loops. Measure again after each change: the fan-in of the edited header, and the wall-clock time of the rebuild it triggers, are the numbers that tell you the edge is really gone. The same idiom also stabilises a library's binary interface, but that is a separate reason with its own rules.
- Why does a pimpl class with no declared destructor fail to compile in its users' files?Without a user-declared destructor, the compiler defines one implicitly wherever a `Planner` is destroyed, and it destroys the `std::unique_ptr<Impl>` member there. The default deleter requires `Impl` to be complete, but in the users' files it is only forward-declared. Declaring `~Planner();` in the header and defining it as `= default` in the `.cpp` file, after `Impl`, moves that instantiation to where `Impl` is complete.
- When is pimpl the wrong tool for a slow build?When the class is a small value type used in hot loops, the per-object heap allocation and extra indirection cost more than the rebuilds save. It also does nothing when the header that churns is a widely included type definition or a template; there the cure is splitting the header, forward declarations and fewer transitive includes.
- How do you tell which include chain dragged a header into a file?Compile that one translation unit with `-H` (GCC and clang both support it): it prints every header opened, indented by depth, so the parent of the edited header is visible. The build tool's own explanation, such as Ninja's `-d explain`, tells you which objects were rebuilt because of it.
- A faster machine or more cores is the real fix for header rebuilds.
- Include guards stop a header change from recompiling its includers.
- With pimpl the destructor can stay implicit in the header.
- Pimpl is free: it has no run-time cost.
- A header only matters if a file includes it directly.