Include Clang in llvm-tools

[SirAlienTheGreat]

• Feature Name: Include Clang in llvm-tools
• Start Date: 2025-08-04
• RFC PR: rust-lang/rfcs#3847
• Rust Issue: rust-lang/rust#0000

Summary

Include a version of clang and clang++ compiled against Rust LLVM in the llvm-tools component in nightly.

Motivation

Allowing user-access to the LLVM pipeline allows for many user-built features, such as cross-language inlining. However, LLVM version mismatching between tools can lead to frustrating problems. Including clang and clang++ in llvm-tools allows users to use only the tools that Rust ships with, ensuring consistent versioning.

In future versions of Rust, including a compiler with Rustup could also improve ergonomics for FFI crates, as it could avoid depending on system compilers. See how Zig's implementation led to easy cross-compiles in rust to Macos.

Background

clang and clang++ are LLVM-based C and C++ compilers mentioned in official documentation:

# Compile the Rust staticlib
RUSTFLAGS="-Clinker-plugin-lto" cargo build --release
# Compile the C code with `-flto=thin`
clang -c -O2 -flto=thin -o cmain.o ./cmain.c
# Link everything, making sure that we use an appropriate linker
clang -flto=thin -fuse-ld=lld -L . -l"name-of-your-rust-lib" -o main -O2 ./cmain.o

Unfortunately, this example does not always work, because it calls system clang, which may use a different version of LLVM than Rust. Additionally, even at the same version, there is a potential for problems from mixing base LLVM tools with the Rust fork of LLVM.

Rustup has the ability to install a component called llvm-tools, which exposes the llvm tools used by Rust, including llvm-link and llc - notably, it does not contain a build of clang or clang++.

Conclusion

Builds of clang and clang++ should be added to the llvm-tools component to enable version matching when working with base LLVM tools.

Drawbacks

This will increase compile times and require more storage on devices with the llvm-tools component installed.

It may also drive more people to use manual compilation processes, which may cause fragmentation or be at odds with the Rust vision.

Rationale and alternatives

Users can opt for system clang and clang++ when building projects with LLVM, however there is no guarantee that users will have an appropriate version of the system tools, or that the Rust fork of LLVM won't contain any breaking changes.

Prior art

This may help in the goal Expose experimental LLVM features for GPU offloading, as raw LLVM access is particularly useful for GPU compilation libraries.

This was mentioned in Shipping clang as a Rustup component

See also the issues for llvm-dis, llc and opt

Unresolved questions

Should clang and clang++ be part of the llvm-tools component or added as their own component?

Rendered

[ehuss]

Just dropping a link to the tracking issue for llvm tools: https://github.com/rust-lang/rust/issues/85658 Note that there are still outstanding questions around how they work (like the location on the filesystem is unclear).

[Kobzol]

I think that if the goal is to simply add clang to llvm-tools, as a best effort thing, then this doesn't even require an RFC, because we don't really promise anything about llvm-tools at the moment, AFAIK.

(We might want to have an RFC for actually stabilizing llvm-tools in the future)

[bjorn3]

llvm-tools is available on stable by accident and can be installed using rustup component add llvm-tools which has no clear indication that it is a preview component. So I think there is a pretty high risk that people will start depending on it on stable. The other tools in llvm-tools are much more niche by comparison.

[Kobzol]

Hmm, fair enough. llvm-profdata is already quite useful for PGO, I use it in cargo-pgo. It's possible that if we start shipping clang, more people would start depending on this component.

[jedbrown]

Similar proposal: https://github.com/rust-lang/compiler-team/issues/907 Zulip discussion: https://rust-lang.zulipchat.com/#narrow/channel/233931-t-compiler.2Fmajor-changes/topic/ship.20clang.20and.20llvm-ar.20in.20rustup.20compiler-team.23907/with/537928032

[kornelski]

If this included libclang, bindgen would become much easier to use.

[kornelski]

If accidental stability or bloat of llvm-tools is a problem, this could be packaged as a completely new clang(-preview) component. Later llvm-tools could be trimmed to only include tools that aren't in the clang package, or maybe rustup could be taught to install the common subset once.