Skip to content

State that incremental compilation assumes the same compiler - #3071

Closed
isHeSatoshi wants to merge 1 commit into
rust-lang:mainfrom
isHeSatoshi:document-incremental-same-compiler
Closed

isHeSatoshi wants to merge 1 commit into
rust-lang:mainfrom
isHeSatoshi:document-incremental-same-compiler

Conversation

@isHeSatoshi

@isHeSatoshi isHeSatoshi commented Oct 19, 2026 •

Copy link
Copy Markdown

Fixes #1860.

The chapter describes the red-green algorithm without saying that it assumes the compiler itself does not change between the previous and the current compilation. That is an easy assumption to miss while reading a guide about how to build and change the compiler: if a query's implementation changes, the same inputs no longer produce the same result, and the saved query DAG stops meaning anything.

The issue also asks whether it works anyway when you change rustc. It does not get the chance to, because rustc discards the cache rather than trying to cope with it.

This adds a note at the top of the chapter covering both points:

  • the assumption is that the same compiler is used for both compilations;
  • each incremental cache file starts with a header containing the compiler's version string, which encodes the git commit hash of the compiler that wrote it, and a file whose header does not match is treated as out of date.

Where this comes from, for review:

  • rustc_incremental/src/persist/file_format.rs writes the header as FILE_MAGIC, a HEADER_FORMAT_VERSION, and the result of rustc_version(sess), which is sess.cfg_version (with a RUSTC_FORCE_RUSTC_VERSION override that tests use to force a mismatch on demand). Its module docs state that "compatible compiler version" means "exactly the same compiler version", since the header encodes the git commit hash of the compiler, and that being conservative costs little because the cache can always just be ignored.
  • A header mismatch surfaces as OpenFileError::NotFoundOrHeaderMismatch, which load_dep_graph maps to LoadResult::DataOutOfDate, documented as "The file either didn't exist or was produced by an incompatible compiler version".
  • setup_dep_graph handles DataOutOfDate by calling invalidate_old_session_dir and starting from an empty dep graph.

No new links are added.

Nothing in the chapter said that the red-green algorithm assumes the
compiler itself is unchanged between the previous and the current
compilation. A reader who is still thinking about building the compiler
can reasonably wonder whether the saved query DAG is reused when the
compiler changes, since a changed query produces a different result for
the same inputs.

Add a note at the top: the assumption is that the same compiler is used,
and `rustc` does not try to cope with a changed one. Each cache file
begins with a header containing the compiler's version string, which
encodes the git commit hash, and a file whose header does not match is
treated as out of date, which invalidates the session directory and
starts the compilation from scratch.
@isHeSatoshi

This comment was marked as low quality.

@rustbot

rustbot commented Oct 19, 2026

Copy link
Copy Markdown
Collaborator

Thanks for the PR. If you have write access, feel free to merge this PR if it does not need reviews. You can request a review using r? rustc-dev-guide or r? <username>.

@rustbot rustbot added the S-waiting-on-review Status: this PR is waiting for a reviewer to verify its content label Oct 19, 2026
@BoxyUwU BoxyUwU closed this Oct 19, 2026
@rustbot rustbot removed the S-waiting-on-review Status: this PR is waiting for a reviewer to verify its content label Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

In Compiler Architecture section, state explicitly you assume the compiler do not change between build

4 participants