skip to content

In a C++ robotics codebase, editing one header triggers a 30-minute rebuild; how do you find why and cut that dependency?

level: seniorimportance: should knowfreq 42%

answer

  1. who includes it, transitively
  2. dependency files and the include tree
  3. include what you use
  4. pimpl as a compile firewall
  5. destructor defined where Impl is complete

basics

~20 s

Find 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 s

The 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
cpp
#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

for a junior

Know that changing a header recompiles every .cpp file that includes it, even indirectly, and that headers should include only what they need.

for a middle

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.

for a senior

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.

for a principal

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.