src/tools/rust-analyzer/crates/proc-macro-srv/src/abis/mod.rs

   1 //! Procedural macros are implemented by compiling the macro providing crate
   2 //! to a dynamic library with a particular ABI which the compiler uses to expand
   3 //! macros. Unfortunately this ABI is not specified and can change from version
   4 //! to version of the compiler. To support this we copy the ABI from the rust
   5 //! compiler into submodules of this module (e.g proc_macro_srv::abis::abi_1_47).
   6 //!
   7 //! All of these ABIs are subsumed in the `Abi` enum, which exposes a simple
   8 //! interface the rest of rust-analyzer can use to talk to the macro
   9 //! provider.
  10 //!
  11 //! # Adding a new ABI
  12 //!
  13 //! To add a new ABI you'll need to copy the source of the target proc_macro
  14 //! crate from the source tree of the Rust compiler into this directory tree.
  15 //! Then you'll need to modify it
  16 //! - Remove any feature! or other things which won't compile on stable
  17 //! - change any absolute imports to relative imports within the ABI tree
  18 //!
  19 //! Then you'll need to add a branch to the `Abi` enum and an implementation of
  20 //! `Abi::expand`, `Abi::list_macros` and `Abi::from_lib` for the new ABI. See
  21 //! `proc_macro_srv/src/abis/abi_1_47/mod.rs` for an example. Finally you'll
  22 //! need to update the conditionals in `Abi::from_lib` to return your new ABI
  23 //! for the relevant versions of the rust compiler
  24 //!
  25
  26 mod abi_1_58;
  27 mod abi_1_63;
  28 mod abi_1_64;
  29 #[cfg(feature = "sysroot-abi")]
  30 mod abi_sysroot;
  31
  32 // see `build.rs`
  33 include!(concat!(env!("OUT_DIR"), "/rustc_version.rs"));
  34
  35 // Used by `test/utils.rs`
  36 #[cfg(test)]
  37 pub(crate) use abi_1_64::TokenStream as TestTokenStream;
  38
  39 use super::dylib::LoadProcMacroDylibError;
  40 pub(crate) use abi_1_58::Abi as Abi_1_58;
  41 pub(crate) use abi_1_63::Abi as Abi_1_63;
  42 pub(crate) use abi_1_64::Abi as Abi_1_64;
  43 #[cfg(feature = "sysroot-abi")]
  44 pub(crate) use abi_sysroot::Abi as Abi_Sysroot;
  45 use libloading::Library;
  46 use proc_macro_api::{ProcMacroKind, RustCInfo};
  47
  48 pub struct PanicMessage {
  49     message: Option<String>,
  50 }
  51
  52 impl PanicMessage {
  53     pub fn as_str(&self) -> Option<String> {
  54         self.message.clone()
  55     }
  56 }
  57
  58 pub(crate) enum Abi {
  59     Abi1_58(Abi_1_58),
  60     Abi1_63(Abi_1_63),
  61     Abi1_64(Abi_1_64),
  62     #[cfg(feature = "sysroot-abi")]
  63     AbiSysroot(Abi_Sysroot),
  64 }
  65
  66 impl Abi {
  67     /// Load a new ABI.
  68     ///
  69     /// # Arguments
  70     ///
  71     /// *`lib` - The dynamic library containing the macro implementations
  72     /// *`symbol_name` - The symbol name the macros can be found attributes
  73     /// *`info` - RustCInfo about the compiler that was used to compile the
  74     ///           macro crate. This is the information we use to figure out
  75     ///           which ABI to return
  76     pub fn from_lib(
  77         lib: &Library,
  78         symbol_name: String,
  79         info: RustCInfo,
  80     ) -> Result<Abi, LoadProcMacroDylibError> {
  81         // the sysroot ABI relies on `extern proc_macro` with unstable features,
  82         // instead of a snapshot of the proc macro bridge's source code. it's only
  83         // enabled if we have an exact version match.
  84         #[cfg(feature = "sysroot-abi")]
  85         {
  86             if info.version_string == RUSTC_VERSION_STRING {
  87                 let inner = unsafe { Abi_Sysroot::from_lib(lib, symbol_name) }?;
  88                 return Ok(Abi::AbiSysroot(inner));
  89             }
  90
  91             // if we reached this point, versions didn't match. in testing, we
  92             // want that to panic - this could mean that the format of `rustc
  93             // --version` no longer matches the format of the version string
  94             // stored in the `.rustc` section, and we want to catch that in-tree
  95             // with `x.py test`
  96             #[cfg(test)]
  97             {
  98                 let allow_mismatch = std::env::var("PROC_MACRO_SRV_ALLOW_SYSROOT_MISMATCH");
  99                 if let Ok("1") = allow_mismatch.as_deref() {
 100                     // only used by rust-analyzer developers, when working on the
 101                     // sysroot ABI from the rust-analyzer repository - which should
 102                     // only happen pre-subtree. this can be removed later.
 103                 } else {
 104                     panic!(
 105                         "sysroot ABI mismatch: dylib rustc version (read from .rustc section): {:?} != proc-macro-srv version (read from 'rustc --version'): {:?}",
 106                         info.version_string, RUSTC_VERSION_STRING
 107                     );
 108                 }
 109             }
 110         }
 111
 112         // FIXME: this should use exclusive ranges when they're stable
 113         // https://github.com/rust-lang/rust/issues/37854
 114         match (info.version.0, info.version.1) {
 115             (1, 58..=62) => {
 116                 let inner = unsafe { Abi_1_58::from_lib(lib, symbol_name) }?;
 117                 Ok(Abi::Abi1_58(inner))
 118             }
 119             (1, 63) => {
 120                 let inner = unsafe { Abi_1_63::from_lib(lib, symbol_name) }?;
 121                 Ok(Abi::Abi1_63(inner))
 122             }
 123             (1, 64..) => {
 124                 let inner = unsafe { Abi_1_64::from_lib(lib, symbol_name) }?;
 125                 Ok(Abi::Abi1_64(inner))
 126             }
 127             _ => Err(LoadProcMacroDylibError::UnsupportedABI),
 128         }
 129     }
 130
 131     pub fn expand(
 132         &self,
 133         macro_name: &str,
 134         macro_body: &tt::Subtree,
 135         attributes: Option<&tt::Subtree>,
 136     ) -> Result<tt::Subtree, PanicMessage> {
 137         match self {
 138             Self::Abi1_58(abi) => abi.expand(macro_name, macro_body, attributes),
 139             Self::Abi1_63(abi) => abi.expand(macro_name, macro_body, attributes),
 140             Self::Abi1_64(abi) => abi.expand(macro_name, macro_body, attributes),
 141             #[cfg(feature = "sysroot-abi")]
 142             Self::AbiSysroot(abi) => abi.expand(macro_name, macro_body, attributes),
 143         }
 144     }
 145
 146     pub fn list_macros(&self) -> Vec<(String, ProcMacroKind)> {
 147         match self {
 148             Self::Abi1_58(abi) => abi.list_macros(),
 149             Self::Abi1_63(abi) => abi.list_macros(),
 150             Self::Abi1_64(abi) => abi.list_macros(),
 151             #[cfg(feature = "sysroot-abi")]
 152             Self::AbiSysroot(abi) => abi.list_macros(),
 153         }
 154     }
 155 }