Include Clang in llvm-tools #3847
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| - Feature Name: Include Clang in llvm-tools | ||
| - Start Date: 2025-08-04 | ||
| - RFC PR: [rust-lang/rfcs#3847]() | ||
| - Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) | ||
|
|
||
| # Summary | ||
| [summary]: #summary | ||
|
|
||
| Include a version of `clang` and `clang++` compiled against Rust LLVM in the `llvm-tools` component in nightly. | ||
|
There was a problem hiding this comment. Question: does this mean we would need to be building There was a problem hiding this comment. I'm not entirely sure, but it would probably depend on if the dist builder includes the There was a problem hiding this comment. Discussion: hm, this means that some maintenance bandwidth would need to be used for keeping There was a problem hiding this comment. Yes, but it shouldn't be much, because the other llvm tools are already being built. |
||
|
|
||
| # Motivation | ||
| [motivation]: #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](https://actually.fyi/posts/zig-makes-rust-cross-compilation-just-work/) led to easy cross-compiles in Rust to Macos. | ||
|
Comment on lines
+14
to
+16
There was a problem hiding this comment. I don't see any explicit mention of sysroots, and mentioning Zig-like capabilities as future work suggests it's not in scope for this RFC. In other words, the propsal for now is to ship only the compiler binary, not all the other files needed to actually compile C and C++ code, and rely on those to already be installed by other means? There was a problem hiding this comment. I'm not very familiar with cross-compiling, which is why I listed it as future work. My understanding of the compiler binary is that it depends on the other llvm tools, and wouldn't introduce new dependencies for users, at least when not cross-compiling. There was a problem hiding this comment. Even without the complications of cross-compiling, the compiler binary and other tools aren't enough to usefully compile C and C++ code. At minimum you headers and static/dynamic libraries for the C standard library and other runtime facilities that are expected on that platform (e.g., on Linux with glibc that's libc and crt0 for C programs, often also libm and pthreads and probably more I'm forgetting). People would still need to have those installed to get any use out of the clang, lld, etc. binaries. In practice they'll probably have the libraries installed anyway because on most host platforms rustc requires that a basic C toolchain is installed for linking Rust programs (e.g., on Unix platforms |
||
|
|
||
| ## Background | ||
|
|
||
| `clang` and `clang++` are LLVM-based C and C++ compilers mentioned in [official documentation](https://doc.rust-lang.org/rustc/linker-plugin-lto.html): | ||
| ```bash | ||
| # 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++`. | ||
|
|
||
| ## Stability Guarantee | ||
|
|
||
| The only stability guarantee is that the versions of `clang` and `clang++` will have the same LLVM version as Rust and the other LLVM tools. It is not guaranteed that `clang` and `clang++` will never break their own interfaces. | ||
|
|
||
| ## 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 | ||
|
There was a problem hiding this comment. Do we expect distros (e.g., Debian, Fedora) to ship a Rust clang if we start doing this? Or will Rust users only get this experience from a rustup install? Do we expect that to mean that e.g. ecosystem crates are encouraged to not worry as much about C/C++ compiler version compatibility since many Rust users get very recent compilers through this mechanism? I think they don't ship llvm tools today in general. There was a problem hiding this comment. I was thinking about it as an alternate release pattern to avoid dealing with distro-specific variations; we would only allow installation via rustup, not by distro. We already have this infrastructure in place for the other LLVM tools. Most crates could continue using system-installed compilers, as C has a stable ABI, and fine-tuning with LLVM isn't necessary for most applications. There was a problem hiding this comment. I think the stability should be "we provide clang and it will have llvm of a matching version as rust has, that's it". Otherwise it will be perma-nightly. There was a problem hiding this comment.
Sure, I don't think there's a reasonable way we can commit to something more stable than that. But I think it's worth having a section in the RFC on how we teach users that this is not subject to the normal relatively strict stability guarantees we have, and in particular e.g. -Werror and similar are probably a bad idea when compiling with this clang. Is that sufficiently discoverable? Does it help that it's in a separate component (perhaps we shouldn't repeat the mistake of skipping -preview in the name?)? Is there some warning we should embed on first use or in rustup add? There was a problem hiding this comment. Having it in nightly-only seems like it would be sufficient to avoid stability guarantees. I don't think there are many people opting into nightly-only features and expecting them to never break |
||
| [drawbacks]: #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. | ||
|
There was a problem hiding this comment. Compile times and storage requirements would be increased for the Manual compilation processes means compiling with tools other than just It could be at odds with the Rust vision, because Rust wasn't intended to come with a C/C++ compiler as an optional component, and it would mean including a compiler that isn't part of |
||
|
|
||
| # Rationale and alternatives | ||
|
There was a problem hiding this comment. It could be a separate component e.g. There was a problem hiding this comment. I think it would be best to keep it in On the other hand, I mention this in the "Unresolved Questions" section because I'm not sure which choice is better. |
||
| [rationale-and-alternatives]: #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 | ||
| [prior-art]: #prior-art | ||
|
|
||
| This may help in the goal [Expose experimental LLVM features for GPU offloading](https://rust-lang.github.io/rust-project-goals/2025h1/GPU-Offload.html), as raw LLVM access is particularly useful for GPU compilation libraries. | ||
|
|
||
| This was mentioned in [Shipping clang as a Rustup component](https://github.com/rust-lang/rust/issues/56371) | ||
|
|
||
| See also the issues for [`llvm-dis`, `llc` and `opt`](https://github.com/rust-lang/rust/issues/55890) | ||
|
|
||
| # Unresolved questions | ||
| [unresolved-questions]: #unresolved-questions | ||
|
|
||
| Should `clang` and `clang++` be part of the `llvm-tools` component or added as their own component? | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is "on nightly" intended to be load bearing here?
In general this RFC I think needs to more clearly document the user expectations around breakage and whether we're ok making it common to reference this tool. Today, we mostly rely on slow moving distros I think to mitigate the less stable interfaces clang (and in general C / C++ compilers expose, to my knowledge), but if we're shipping it ourselves that pushes towards Rust being the one blamed for breakage.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure what the Rust way to manage stabilization for this is. The problem is that if it were in stable, breaking changes from clang interfaces might count as breaking changes that trickle into Rust.
I included the "in nightly" to limit the scope of this RFC to avoid having to deal with this question, as such an unlikely type of breakage wouldn't be a problem on nightly.