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";