1 use std::fs::{self, File};
2 use std::io::prelude::*;
3 use std::io::{self, BufReader};
4 use std::path::{Component, Path};
7 use itertools::Itertools;
8 use rustc_data_structures::flock;
9 use rustc_data_structures::fx::{FxHashMap, FxHashSet};
10 use serde::ser::SerializeSeq;
11 use serde::{Serialize, Serializer};
13 use super::{collect_paths_for_type, ensure_trailing_slash, Context, BASIC_KEYWORDS};
14 use crate::clean::Crate;
15 use crate::config::{EmitType, RenderOptions};
16 use crate::docfs::PathError;
17 use crate::error::Error;
18 use crate::html::{layout, static_files};
19 use crate::{try_err, try_none};
21 /// Rustdoc writes out two kinds of shared files:
22 /// - Static files, which are embedded in the rustdoc binary and are written with a
23 /// filename that includes a hash of their contents. These will always have a new
24 /// URL if the contents change, so they are safe to cache with the
25 /// `Cache-Control: immutable` directive. They are written under the static.files/
26 /// directory and are written when --emit-type is empty (default) or contains
27 /// "toolchain-specific". If using the --static-root-path flag, it should point
28 /// to a URL path prefix where each of these filenames can be fetched.
29 /// - Invocation specific files. These are generated based on the crate(s) being
30 /// documented. Their filenames need to be predictable without knowing their
31 /// contents, so they do not include a hash in their filename and are not safe to
32 /// cache with `Cache-Control: immutable`. They include the contents of the
33 /// --resource-suffix flag and are emitted when --emit-type is empty (default)
34 /// or contains "invocation-specific".
35 pub(super) fn write_shared(
39 options: &RenderOptions,
40 ) -> Result<(), Error> {
41 // Write out the shared files. Note that these are shared among all rustdoc
42 // docs placed in the output directory, so this needs to be a synchronized
43 // operation with respect to all other rustdocs running around.
44 let lock_file = cx.dst.join(".lock");
45 let _lock = try_err!(flock::Lock::new(&lock_file, true, true, true), &lock_file);
47 // InvocationSpecific resources should always be dynamic.
48 let write_invocation_specific = |p: &str, make_content: &dyn Fn() -> Result<Vec<u8>, Error>| {
49 let content = make_content()?;
50 if options.emit.is_empty() || options.emit.contains(&EmitType::InvocationSpecific) {
51 let output_filename = static_files::suffix_path(p, &cx.shared.resource_suffix);
52 cx.shared.fs.write(cx.dst.join(output_filename), content)
60 .create_dir_all(cx.dst.join("static.files"))
61 .map_err(|e| PathError::new(e, "static.files"))?;
63 // Handle added third-party themes
64 for entry in &cx.shared.style_files {
65 let theme = entry.basename()?;
67 try_none!(try_none!(entry.path.extension(), &entry.path).to_str(), &entry.path);
69 // Skip the official themes. They are written below as part of STATIC_FILES_LIST.
70 if matches!(theme.as_str(), "light" | "dark" | "ayu") {
74 let bytes = try_err!(fs::read(&entry.path), &entry.path);
75 let filename = format!("{}{}.{}", theme, cx.shared.resource_suffix, extension);
76 cx.shared.fs.write(cx.dst.join(filename), bytes)?;
79 // When the user adds their own CSS files with --extend-css, we write that as an
80 // invocation-specific file (that is, with a resource suffix).
81 if let Some(ref css) = cx.shared.layout.css_file_extension {
82 let buffer = try_err!(fs::read_to_string(css), css);
83 let path = static_files::suffix_path("theme.css", &cx.shared.resource_suffix);
84 cx.shared.fs.write(cx.dst.join(path), buffer)?;
87 if options.emit.is_empty() || options.emit.contains(&EmitType::Toolchain) {
88 let static_dir = cx.dst.join(Path::new("static.files"));
89 static_files::for_each(|f: &static_files::StaticFile| {
90 let filename = static_dir.join(f.output_filename());
91 cx.shared.fs.write(filename, f.minified())
95 /// Read a file and return all lines that match the `"{crate}":{data},` format,
96 /// and return a tuple `(Vec<DataString>, Vec<CrateNameString>)`.
98 /// This forms the payload of files that look like this:
102 /// "{crate1}":{data},
103 /// "{crate2}":{data}
108 /// The file needs to be formatted so that *only crate data lines start with `"`*.
109 fn collect(path: &Path, krate: &str) -> io::Result<(Vec<String>, Vec<String>)> {
110 let mut ret = Vec::new();
111 let mut krates = Vec::new();
114 let prefix = format!("\"{}\"", krate);
115 for line in BufReader::new(File::open(path)?).lines() {
117 if !line.starts_with('"') {
120 if line.starts_with(&prefix) {
123 if line.ends_with(',') {
124 ret.push(line[..line.len() - 1].to_string());
126 // No comma (it's the case for the last added crate line)
127 ret.push(line.to_string());
131 .find(|s| !s.is_empty())
132 .map(|s| s.to_owned())
133 .unwrap_or_else(String::new),
140 /// Read a file and return all lines that match the <code>"{crate}":{data},\</code> format,
141 /// and return a tuple `(Vec<DataString>, Vec<CrateNameString>)`.
143 /// This forms the payload of files that look like this:
146 /// var data = JSON.parse('{\
147 /// "{crate1}":{data},\
148 /// "{crate2}":{data}\
153 /// The file needs to be formatted so that *only crate data lines start with `"`*.
154 fn collect_json(path: &Path, krate: &str) -> io::Result<(Vec<String>, Vec<String>)> {
155 let mut ret = Vec::new();
156 let mut krates = Vec::new();
159 let prefix = format!("\"{}\"", krate);
160 for line in BufReader::new(File::open(path)?).lines() {
162 if !line.starts_with('"') {
165 if line.starts_with(&prefix) {
168 if line.ends_with(",\\") {
169 ret.push(line[..line.len() - 2].to_string());
171 // Ends with "\\" (it's the case for the last added crate line)
172 ret.push(line[..line.len() - 1].to_string());
176 .find(|s| !s.is_empty())
177 .map(|s| s.to_owned())
178 .unwrap_or_else(String::new),
185 use std::ffi::OsString;
190 children: FxHashMap<OsString, Hierarchy>,
191 elems: FxHashSet<OsString>,
195 fn new(elem: OsString) -> Hierarchy {
196 Hierarchy { elem, children: FxHashMap::default(), elems: FxHashSet::default() }
199 fn to_json_string(&self) -> String {
200 let mut subs: Vec<&Hierarchy> = self.children.values().collect();
201 subs.sort_unstable_by(|a, b| a.elem.cmp(&b.elem));
205 .map(|s| format!("\"{}\"", s.to_str().expect("invalid osstring conversion")))
206 .collect::<Vec<_>>();
207 files.sort_unstable();
208 let subs = subs.iter().map(|s| s.to_json_string()).collect::<Vec<_>>().join(",");
209 let dirs = if subs.is_empty() && files.is_empty() {
212 format!(",[{}]", subs)
214 let files = files.join(",");
215 let files = if files.is_empty() { String::new() } else { format!(",[{}]", files) };
217 "[\"{name}\"{dirs}{files}]",
218 name = self.elem.to_str().expect("invalid osstring conversion"),
225 if cx.include_sources {
226 let mut hierarchy = Hierarchy::new(OsString::new());
231 .filter_map(|p| p.0.strip_prefix(&cx.shared.src_root).ok())
233 let mut h = &mut hierarchy;
234 let mut elems = source
236 .filter_map(|s| match s {
237 Component::Normal(s) => Some(s.to_owned()),
242 let cur_elem = elems.next().expect("empty file path");
243 if elems.peek().is_none() {
244 h.elems.insert(cur_elem);
247 let e = cur_elem.clone();
248 h = h.children.entry(cur_elem.clone()).or_insert_with(|| Hierarchy::new(e));
253 let dst = cx.dst.join(&format!("source-files{}.js", cx.shared.resource_suffix));
254 let make_sources = || {
255 let (mut all_sources, _krates) =
256 try_err!(collect_json(&dst, krate.name(cx.tcx()).as_str()), &dst);
257 all_sources.push(format!(
259 &krate.name(cx.tcx()),
262 // All these `replace` calls are because we have to go through JS string for JSON content.
263 .replace('\\', r"\\")
264 .replace('\'', r"\'")
265 // We need to escape double quotes for the JSON.
266 .replace("\\\"", "\\\\\"")
269 let mut v = String::from("var sourcesIndex = JSON.parse('{\\\n");
270 v.push_str(&all_sources.join(",\\\n"));
271 v.push_str("\\\n}');\ncreateSourceSidebar();\n");
274 write_invocation_specific("source-files.js", &make_sources)?;
277 // Update the search index and crate list.
278 let dst = cx.dst.join(&format!("search-index{}.js", cx.shared.resource_suffix));
279 let (mut all_indexes, mut krates) =
280 try_err!(collect_json(&dst, krate.name(cx.tcx()).as_str()), &dst);
281 all_indexes.push(search_index);
282 krates.push(krate.name(cx.tcx()).to_string());
285 // Sort the indexes by crate so the file will be generated identically even
286 // with rustdoc running in parallel.
288 write_invocation_specific("search-index.js", &|| {
289 let mut v = String::from("var searchIndex = JSON.parse('{\\\n");
290 v.push_str(&all_indexes.join(",\\\n"));
294 if (typeof window !== 'undefined' && window.initSearch) {window.initSearch(searchIndex)};
295 if (typeof exports !== 'undefined') {exports.searchIndex = searchIndex};
301 write_invocation_specific("crates.js", &|| {
302 let krates = krates.iter().map(|k| format!("\"{}\"", k)).join(",");
303 Ok(format!("window.ALL_CRATES = [{}];", krates).into_bytes())
306 if options.enable_index_page {
307 if let Some(index_page) = options.index_page.clone() {
308 let mut md_opts = options.clone();
309 md_opts.output = cx.dst.clone();
310 md_opts.external_html = (*cx.shared).layout.external_html.clone();
312 crate::markdown::render(&index_page, md_opts, cx.shared.edition())
313 .map_err(|e| Error::new(e, &index_page))?;
315 let shared = Rc::clone(&cx.shared);
316 let dst = cx.dst.join("index.html");
317 let page = layout::Page {
318 title: "Index of crates",
321 static_root_path: shared.static_root_path.as_deref(),
322 description: "List of crates",
323 keywords: BASIC_KEYWORDS,
324 resource_suffix: &shared.resource_suffix,
327 let content = format!(
328 "<h1 class=\"fqn\">List of all crates</h1><ul class=\"all-items\">{}</ul>",
333 "<li><a href=\"{}index.html\">{}</a></li>",
334 ensure_trailing_slash(s),
340 let v = layout::render(&shared.layout, &page, "", content, &shared.style_files);
341 shared.fs.write(dst, v)?;
345 // Update the list of all implementors for traits
346 let dst = cx.dst.join("implementors");
347 let cache = cx.cache();
348 for (&did, imps) in &cache.implementors {
349 // Private modules can leak through to this phase of rustdoc, which
350 // could contain implementations for otherwise private types. In some
351 // rare cases we could find an implementation for an item which wasn't
352 // indexed, so we just skip this step in that case.
354 // FIXME: this is a vague explanation for why this can't be a `get`, in
355 // theory it should be...
356 let (remote_path, remote_item_type) = match cache.exact_paths.get(&did) {
357 Some(p) => match cache.paths.get(&did).or_else(|| cache.external_paths.get(&did)) {
358 Some((_, t)) => (p, t),
361 None => match cache.external_paths.get(&did) {
362 Some((p, t)) => (p, t),
373 impl Serialize for Implementor {
374 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
378 let mut seq = serializer.serialize_seq(None)?;
379 seq.serialize_element(&self.text)?;
381 seq.serialize_element(&1)?;
382 seq.serialize_element(&self.types)?;
388 let implementors = imps
391 // If the trait and implementation are in the same crate, then
392 // there's no need to emit information about it (there's inlining
393 // going on). If they're in different crates then the crate defining
394 // the trait will be interested in our implementation.
396 // If the implementation is from another crate then that crate
398 if imp.impl_item.item_id.krate() == did.krate || !imp.impl_item.item_id.is_local() {
402 text: imp.inner_impl().print(false, cx).to_string(),
403 synthetic: imp.inner_impl().kind.is_auto(),
404 types: collect_paths_for_type(imp.inner_impl().for_.clone(), cache),
408 .collect::<Vec<_>>();
410 // Only create a js file if we have impls to add to it. If the trait is
411 // documented locally though we always create the file to avoid dead
413 if implementors.is_empty() && !cache.paths.contains_key(&did) {
417 let implementors = format!(
419 krate.name(cx.tcx()),
420 serde_json::to_string(&implementors).expect("failed serde conversion"),
423 let mut mydst = dst.clone();
424 for part in &remote_path[..remote_path.len() - 1] {
425 mydst.push(part.to_string());
427 cx.shared.ensure_dir(&mydst)?;
428 mydst.push(&format!("{}.{}.js", remote_item_type, remote_path[remote_path.len() - 1]));
430 let (mut all_implementors, _) =
431 try_err!(collect(&mydst, krate.name(cx.tcx()).as_str()), &mydst);
432 all_implementors.push(implementors);
433 // Sort the implementors by crate so the file will be generated
434 // identically even with rustdoc running in parallel.
435 all_implementors.sort();
437 let mut v = String::from("(function() {var implementors = {\n");
438 v.push_str(&all_implementors.join(",\n"));
441 "if (window.register_implementors) {\
442 window.register_implementors(implementors);\
444 window.pending_implementors = implementors;\
448 cx.shared.fs.write(mydst, v)?;