run_make_support/external_deps/
rustdoc.rs

1use std::ffi::OsStr;
2use std::path::Path;
3
4use crate::command::Command;
5use crate::env::env_var;
6use crate::util::set_host_compiler_dylib_path;
7
8/// Construct a new `rustdoc` invocation.
9#[track_caller]
10pub fn rustdoc() -> Rustdoc {
11    Rustdoc::new()
12}
13
14#[derive(Debug)]
15#[must_use]
16pub struct Rustdoc {
17    cmd: Command,
18}
19
20crate::macros::impl_common_helpers!(Rustdoc);
21
22#[track_caller]
23fn setup_common() -> Command {
24    let rustdoc = env_var("RUSTDOC");
25    let mut cmd = Command::new(rustdoc);
26    set_host_compiler_dylib_path(&mut cmd);
27    cmd
28}
29
30impl Rustdoc {
31    /// Construct a bare `rustdoc` invocation.
32    #[track_caller]
33    pub fn new() -> Self {
34        let cmd = setup_common();
35        Self { cmd }
36    }
37
38    /// Specify where an external library is located.
39    pub fn extern_<P: AsRef<Path>>(&mut self, crate_name: &str, path: P) -> &mut Self {
40        assert!(
41            !crate_name.contains(|c: char| c.is_whitespace() || c == '\\' || c == '/'),
42            "crate name cannot contain whitespace or path separators"
43        );
44
45        let path = path.as_ref().to_string_lossy();
46
47        self.cmd.arg("--extern");
48        self.cmd.arg(format!("{crate_name}={path}"));
49
50        self
51    }
52
53    /// Specify path to the input file.
54    pub fn input<P: AsRef<Path>>(&mut self, path: P) -> &mut Self {
55        self.cmd.arg(path.as_ref());
56        self
57    }
58
59    /// Specify output directory.
60    #[doc(alias = "output")]
61    pub fn out_dir<P: AsRef<Path>>(&mut self, path: P) -> &mut Self {
62        self.cmd.arg("--out-dir").arg(path.as_ref());
63        self
64    }
65
66    /// Given a `path`, pass `@{path}` to `rustdoc` as an
67    /// [arg file](https://doc.rust-lang.org/rustdoc/command-line-arguments.html#path-load-command-line-flags-from-a-path).
68    pub fn arg_file<P: AsRef<Path>>(&mut self, path: P) -> &mut Self {
69        self.cmd.arg(format!("@{}", path.as_ref().display()));
70        self
71    }
72
73    /// Specify a stdin input buffer.
74    pub fn stdin_buf<I: AsRef<[u8]>>(&mut self, input: I) -> &mut Self {
75        self.cmd.stdin_buf(input);
76        self
77    }
78
79    /// Specify the edition year.
80    pub fn edition(&mut self, edition: &str) -> &mut Self {
81        self.cmd.arg("--edition");
82        self.cmd.arg(edition);
83        self
84    }
85
86    /// Specify the target triple, or a path to a custom target json spec file.
87    pub fn target<S: AsRef<str>>(&mut self, target: S) -> &mut Self {
88        let target = target.as_ref();
89        self.cmd.arg(format!("--target={target}"));
90        self
91    }
92
93    /// Specify the crate type.
94    pub fn crate_type(&mut self, crate_type: &str) -> &mut Self {
95        self.cmd.arg("--crate-type");
96        self.cmd.arg(crate_type);
97        self
98    }
99
100    /// Specify the crate name.
101    pub fn crate_name<S: AsRef<OsStr>>(&mut self, name: S) -> &mut Self {
102        self.cmd.arg("--crate-name");
103        self.cmd.arg(name.as_ref());
104        self
105    }
106
107    /// Add a directory to the library search path. It corresponds to the `-L`
108    /// rustdoc option.
109    pub fn library_search_path<P: AsRef<Path>>(&mut self, path: P) -> &mut Self {
110        self.cmd.arg("-L");
111        self.cmd.arg(path.as_ref());
112        self
113    }
114
115    /// Specify the output format.
116    pub fn output_format(&mut self, format: &str) -> &mut Self {
117        self.cmd.arg("--output-format");
118        self.cmd.arg(format);
119        self
120    }
121
122    /// Specify type(s) of output files to generate.
123    pub fn emit<S: AsRef<str>>(&mut self, kinds: S) -> &mut Self {
124        let kinds = kinds.as_ref();
125        self.cmd.arg(format!("--emit={kinds}"));
126        self
127    }
128}