One Version of the Headers, Another Version of the Generator

Series contents · Engineering and Delivery · 阅读中文版

“I fixed the LLVM path. Why does the generated code still fail to compile?”

The configuration log reports the right dependency directory. The compiler complains that an interface is missing. The first response is to add headers. A few files start compiling; another target breaks.

It is worth pausing for a question that sounds almost too simple: is this build actually using only one LLVM/MLIR toolchain?

Why a version number is not enough

A compiler project has at least three kinds of upstream toolchain inputs: headers read during compilation, libraries used during linking, and generators executed during the build. They can come from different locations.

Imagine that configuration discovers toolchain A’s CMake package, while a custom command invokes a generator through PATH:

1
2
3

find_package → headers and libraries from toolchain A
PATH         → a description-file generator from toolchain B
default include paths → another old installation

If their interfaces happen to be compatible, this mixture can appear healthy for a long time. A change in description-file syntax, generated interfaces, or implicit header dependencies exposes it. An error in generated code does not necessarily call for editing generated code.

The reviewed change checked the expected toolchain version, bound the generator path to the tools directory supplied by the discovered toolchain, and collected the corresponding include paths. Together, these establish consistency. Doing only one can leave gaps.

Draw the chain of responsibility

Trace an error in a generated file backward through its dependencies:

1
2
3
4

Compilation error
  ← generated declarations or definitions
  ← description files + generator + generator include paths
  ← toolchain selected during configuration

Then ask concrete questions. Which source directory supplied the descriptions? What is the generator’s absolute path? Which includes did it use? Which headers did the compiler read when compiling the generated result?

Recording paths is a debugging technique, not a reason to embed absolute paths in a distributed program. A build needs precise input selection; a runtime package often needs relocation. Confusing those requirements creates a different problem elsewhere.

Similarly, “Found version X” is evidence, but not a full identity. A modified toolchain branch can report the same base version string as another installation while exposing different interfaces. Strict version checks catch obvious mismatches; revision identifiers, build options, and package contents provide stronger provenance.

API renaming and semantic migration are different jobs

The reviewed adaptations changed pass lookup, arithmetic operation construction, and explicit interface includes. All can be called “version compatibility,” but they require at least three kinds of reasoning.

First, an API may move to a different class or namespace. Confirm the meaning of its arguments, return value, and failure behavior. Finding a similarly named function is not the end of the migration.

Second, header dependencies may need to become explicit. A previously indirect include happened to expose an interface; an update removed that accidental connection. The usual repair is a direct dependency at the use site, not an oversized shared header that makes every module happen to see everything again.

Third, a replacement may differ semantically. Floating-point maximum operations can have similar names but different behavior for NaNs or signed zero. The reviewed diff did replace the relevant operation class. Successful compilation alone cannot establish equivalence at those boundaries. Check the semantics for the versions involved and verify edge cases.

Why not add macros to “support every version”?

Compatibility layers are useful when they cover a real support commitment. If a project validates one toolchain but adds branches for many untested versions, it becomes more flexible on paper while its verification space expands.

Two generator versions, two header interfaces, two library sets, and two compilation configurations already create more combinations than casual testing tends to cover. A version branch may also solve a declaration mismatch without addressing a semantic change.

For a fixed delivery environment, rejecting incompatible inputs early is often the more honest contract. A project that truly supports several upstream versions should make that a test matrix: specify the generator, library, and header combinations in each column. A list of versions that “compile” is not enough.

What would an explainable validation look like?

The following checks are proposed methods.

The fresh-build-tree check matters. A changed configuration variable can coexist with cached old paths. One developer succeeds after recreating everything, another fails with the existing tree, and both insist they ran the same command. They did not supply the same effective inputs.

Inspect the relevant cache entries before choosing reconfiguration or a separate build directory. “Rebuild everything” can be an experiment; it is not an explanation.

An easy-to-miss entry point

When a C++ compiler receives pass options through Python bindings, an upstream API change may affect that path without affecting the native command-line entry point. Native smoke tests can all pass while Python users still fail.

Entry points therefore belong in the verification matrix too: the native optimizer, Python bindings, and generated command builders should be checked separately. Otherwise, the adaptation may repair only the interface most familiar to its developer.

Binding the generator to a known path does not by itself make compilation faster. It removes ambiguity and repeated investigation. Incremental-build benefits require separate measurements; one cache hit is not proof that toolchain consistency improved performance.

A healthy build system can explain who produced a line of generated code and from which inputs. Once the answer becomes a dependency chain instead of “there was something on PATH,” many bizarre compilation failures become ordinary interface mismatches.

Series contents · Previous · Next

• ← Previous Post
• Next Post →