rustup_toolchain/
lib.rs

1//! Utilities for working with `rustup` toolchains.
2//!
3//! # Ensuring a toolchain is installed
4//!
5//! This checks if a toolchain is installed, and installs it if not.
6//!
7//! ```no_run
8//! rustup_toolchain::ensure_installed("nightly").unwrap();
9//! ```
10
11#[derive(thiserror::Error, Debug)]
12#[non_exhaustive]
13/// Enumerates all errors that can currently occur within this crate.
14pub enum Error {
15    /// Some kind of IO error occurred.
16    #[error(transparent)]
17    IoError(#[from] std::io::Error),
18
19    /// The lock used to work around <https://github.com/rust-lang/rustup/issues/988> has been poisoned
20    #[error("The lock used to work around https://github.com/rust-lang/rustup/issues/988 has been poisoned")]
21    StdSyncPoisonError,
22
23    /// `rustup toolchain install ...` failed for some reason
24    #[error("`rustup toolchain install ...` failed for some reason")]
25    RustupToolchainInstallError,
26}
27
28/// Shorthand for [`std::result::Result<T, rustup_toolchain::Error>`].
29pub type Result<T> = std::result::Result<T, Error>;
30
31/// As a workaround for [Rustup (including proxies) is not safe for concurrent
32/// use](https://github.com/rust-lang/rustup/issues/988) we keep a per-process
33/// global lock.
34static RUSTUP_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());
35
36/// Installs a toolchain if it is not already installed.
37///
38/// As a workaround for [Rustup (including proxies) is not safe for concurrent
39/// use](https://github.com/rust-lang/rustup/issues/988) this function is
40/// protected by a process-global lock. If you use multiple processes, you need
41/// to prevent concurrent `rustup` usage yourself.
42///
43/// # Errors
44///
45/// If `rustup` is not installed on your system, for example.
46pub fn install(toolchain: impl AsRef<str>) -> Result<()> {
47    // The reason we check if the toolchain is installed rather than always
48    // doing `rustup install toolchain` is because otherwise there will be noisy
49    // "already installed" output from `rustup install toolchain`.
50    if !is_installed(toolchain.as_ref())? {
51        run_rustup_install(toolchain)?;
52    }
53
54    Ok(())
55}
56
57/// Deprecated
58#[deprecated(since = "0.1.4", note = "Renamed to `install()` for brevity.")]
59pub fn ensure_installed(toolchain: &str) -> Result<()> {
60    install(toolchain)
61}
62
63/// Check if a toolchain is installed.
64///
65/// As a workaround [Rustup (including proxies) is not safe for concurrent
66/// use](https://github.com/rust-lang/rustup/issues/988) this function is
67/// protected by a process-global lock. If you use multiple processes, you need
68/// to prevent concurrent `rustup` usage yourself.
69///
70/// # Errors
71///
72/// If `rustup` is not installed on your system, for example.
73pub fn is_installed(toolchain: &str) -> Result<bool> {
74    let _guard = RUSTUP_MUTEX.lock().map_err(|_| Error::StdSyncPoisonError)?;
75
76    Ok(std::process::Command::new("rustup")
77        .arg("run")
78        .arg(toolchain)
79        .arg("cargo")
80        .arg("--version")
81        .stdout(std::process::Stdio::null())
82        .stderr(std::process::Stdio::null())
83        .status()?
84        .success())
85}
86
87fn run_rustup_install(toolchain: impl AsRef<str>) -> Result<()> {
88    let _guard = RUSTUP_MUTEX.lock().map_err(|_| Error::StdSyncPoisonError)?;
89
90    let status = std::process::Command::new("rustup")
91        .arg("toolchain")
92        .arg("install")
93        .arg("--no-self-update")
94        .arg("--profile")
95        .arg("minimal")
96        .arg(toolchain.as_ref())
97        .status()?;
98
99    if status.success() {
100        Ok(())
101    } else {
102        Err(Error::RustupToolchainInstallError)
103    }
104}
rustup_toolchain/lib.rs

rustup_toolchain/
lib.rs
