Which version of librustc_driver clippy uses?

[manswami23]

Description

Hello,

I'm a beginner trying to poke around in clippy. I've asked a couple silly questions so far, so I hope nobody minds a couple more :). I'm specifically poking around with how clippy determines which rustc_driver to link against.

On my machine, I've got two toolchains installed through rustup. nightly-2025-02-06 and stable 1.86.0.

bash-5.2# rustup show
Default host: aarch64-unknown-linux-gnu
rustup home:  /root/.rustup

installed toolchains
--------------------
nightly-2025-02-06-aarch64-unknown-linux-gnu (active)
1.86.0-aarch64-unknown-linux-gnu (default)

I've noticed that when I run clippy with the nightly toolchain, it links against a specific version of rustc_driver: librustc_driver-3e6e9637b7731f3f.so.

When I run clippy with the 1.86.0 toolchain, it looks for librustc_driver-d10e1ea80d090031.so.

Originally, I assumed that the difference is because both clippy versions are being packaged with different rust toolchains. And that there's probably something happening as part of this packaging that dictates to the final clippy executable which driver to link against.

However, I started to stumble when I noticed that for the version of clippy that's been copied/synced into the rust repo for rust 1.86.0, it's toolchain declares that it must be built with nightly-2025-02-06: https://github.com/rust-lang/rust/blob/1.86.0/src/tools/clippy/rust-toolchain.

And I confirmed on my local that when I manually build clippy at commit 3e3715c (ie the commit which I believe corresponds to the aforementioned copied/synced clippy code), the resulting cargo-clippy executable looks for librustc_driver-3e6e9637b7731f3f.so, not librustc_driver-d10e1ea80d090031.so. That is to say, it links against the driver from the nightly toolchain rather than the stable 1.86 toolchain.

(If it helps, this is how I build clippy: cargo build --release --bin cargo-clippy --bin clippy-driver -Zunstable-options --out-dir "$(rustc --print=sysroot)/bin")

So I guess my questions are

1. How come when I built clippy independently using the nightly toolchain, the resulting executable loads the nightly toolchain's rustc_driver. Whereas the clippy embedded inside the rust repo is linking against the stable tool chain rustc_driver even though the clippy toolchain.toml file specifies it builds against the nightly.
2. Is there some logic that specifies for the clippy code embedded inside the rust repo, that it should specifically link against the toolchain for that version of rust rather than the nightly toolchain with which clippy was built? If so, could someone point me to that logic?
3. When I built clippy locally, how can I dictate the final program to link against the stable rustc_driver?

Thanks!

Version

Stable Toolchain

rustc 1.86.0 (05f9846f8 2025-03-31)
binary: rustc
commit-hash: 05f9846f893b09a1be1fc8560e33fc3c815cfecb
commit-date: 2025-03-31
host: aarch64-unknown-linux-gnu
release: 1.86.0
LLVM version: 19.1.7


Nightly Toolchain that I'm using to build clippy locally
rustc 1.86.0-nightly (a9730c3b5 2025-02-05)
binary: rustc
commit-hash: a9730c3b5f84a001c052c60c97ed0765e9ceac04
commit-date: 2025-02-05
host: aarch64-unknown-linux-gnu
release: 1.86.0-nightly
LLVM version: 19.1.7

Additional Labels

@rustbot label + C-question

[rustbot]

Error: Parsing relabel command in comment failed: ...' label +' | error: empty label at >| ' C-questio'...

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #t-infra on Zulip.

[samueltardieu]

The Clippy repository is synced against the Rust compiler repository every two weeks, in both directions. It means that in the meantime:

• changes in the Rust compiler repository modify their version of Clippy as needed, to ensure that it still compiles and runs tests appropriately, but without adding any Clippy functionality or bug fix — it is needed to release a nightly version which includes Clippy
• new developments in Clippy use the same Rust compiler version (librustc_driver) for two weeks between the syncs — new developments in the compiler cannot be used in Clippy in the meantime.

During the sync process, the person in charge of it (@flip1995) takes care of modifying the changes made into the Clippy repository for the last two weeks to accommodate the changes made to the Rust compiler during the same time frame. This can be quite complex as new developments in Clippy have been made against the old version of the Rust compiler internals (2 weeks old may feel really old given the active development of the compiler). This can be a daunting task.

As a consequence of this process, and as a more direct answer to your questions:

