Skip to content

external-rustc-drivers.md

Latest commit

 

History

History
92 lines (59 loc) · 3.04 KB

external-rustc-drivers.md

File metadata and controls

92 lines (59 loc) · 3.04 KB

External rustc_drivers

rustc_private

Overview

The rustc_private feature allows external crates to use compiler internals.

Using rustc_private with Official Toolchains

When using the rustc_private feature with official Rust toolchains distributed via rustup, you need to install two additional components:

  1. rustc-dev: Provides compiler libraries
  2. llvm-tools: Provides LLVM libraries required for linking

Installation Steps

Install both components using rustup:

rustup component add rustc-dev llvm-tools

Common Error

Without the llvm-tools component, you'll encounter linking errors like:

error: linking with `cc` failed: exit status: 1
  |
  = note: rust-lld: error: unable to find library -lLLVM-{version}

Using rustc-private with Custom Toolchains

For custom-built toolchains or environments not using rustup, additional configuration is typically required:

Requirements

  • LLVM libraries must be available in your system's library search paths
  • The LLVM version must match the one used to build your Rust toolchain

Troubleshooting Steps

  1. Verify LLVM is installed and accessible
  2. Ensure that library paths are set: 
    export LD_LIBRARY_PATH=/path/to/llvm/lib:$LD_LIBRARY_PATH
  3. Ensure your LLVM version is compatible with your Rust toolchain

Configuring rust-analyzer for out-of-tree projects

When developing out-of-tree projects that use rustc_private crates, you can configure rust-analyzer to recognize these crates.

Configuration Steps

  1. Configure rust-analyzer.rustc.source to "discover" in your editor settings.
    For VS Code, add to rust_analyzer_settings.json:

    {
    "rust-analyzer.rustc.source": "discover"
}

  2. Add the following to the Cargo.toml of every crate that uses rustc_private:

    [package.metadata.rust-analyzer]
rustc_private = true

This configuration allows rust-analyzer to properly recognize and provide IDE support for rustc_private crates in out-of-tree projects.

Getting Specific Nightly Documentation for rustc_private

The nightly-rustc internal crates' documentation is only available for the latest nightly. If you depend on compiler internals from an older nightly, you may want to refer to the internal documentation from that particular nightly. The only way to do this is to generate the documentation locally. For example, to get documentation for nightly-2025-11-08:

Get the Git commit hash for that nightly:

rustup toolchain install nightly-2025-11-08
rustc +nightly-2025-11-08 --version --verbose

The output will include a commit-hash line identifying the exact source revision. Check out rust-lang/rust at that commit, then follow the steps in compiler documentation.

Additional Resources

  • GitHub Issue #137421 explains that rustc_private linker failures often occur because llvm-tools is not installed