rustc_plugin/
plugin.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
use std::{borrow::Cow, hash::Hasher, path::PathBuf, process::Command};

use cargo_metadata::camino::Utf8Path;
use rustc_tools_util::VersionInfo;
use serde::{de::DeserializeOwned, Serialize};

/// Specification of a set of crates.
pub enum CrateFilter {
  /// Every crate in the workspace and all transitive dependencies.
  AllCrates,

  /// Just crates in the workspace.
  OnlyWorkspace,

  /// Only the crate containing a specific file.
  CrateContainingFile(PathBuf),
}

/// Arguments from your plugin to the rustc_plugin framework.
pub struct RustcPluginArgs<Args> {
  /// Whatever CLI arguments you want to pass along.
  pub args: Args,

  /// Which crates you want to run the plugin on.
  pub filter: CrateFilter,
}

/// Interface between your plugin and the rustc_plugin framework.
pub trait RustcPlugin: Sized {
  /// Command-line arguments passed by the user.
  type Args: Serialize + DeserializeOwned;

  /// Returns the version of your plugin.
  ///
  /// A sensible default is your plugin's Cargo version:
  ///
  /// ```ignore
  /// env!("CARGO_PKG_VERSION").into()
  /// ```
  fn version(&self) -> Cow<'static, str>;

  fn reported_driver_version(&self) -> Cow<'static, str> {
    Cow::Owned(format!("{}", rustc_tools_util::get_version_info!()))
  }

  /// Returns the name of your driver binary as it's installed in the filesystem.
  ///
  /// Should be just the filename, not the full path.
  fn driver_name(&self) -> Cow<'static, str>;

  /// Parses and returns the CLI arguments for the plugin.
  fn args(&self, target_dir: &Utf8Path) -> RustcPluginArgs<Self::Args>;

  fn hash_config(&self, _args: &Self::Args, _hasher: &mut impl Hasher) {}

  /// Optionally modify the `cargo` command that launches rustc.
  /// For example, you could pass a `--feature` flag here.
  fn modify_cargo(&self, _cargo: &mut Command, _args: &Self::Args) {}

  /// Executes the plugin with a set of compiler and plugin args.
  fn run(
    self,
    compiler_args: Vec<String>,
    plugin_args: Self::Args,
  ) -> rustc_interface::interface::Result<()>;
}

/// The name of the environment variable shared between the CLI and the driver.
/// Must not conflict with any other env var used by Cargo.
pub const PLUGIN_ARGS: &str = "PLUGIN_ARGS";