• Clippy developments always occur against the nightly toolchain (≤ 2 weeks old, due to the sync period) within the Clippy repository – we never develop against stable or beta toolchains
• When the Rust compiler branches from master to beta, it also includes the version of Clippy found in the Rust compiler repository at this point, which becomes frozen, unless some bugfixes PR are manually cherry-picked, as for the Rust compiler itself. As a consequence, this version of Clippy is built against a beta version of the Rust compiler libraries, and when it is time to release a new stable version of Rust, they will build Clippy against the stable version of the Rust compiler libraries. Except for manually backported fixes, Clippy hasn't changed since the first beta version, as is the case for the Rust compiler. Only the denomination of the compiler libraries change, from beta to stable.

For example, the beta branch for Rust 1.88 should be cut later today (May 9, 2025) from the Rust repository. It will include the current state of the Clippy sync, which was done on May 1st. New developments that happened in Clippy since the last sync (one week ago) will not be included in the 1.88 beta (unless they are manually backported during the beta period — we already have some PR that we want to backport to the beta, to prevent recently introduced bugs from ever reaching the stable version users).

Does it makes it clearer?

[manswami23]

Thanks @samueltardieu , yes it's starting to become clear.

Just to echo it back to make sure I understood correctly... when the beta/stable branches get cut, clippy gets built against the beta/stable version of Rust rather than the nightly toolchain. This is because at branch time, we would have already done the syncing process; and as a result of the syncing process, this particular rust version and clippy version are known to be compatible with each other?

As a follow up, how exactly does the build work? I attempted to modify the toolchain file in my local clippy repo to no longer reference the nightly toolchain and instead look at the version of rust with which it was presumably packaged as part of the 1.86 release:

[toolchain]
channel = "1.86.0"
components = ["cargo", "llvm-tools", "rust-src", "rust-std", "rustc", "rustc-dev", "rustfmt"]
profile = "minimal"

However, running cargo build --release --bin cargo-clippy --bin clippy-driver gives the following error that suggests I switch back to nightly? :

error: failed to run `rustc` to learn about target-specific information

Caused by:
  process didn't exit successfully: `/root/.rustup/toolchains/1.86.0-aarch64-unknown-linux-gnu/bin/rustc - --crate-name ___ --print=file-names -Zunstable-options -Zbinary-dep-depinfo --crate-type bin --crate-type rlib --crate-type dylib --crate-type cdylib --crate-type staticlib --crate-type proc-macro --print=sysroot --print=split-debuginfo --print=crate-name --print=cfg -Wwarnings` (exit status: 1)
  --- stderr
  error: the option `Z` is only accepted on the nightly compiler

  help: consider switching to a nightly toolchain: `rustup default nightly`

  note: selecting a toolchain with `+toolchain` arguments require a rustup proxy; see <https://rust-lang.github.io/rustup/concepts/index.html>

  note: for more information about Rust's stability policy, see <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html#unstable-features>

  error: 1 nightly option were parsed

[samueltardieu]

Just to echo it back to make sure I understood correctly... when the beta/stable branches get cut, clippy gets built against the beta/stable version of Rust rather than the nightly toolchain. This is because at branch time, we would have already done the syncing process; and as a result of the syncing process, this particular rust version and clippy version are known to be compatible with each other?

This is the idea. As the Rust compiler folks start to mark a branch in their repository as beta or stable, they drag with them other tools as they are, such as Clippy, rustdoc or Cargo, which are synced to the Rust compiler repository on a regular basis. Those will follow the same terminology and be labelled as beta, then stable.

As for your latest question: as I indicated before, from a Clippy developer point of view, development always happens against a recent (≤ 2 weeks) version of the Rust compiler. Since this is a nightly version, we are free to use -Z option during development.

If you want to check out an earlier version of the Clippy repository, it should work as long as you don't change the required toolchain, which was an earlier nightly version (which supports -Z). Stable versions restrict what you can do.

Why are you trying to build against a stable toolchain? What would be the benefit?

[manswami23]

sorry, I should have mentioned this at the beginning of the post.

one of the things I'm expirementing with is forking clippy and override my existing stable 1.86.0 toolchain to point to my custom built cargo-clippy and clippy-driver executables. Reason is I feel it likely in the future that my colleagues and I might want to write custom linting; so forking and maintaining our own copy of clippy seemed to way to go.

My rudimentary (and possibly ill-advised lol) steps were to

