proc_macro_api/
lib.rs

1//! Client-side Proc-Macro crate
2//!
3//! We separate proc-macro expanding logic to an extern program to allow
4//! different implementations (e.g. wasm or dylib loading). And this crate
5//! is used to provide basic infrastructure for communication between two
6//! processes: Client (RA itself), Server (the external program)
7
8#![cfg_attr(not(feature = "sysroot-abi"), allow(unused_crate_dependencies))]
9#![cfg_attr(
10    feature = "sysroot-abi",
11    feature(proc_macro_internals, proc_macro_diagnostic, proc_macro_span)
12)]
13#![allow(internal_features)]
14#![cfg_attr(feature = "in-rust-tree", feature(rustc_private))]
15
16#[cfg(feature = "in-rust-tree")]
17extern crate rustc_driver as _;
18
19mod codec;
20mod framing;
21pub mod legacy_protocol;
22mod process;
23
24use paths::{AbsPath, AbsPathBuf};
25use semver::Version;
26use span::{ErasedFileAstId, FIXUP_ERASED_FILE_AST_ID_MARKER, Span};
27use std::{fmt, io, sync::Arc, time::SystemTime};
28
29pub use crate::codec::Codec;
30use crate::process::ProcMacroServerProcess;
31
32/// The versions of the server protocol
33pub mod version {
34    pub const NO_VERSION_CHECK_VERSION: u32 = 0;
35    pub const VERSION_CHECK_VERSION: u32 = 1;
36    pub const ENCODE_CLOSE_SPAN_VERSION: u32 = 2;
37    pub const HAS_GLOBAL_SPANS: u32 = 3;
38    pub const RUST_ANALYZER_SPAN_SUPPORT: u32 = 4;
39    /// Whether literals encode their kind as an additional u32 field and idents their rawness as a u32 field.
40    pub const EXTENDED_LEAF_DATA: u32 = 5;
41    pub const HASHED_AST_ID: u32 = 6;
42
43    /// Current API version of the proc-macro protocol.
44    pub const CURRENT_API_VERSION: u32 = HASHED_AST_ID;
45}
46
47/// Represents different kinds of procedural macros that can be expanded by the external server.
48#[derive(Copy, Clone, Eq, PartialEq, Debug, serde_derive::Serialize, serde_derive::Deserialize)]
49pub enum ProcMacroKind {
50    /// A macro that derives implementations for a struct or enum.
51    CustomDerive,
52    /// An attribute-like procedural macro.
53    Attr,
54    // This used to be called FuncLike, so that's what the server expects currently.
55    #[serde(alias = "Bang")]
56    #[serde(rename(serialize = "FuncLike", deserialize = "FuncLike"))]
57    Bang,
58}
59
60/// A handle to an external process which load dylibs with macros (.so or .dll)
61/// and runs actual macro expansion functions.
62#[derive(Debug)]
63pub struct ProcMacroClient {
64    /// Currently, the proc macro process expands all procedural macros sequentially.
65    ///
66    /// That means that concurrent salsa requests may block each other when expanding proc macros,
67    /// which is unfortunate, but simple and good enough for the time being.
68    process: Arc<ProcMacroServerProcess>,
69    path: AbsPathBuf,
70}
71
72/// Represents a dynamically loaded library containing procedural macros.
73pub struct MacroDylib {
74    path: AbsPathBuf,
75}
76
77impl MacroDylib {
78    /// Creates a new MacroDylib instance with the given path.
79    pub fn new(path: AbsPathBuf) -> MacroDylib {
80        MacroDylib { path }
81    }
82}
83
84/// A handle to a specific proc-macro (a `#[proc_macro]` annotated function).
85///
86/// It exists within the context of a specific proc-macro server -- currently
87/// we share a single expander process for all macros within a workspace.
88#[derive(Debug, Clone)]
89pub struct ProcMacro {
90    process: Arc<ProcMacroServerProcess>,
91    dylib_path: Arc<AbsPathBuf>,
92    name: Box<str>,
93    kind: ProcMacroKind,
94    dylib_last_modified: Option<SystemTime>,
95}
96
97impl Eq for ProcMacro {}
98impl PartialEq for ProcMacro {
99    fn eq(&self, other: &Self) -> bool {
100        self.name == other.name
101            && self.kind == other.kind
102            && self.dylib_path == other.dylib_path
103            && self.dylib_last_modified == other.dylib_last_modified
104            && Arc::ptr_eq(&self.process, &other.process)
105    }
106}
107
108/// Represents errors encountered when communicating with the proc-macro server.
109#[derive(Clone, Debug)]
110pub struct ServerError {
111    pub message: String,
112    pub io: Option<Arc<io::Error>>,
113}
114
115impl fmt::Display for ServerError {
116    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
117        self.message.fmt(f)?;
118        if let Some(io) = &self.io {
119            f.write_str(": ")?;
120            io.fmt(f)?;
121        }
122        Ok(())
123    }
124}
125
126impl ProcMacroClient {
127    /// Spawns an external process as the proc macro server and returns a client connected to it.
128    pub fn spawn<'a>(
129        process_path: &AbsPath,
130        env: impl IntoIterator<
131            Item = (impl AsRef<std::ffi::OsStr>, &'a Option<impl 'a + AsRef<std::ffi::OsStr>>),
132        > + Clone,
133        version: Option<&Version>,
134    ) -> io::Result<ProcMacroClient> {
135        let process = ProcMacroServerProcess::run(process_path, env, version)?;
136        Ok(ProcMacroClient { process: Arc::new(process), path: process_path.to_owned() })
137    }
138
139    /// Returns the absolute path to the proc-macro server.
140    pub fn server_path(&self) -> &AbsPath {
141        &self.path
142    }
143
144    /// Loads a proc-macro dylib into the server process returning a list of `ProcMacro`s loaded.
145    pub fn load_dylib(&self, dylib: MacroDylib) -> Result<Vec<ProcMacro>, ServerError> {
146        let _p = tracing::info_span!("ProcMacroServer::load_dylib").entered();
147        let macros = self.process.find_proc_macros(&dylib.path)?;
148
149        let dylib_path = Arc::new(dylib.path);
150        let dylib_last_modified = std::fs::metadata(dylib_path.as_path())
151            .ok()
152            .and_then(|metadata| metadata.modified().ok());
153        match macros {
154            Ok(macros) => Ok(macros
155                .into_iter()
156                .map(|(name, kind)| ProcMacro {
157                    process: self.process.clone(),
158                    name: name.into(),
159                    kind,
160                    dylib_path: dylib_path.clone(),
161                    dylib_last_modified,
162                })
163                .collect()),
164            Err(message) => Err(ServerError { message, io: None }),
165        }
166    }
167
168    /// Checks if the proc-macro server has exited.
169    pub fn exited(&self) -> Option<&ServerError> {
170        self.process.exited()
171    }
172}
173
174impl ProcMacro {
175    /// Returns the name of the procedural macro.
176    pub fn name(&self) -> &str {
177        &self.name
178    }
179
180    /// Returns the type of procedural macro.
181    pub fn kind(&self) -> ProcMacroKind {
182        self.kind
183    }
184
185    fn needs_fixup_change(&self) -> bool {
186        let version = self.process.version();
187        (version::RUST_ANALYZER_SPAN_SUPPORT..version::HASHED_AST_ID).contains(&version)
188    }
189
190    /// On some server versions, the fixup ast id is different than ours. So change it to match.
191    fn change_fixup_to_match_old_server(&self, tt: &mut tt::TopSubtree<Span>) {
192        const OLD_FIXUP_AST_ID: ErasedFileAstId = ErasedFileAstId::from_raw(!0 - 1);
193        let change_ast_id = |ast_id: &mut ErasedFileAstId| {
194            if *ast_id == FIXUP_ERASED_FILE_AST_ID_MARKER {
195                *ast_id = OLD_FIXUP_AST_ID;
196            } else if *ast_id == OLD_FIXUP_AST_ID {
197                // Swap between them, that means no collision plus the change can be reversed by doing itself.
198                *ast_id = FIXUP_ERASED_FILE_AST_ID_MARKER;
199            }
200        };
201
202        for tt in &mut tt.0 {
203            match tt {
204                tt::TokenTree::Leaf(tt::Leaf::Ident(tt::Ident { span, .. }))
205                | tt::TokenTree::Leaf(tt::Leaf::Literal(tt::Literal { span, .. }))
206                | tt::TokenTree::Leaf(tt::Leaf::Punct(tt::Punct { span, .. })) => {
207                    change_ast_id(&mut span.anchor.ast_id);
208                }
209                tt::TokenTree::Subtree(subtree) => {
210                    change_ast_id(&mut subtree.delimiter.open.anchor.ast_id);
211                    change_ast_id(&mut subtree.delimiter.close.anchor.ast_id);
212                }
213            }
214        }
215    }
216
217    /// Expands the procedural macro by sending an expansion request to the server.
218    /// This includes span information and environmental context.
219    pub fn expand(
220        &self,
221        subtree: tt::SubtreeView<'_, Span>,
222        attr: Option<tt::SubtreeView<'_, Span>>,
223        env: Vec<(String, String)>,
224        def_site: Span,
225        call_site: Span,
226        mixed_site: Span,
227        current_dir: String,
228    ) -> Result<Result<tt::TopSubtree<Span>, String>, ServerError> {
229        let (mut subtree, mut attr) = (subtree, attr);
230        let (mut subtree_changed, mut attr_changed);
231        if self.needs_fixup_change() {
232            subtree_changed = tt::TopSubtree::from_subtree(subtree);
233            self.change_fixup_to_match_old_server(&mut subtree_changed);
234            subtree = subtree_changed.view();
235
236            if let Some(attr) = &mut attr {
237                attr_changed = tt::TopSubtree::from_subtree(*attr);
238                self.change_fixup_to_match_old_server(&mut attr_changed);
239                *attr = attr_changed.view();
240            }
241        }
242
243        legacy_protocol::expand(
244            self,
245            subtree,
246            attr,
247            env,
248            def_site,
249            call_site,
250            mixed_site,
251            current_dir,
252        )
253    }
254}
proc_macro_api/lib.rs

proc_macro_api/
lib.rs
