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. Check LLVM installation: Verify LLVM is installed and accessible
  2. Configure library paths: You may need to set environment variables:
    export LD_LIBRARY_PATH=/path/to/llvm/lib:$LD_LIBRARY_PATH
  3. Check version compatibility: 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. Set rust-analyzer configuration 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 metadata to Cargo.toml
    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.

Additional Resources

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