1. Install the 1.86.0 toolchain
2. Clone rust-clippy and checkout the commit corresponding to 1.86
3. Build cargo-clippy and clippy-driver
4. As https://doc.rust-lang.org/nightly/clippy/development/basics.html#install-from-source indicates, this will override the nightly toolchain with which my local copy of clippy was built.
5. At this point, I can run something like cargo +nightly-2025-02-06 clippy against my project. However, it didn't feel very ergonomic to have to switch toolchains everytime I want to run static analysis. What I really wanted was to plop the clippy executables into my stable toolchain
6. My next step was to move the cargo-clippy and clippy-driver files from the nightly toolchain folder to /root/.rustup/toolchains/1.86.0-aarch64-unknown-linux-gnu/bin. However, running cargo clippy predictably failed because clippy is looking for the rustc_driver from the nightly toolchain, and I guess when I run cargo clippy, it doesn't set LD_LIBRARY_PATH to point to the nightly toolchain folder : /root/.rustup/toolchains/1.86.0-aarch64-unknown-linux-gnu/bin/cargo-clippy: error while loading shared libraries: librustc_driver-3e6e9637b7731f3f.so: cannot open shared object file: No such file or directory
7. I thought maybe I could manually set LD_LIBRARY_PATH? And while this got past the previous point of failure, it still ended up failing during the actual compile because my project was built with 1.86 but my clippy was linking against 1.86-nightly:

note: the following crate versions were found:
            crate `syn` compiled by rustc 1.86.0 (05f9846f8 2025-03-31): /workspaces/app/server/target/debug/deps/libsyn-d0e202c815253fc4.rlib
    = help: please recompile that crate using this compiler (rustc 1.86.0-nightly (a9730c3b5 2025-02-05)) (consider running `cargo clean` first)

8. After giving this some thought, I realized that I probably didn't want to have to run clippy using the nightly-build against my project. Because that would require constantly cargo clean-ing when I switch building with 1.86 vs 1.86-nightly. So I instead pivoted to seeing how I can produce a clippy executable that knows to link against the rustc_driver within the stable toolchain.

I assumed that if I change the toolchain.toml file in rust-clippy to point to the stable rust 1.86, that it would automatically override the clippy component inside my stable toolchain. However, as you correctly pointed out, that won't work because the clippy build gets restricted by the stable toolchain. Which has now left me curious how exactly the clippy component that's packaged with stable rust is able to link against the stable toolchain, and what I can do to mimic the same behavior on my local.

[Alexendoo]

The clippy-driver you can download from rustup isn't built from this repository, the rust-lang/rust-clippy repo is only for development of clippy itself so there's no way to build it for stable as far as I'm aware

To get a built against stable 1.86 clippy-driver you'd have to checkout rust-lang/rust@05f9846 and run the required ./x build src/tools/clippy command, I don't know the exact arguments that it's equivalent to

Similar custom linters such as bevy_lint go with the pin a nightly approach

[flip1995]

• How come when I built clippy independently using the nightly toolchain, the resulting executable loads the nightly toolchain's rustc_driver. Whereas the clippy embedded inside the rust repo is linking against the stable tool chain rustc_driver even though the clippy toolchain.toml file specifies it builds against the nightly.

When building Clippy in the rust-clippy repo, rustup will automatically install the nightly toolchain listed in the rust-toolchain.toml file. When building in the Rust repo, this file is ignored, as the Rust compiler is not directly build with cargo/rustup, but with a build tool in the repo called bootstrap. bootstrap first builds the Rust compiler in the repo and then builds Clippy with the Rust compiler that was just built. When doing that on the rust-lang/rust stable branch (on release), it will be linked against the Rust compiler that was just built, which is the stable compiler.

• Is there some logic that specifies for the clippy code embedded inside the rust repo, that it should specifically link against the toolchain for that version of rust rather than the nightly toolchain with which clippy was built? If so, could someone point me to that logic?

See bootstrap. It's complicated. For an explanation, see the rustc-dev-guide

• When I built clippy locally, how can I dictate the final program to link against the stable rustc_driver?

You can't. Clippy usually only builds with a specific nightly version, the one in the rust-toolchain.toml file. As only that version of rustc-driver can be used to build Clippy, you can also only link against that version of rustc-driver.

[flip1995]

so forking and maintaining our own copy of clippy seemed to way to go.

That just makes things harder for you. The situation for custom linters in Rust is not ideal (yet). Work is going on to improve the situation. If you want to write your own linter, I recommend to do that from scratch. The boilerplate (the two files in the src/ dir in this repo) is not too big. See bevy_lint mentioned by Alex or klint used in the Rust for Linux project. klint actually uses a stable version of rustc. However, this is not recommended if you aren't absolutely sure what you are doing.