1use std::fs;
4use std::path::PathBuf;
5
6use rustc_data_structures::fx::FxIndexMap;
7use rustc_errors::DiagCtxtHandle;
8use rustc_hir::intravisit::{self, Visitor};
9use rustc_hir::{self as hir};
10use rustc_macros::{Decodable, Encodable};
11use rustc_middle::hir::nested_filter;
12use rustc_middle::ty::{self, TyCtxt};
13use rustc_serialize::opaque::{FileEncoder, MemDecoder};
14use rustc_serialize::{Decodable, Encodable};
15use rustc_session::getopts;
16use rustc_span::def_id::{CrateNum, DefPathHash, LOCAL_CRATE};
17use rustc_span::edition::Edition;
18use rustc_span::{BytePos, FileName, SourceFile};
19use tracing::{debug, trace, warn};
20
21use crate::formats::renderer::FormatRenderer;
22use crate::html::render::Context;
23use crate::{clean, config, formats};
24
25#[derive(Debug, Clone)]
26pub(crate) struct ScrapeExamplesOptions {
27 output_path: PathBuf,
28 target_crates: Vec<String>,
29 pub(crate) scrape_tests: bool,
30}
31
32impl ScrapeExamplesOptions {
33 pub(crate) fn new(matches: &getopts::Matches, dcx: DiagCtxtHandle<'_>) -> Option<Self> {
34 let output_path = matches.opt_str("scrape-examples-output-path");
35 let target_crates = matches.opt_strs("scrape-examples-target-crate");
36 let scrape_tests = matches.opt_present("scrape-tests");
37 match (output_path, !target_crates.is_empty(), scrape_tests) {
38 (Some(output_path), true, _) => Some(ScrapeExamplesOptions {
39 output_path: PathBuf::from(output_path),
40 target_crates,
41 scrape_tests,
42 }),
43 (Some(_), false, _) | (None, true, _) => {
44 dcx.fatal(
45 "must use --scrape-examples-output-path and --scrape-examples-target-crate \
46 together",
47 );
48 }
49 (None, false, true) => {
50 dcx.fatal(
51 "must use --scrape-examples-output-path and \
52 --scrape-examples-target-crate with --scrape-tests",
53 );
54 }
55 (None, false, false) => None,
56 }
57 }
58}
59
60#[derive(Encodable, Decodable, Debug, Clone)]
61pub(crate) struct SyntaxRange {
62 pub(crate) byte_span: (u32, u32),
63 pub(crate) line_span: (usize, usize),
64}
65
66impl SyntaxRange {
67 fn new(span: rustc_span::Span, file: &SourceFile) -> Option<Self> {
68 let get_pos = |bytepos: BytePos| file.original_relative_byte_pos(bytepos).0;
69 let get_line = |bytepos: BytePos| file.lookup_line(file.relative_position(bytepos));
70
71 Some(SyntaxRange {
72 byte_span: (get_pos(span.lo()), get_pos(span.hi())),
73 line_span: (get_line(span.lo())?, get_line(span.hi())?),
74 })
75 }
76}
77
78#[derive(Encodable, Decodable, Debug, Clone)]
79pub(crate) struct CallLocation {
80 pub(crate) call_expr: SyntaxRange,
81 pub(crate) call_ident: SyntaxRange,
82 pub(crate) enclosing_item: SyntaxRange,
83}
84
85impl CallLocation {
86 fn new(
87 expr_span: rustc_span::Span,
88 ident_span: rustc_span::Span,
89 enclosing_item_span: rustc_span::Span,
90 source_file: &SourceFile,
91 ) -> Option<Self> {
92 Some(CallLocation {
93 call_expr: SyntaxRange::new(expr_span, source_file)?,
94 call_ident: SyntaxRange::new(ident_span, source_file)?,
95 enclosing_item: SyntaxRange::new(enclosing_item_span, source_file)?,
96 })
97 }
98}
99
100#[derive(Encodable, Decodable, Debug, Clone)]
101pub(crate) struct CallData {
102 pub(crate) locations: Vec<CallLocation>,
103 pub(crate) url: String,
104 pub(crate) display_name: String,
105 pub(crate) edition: Edition,
106 pub(crate) is_bin: bool,
107}
108
109pub(crate) type FnCallLocations = FxIndexMap<PathBuf, CallData>;
110pub(crate) type AllCallLocations = FxIndexMap<DefPathHash, FnCallLocations>;
111
112struct FindCalls<'a, 'tcx> {
114 cx: Context<'tcx>,
115 target_crates: Vec<CrateNum>,
116 calls: &'a mut AllCallLocations,
117 bin_crate: bool,
118}
119
120impl<'a, 'tcx> Visitor<'tcx> for FindCalls<'a, 'tcx>
121where
122 'tcx: 'a,
123{
124 type NestedFilter = nested_filter::OnlyBodies;
125
126 fn maybe_tcx(&mut self) -> Self::MaybeTyCtxt {
127 self.cx.tcx()
128 }
129
130 fn visit_expr(&mut self, ex: &'tcx hir::Expr<'tcx>) {
131 intravisit::walk_expr(self, ex);
132
133 let tcx = self.cx.tcx();
134
135 if tcx.hir_maybe_body_owned_by(ex.hir_id.owner.def_id).is_none() {
139 return;
140 }
141
142 let (ty, call_span, ident_span) = match ex.kind {
144 hir::ExprKind::Call(f, _) => {
145 let types = tcx.typeck(ex.hir_id.owner.def_id);
146
147 if let Some(ty) = types.node_type_opt(f.hir_id) {
148 (ty, ex.span, f.span)
149 } else {
150 trace!("node_type_opt({}) = None", f.hir_id);
151 return;
152 }
153 }
154 hir::ExprKind::MethodCall(path, _, _, call_span) => {
155 let types = tcx.typeck(ex.hir_id.owner.def_id);
156 let Some(def_id) = types.type_dependent_def_id(ex.hir_id) else {
157 trace!("type_dependent_def_id({}) = None", ex.hir_id);
158 return;
159 };
160
161 let ident_span = path.ident.span;
162 (tcx.type_of(def_id).instantiate_identity(), call_span, ident_span)
163 }
164 _ => {
165 return;
166 }
167 };
168
169 if call_span.from_expansion() {
173 trace!("Rejecting expr from macro: {call_span:?}");
174 return;
175 }
176
177 let enclosing_item_span = tcx.hir_span_with_body(tcx.hir_get_parent_item(ex.hir_id).into());
180 if enclosing_item_span.from_expansion() {
181 trace!("Rejecting expr ({call_span:?}) from macro item: {enclosing_item_span:?}");
182 return;
183 }
184
185 if !enclosing_item_span.contains(call_span) {
188 warn!(
189 "Attempted to scrape call at [{call_span:?}] whose enclosing item \
190 [{enclosing_item_span:?}] doesn't contain the span of the call."
191 );
192 return;
193 }
194
195 if !call_span.contains(ident_span) {
197 warn!(
198 "Attempted to scrape call at [{call_span:?}] whose identifier [{ident_span:?}] was \
199 not contained in the span of the call."
200 );
201 return;
202 }
203
204 if let ty::FnDef(def_id, _) = ty.kind() {
206 if self.target_crates.iter().all(|krate| *krate != def_id.krate) {
207 trace!("Rejecting expr from crate not being documented: {call_span:?}");
208 return;
209 }
210
211 let source_map = tcx.sess.source_map();
212 let file = source_map.lookup_char_pos(call_span.lo()).file;
213 let file_path = match file.name.clone() {
214 FileName::Real(real_filename) => real_filename.into_local_path(),
215 _ => None,
216 };
217
218 if let Some(file_path) = file_path {
219 let abs_path = match fs::canonicalize(file_path.clone()) {
220 Ok(abs_path) => abs_path,
221 Err(_) => {
222 trace!("Could not canonicalize file path: {}", file_path.display());
223 return;
224 }
225 };
226
227 let cx = &self.cx;
228 let clean_span = crate::clean::types::Span::new(call_span);
229 let url = match cx.href_from_span(clean_span, false) {
230 Some(url) => url,
231 None => {
232 trace!(
233 "Rejecting expr ({call_span:?}) whose clean span ({clean_span:?}) \
234 cannot be turned into a link"
235 );
236 return;
237 }
238 };
239
240 let mk_call_data = || {
241 let display_name = file_path.display().to_string();
242 let edition = call_span.edition();
243 let is_bin = self.bin_crate;
244
245 CallData { locations: Vec::new(), url, display_name, edition, is_bin }
246 };
247
248 let fn_key = tcx.def_path_hash(*def_id);
249 let fn_entries = self.calls.entry(fn_key).or_default();
250
251 trace!("Including expr: {call_span:?}");
252 let enclosing_item_span =
253 source_map.span_extend_to_prev_char(enclosing_item_span, '\n', false);
254 let location =
255 match CallLocation::new(call_span, ident_span, enclosing_item_span, &file) {
256 Some(location) => location,
257 None => {
258 trace!("Could not get serializable call location for {call_span:?}");
259 return;
260 }
261 };
262 fn_entries.entry(abs_path).or_insert_with(mk_call_data).locations.push(location);
263 }
264 }
265 }
266}
267
268pub(crate) fn run(
269 krate: clean::Crate,
270 mut renderopts: config::RenderOptions,
271 cache: formats::cache::Cache,
272 tcx: TyCtxt<'_>,
273 options: ScrapeExamplesOptions,
274 bin_crate: bool,
275) {
276 let inner = move || -> Result<(), String> {
277 renderopts.no_emit_shared = true;
279 let (cx, _) = Context::init(krate, renderopts, cache, tcx).map_err(|e| e.to_string())?;
280
281 let all_crates = tcx
285 .crates(())
286 .iter()
287 .chain([&LOCAL_CRATE])
288 .map(|crate_num| (crate_num, tcx.crate_name(*crate_num)))
289 .collect::<Vec<_>>();
290 let target_crates = options
291 .target_crates
292 .into_iter()
293 .flat_map(|target| all_crates.iter().filter(move |(_, name)| name.as_str() == target))
294 .map(|(crate_num, _)| **crate_num)
295 .collect::<Vec<_>>();
296
297 debug!("All crates in TyCtxt: {all_crates:?}");
298 debug!("Scrape examples target_crates: {target_crates:?}");
299
300 let mut calls = FxIndexMap::default();
302 let mut finder = FindCalls { calls: &mut calls, cx, target_crates, bin_crate };
303 tcx.hir_visit_all_item_likes_in_crate(&mut finder);
304
305 if tcx.dcx().has_errors().is_some() {
308 return Err(String::from("Compilation failed, aborting rustdoc"));
309 }
310
311 for fn_calls in calls.values_mut() {
313 for file_calls in fn_calls.values_mut() {
314 file_calls.locations.sort_by_key(|loc| loc.call_expr.byte_span.0);
315 }
316 }
317
318 let mut encoder = FileEncoder::new(options.output_path).map_err(|e| e.to_string())?;
320 calls.encode(&mut encoder);
321 encoder.finish().map_err(|(_path, e)| e.to_string())?;
322
323 Ok(())
324 };
325
326 if let Err(e) = inner() {
327 tcx.dcx().fatal(e);
328 }
329}
330
331pub(crate) fn load_call_locations(
334 with_examples: Vec<String>,
335 dcx: DiagCtxtHandle<'_>,
336) -> AllCallLocations {
337 let mut all_calls: AllCallLocations = FxIndexMap::default();
338 for path in with_examples {
339 let bytes = match fs::read(&path) {
340 Ok(bytes) => bytes,
341 Err(e) => dcx.fatal(format!("failed to load examples: {e}")),
342 };
343 let Ok(mut decoder) = MemDecoder::new(&bytes, 0) else {
344 dcx.fatal(format!("Corrupt metadata encountered in {path}"))
345 };
346 let calls = AllCallLocations::decode(&mut decoder);
347
348 for (function, fn_calls) in calls.into_iter() {
349 all_calls.entry(function).or_default().extend(fn_calls.into_iter());
350 }
351 }
352
353 all_calls
354}