No documentation for minimal and maximal LLVM versions supported

[dilyanpalauzov]

Location

Nowhere

Summary

When I build rustc with the local llvm, I want to know with what external LLVM versions will rustc work.

#122649 upgrades in March the minimum external LLVM version to 17.
#127513 updates in July LLVM to version 19.

But the above links do not touch the user-visible documentation. For me it is unclear, if I want to compile rust 1.82 later, if I can use LLVM 18, or I must use LLVM 19. I find no place, where this is documented.

• Document the minimal and maximal versions for external LLVM supported by rustc.

[the8472]

https://rustc-dev-guide.rust-lang.org/backend/updating-llvm.html

Rust supports building against multiple LLVM versions:
Tip-of-tree for the current LLVM development branch is usually supported within a few days. PRs for such fixes are tagged with llvm-main.
The latest released major version is always supported.
The one or two preceding major versions are usually supported.

bootstrap should also be telling you if it's too old

rust/src/bootstrap/src/core/build_steps/llvm.rs

Line 602 in fb20e4d

panic!("\n\nbad LLVM version: {version}, need >=18\n\n")

[dilyanpalauzov]

If I remember correctly, at least in the past this was the case, when rustc is asked to build itself with external LLVM, and something from that LLVM was not fine, the build process downloaded and rebuild that part. (linker, nm-wrapper, or alike - I do not recall what exactly). It should have aborted with hints how to build the external LLVM instead.

It is good that build_steps/llvm.rs aborts on too-old LLVM, but I want actually to read somewhere what LLVM version I need before starting the bootstrap process.

Considering the first paragraph, I have the feeling that if rustc thinks something in LLVM is not new-enough, it will not use that piece of external LLVM, but recompile it itself, despite being told to use external LLVM, and will not abort. So in fact rustc does not use external LLVM completely.

[DianQK]

See Compatibility Notes at https:/rust-lang/rust/releases/tag/1.79.0.

[dilyanpalauzov]

The changelog for 1.79 says at https:/rust-lang/rust/releases/tag/1.79.0 „Update the minimum external LLVM to 17“.

But for 1.80 and 1.81 there is no statement what minimal version the external LLVM must have.

[workingjubilee]

The required LLVM is going to be LLVM 18, actually. #130487

@dilyanpalauzov Why are you guessing instead of just using the latest LLVM release from that version's date of release? Or using the same version that rustc did for the last release?

[workingjubilee]

The problem with the documentation is that if we document this and it becomes horribly out of date because people forgot to update it because we are all just using the LLVM we build with rustc, then you'll be back to where you were: you still don't know. Meanwhile, using rustc --version --verbose always works, and that has to be the version you can bootstrap the next withe.