rustc_plugin/plugin.rs
1use std::{borrow::Cow, path::PathBuf, process::Command};
2
3use cargo_metadata::camino::Utf8Path;
4use serde::{Serialize, de::DeserializeOwned};
5
6/// Specification of a set of crates.
7pub enum CrateFilter {
8 /// Every crate in the workspace and all transitive dependencies.
9 AllCrates,
10
11 /// Just crates in the workspace.
12 OnlyWorkspace,
13
14 /// Only the crate containing a specific file.
15 CrateContainingFile(PathBuf),
16}
17
18/// Arguments from your plugin to the rustc_plugin framework.
19pub struct RustcPluginArgs<Args> {
20 /// Whatever CLI arguments you want to pass along.
21 pub args: Args,
22
23 /// Which crates you want to run the plugin on.
24 pub filter: CrateFilter,
25}
26
27/// Interface between your plugin and the rustc_plugin framework.
28pub trait RustcPlugin: Sized {
29 /// Command-line arguments passed by the user.
30 type Args: Serialize + DeserializeOwned;
31
32 /// Returns the version of your plugin.
33 ///
34 /// A sensible default is your plugin's Cargo version:
35 ///
36 /// ```ignore
37 /// env!("CARGO_PKG_VERSION").into()
38 /// ```
39 fn version(&self) -> Cow<'static, str>;
40
41 /// Returns the name of your driver binary as it's installed in the filesystem.
42 ///
43 /// Should be just the filename, not the full path.
44 fn driver_name(&self) -> Cow<'static, str>;
45
46 /// Parses and returns the CLI arguments for the plugin.
47 fn args(&self, target_dir: &Utf8Path) -> RustcPluginArgs<Self::Args>;
48
49 /// Optionally modify the `cargo` command that launches rustc.
50 /// For example, you could pass a `--feature` flag here.
51 fn modify_cargo(&self, _cargo: &mut Command, _args: &Self::Args) {}
52
53 /// Executes the plugin with a set of compiler and plugin args.
54 fn run(
55 self,
56 compiler_args: Vec<String>,
57 plugin_args: Self::Args,
58 ) -> rustc_interface::interface::Result<()>;
59}
60
61/// The name of the environment variable shared between the CLI and the driver.
62/// Must not conflict with any other env var used by Cargo.
63pub const PLUGIN_ARGS: &str = "PLUGIN_ARGS";