src/librustdoc/html/render/write_shared.rs

   1 use std::ffi::OsStr;
   2 use std::fmt::Write;
   3 use std::fs::{self, File};
   4 use std::io::prelude::*;
   5 use std::io::{self, BufReader};
   6 use std::lazy::SyncLazy as Lazy;
   7 use std::path::{Component, Path, PathBuf};
   8
   9 use itertools::Itertools;
  10 use rustc_data_structures::flock;
  11 use rustc_data_structures::fx::{FxHashMap, FxHashSet};
  12 use serde::Serialize;
  13
  14 use super::{collect_paths_for_type, ensure_trailing_slash, Context, BASIC_KEYWORDS};
  15 use crate::clean::Crate;
  16 use crate::config::{EmitType, RenderOptions};
  17 use crate::docfs::PathError;
  18 use crate::error::Error;
  19 use crate::html::{layout, static_files};
  20
  21 static FILES_UNVERSIONED: Lazy<FxHashMap<&str, &[u8]>> = Lazy::new(|| {
  22     map! {
  23         "FiraSans-Regular.woff2" => static_files::fira_sans::REGULAR2,
  24         "FiraSans-Medium.woff2" => static_files::fira_sans::MEDIUM2,
  25         "FiraSans-Regular.woff" => static_files::fira_sans::REGULAR,
  26         "FiraSans-Medium.woff" => static_files::fira_sans::MEDIUM,
  27         "FiraSans-LICENSE.txt" => static_files::fira_sans::LICENSE,
  28         "SourceSerif4-Regular.ttf.woff" => static_files::source_serif_4::REGULAR,
  29         "SourceSerif4-Bold.ttf.woff" => static_files::source_serif_4::BOLD,
  30         "SourceSerif4-It.ttf.woff" => static_files::source_serif_4::ITALIC,
  31         "SourceSerif4-LICENSE.md" => static_files::source_serif_4::LICENSE,
  32         "SourceCodePro-Regular.ttf.woff" => static_files::source_code_pro::REGULAR,
  33         "SourceCodePro-Semibold.ttf.woff" => static_files::source_code_pro::SEMIBOLD,
  34         "SourceCodePro-It.ttf.woff" => static_files::source_code_pro::ITALIC,
  35         "SourceCodePro-LICENSE.txt" => static_files::source_code_pro::LICENSE,
  36         "noto-sans-kr-v13-korean-regular.woff" => static_files::noto_sans_kr::REGULAR,
  37         "noto-sans-kr-v13-korean-regular-LICENSE.txt" => static_files::noto_sans_kr::LICENSE,
  38         "LICENSE-MIT.txt" => static_files::LICENSE_MIT,
  39         "LICENSE-APACHE.txt" => static_files::LICENSE_APACHE,
  40         "COPYRIGHT.txt" => static_files::COPYRIGHT,
  41     }
  42 });
  43
  44 enum SharedResource<'a> {
  45     /// This file will never change, no matter what toolchain is used to build it.
  46     ///
  47     /// It does not have a resource suffix.
  48     Unversioned { name: &'static str },
  49     /// This file may change depending on the toolchain.
  50     ///
  51     /// It has a resource suffix.
  52     ToolchainSpecific { basename: &'static str },
  53     /// This file may change for any crate within a build, or based on the CLI arguments.
  54     ///
  55     /// This differs from normal invocation-specific files because it has a resource suffix.
  56     InvocationSpecific { basename: &'a str },
  57 }
  58
  59 impl SharedResource<'_> {
  60     fn extension(&self) -> Option<&OsStr> {
  61         use SharedResource::*;
  62         match self {
  63             Unversioned { name }
  64             | ToolchainSpecific { basename: name }
  65             | InvocationSpecific { basename: name } => Path::new(name).extension(),
  66         }
  67     }
  68
  69     fn path(&self, cx: &Context<'_>) -> PathBuf {
  70         match self {
  71             SharedResource::Unversioned { name } => cx.dst.join(name),
  72             SharedResource::ToolchainSpecific { basename } => cx.suffix_path(basename),
  73             SharedResource::InvocationSpecific { basename } => cx.suffix_path(basename),
  74         }
  75     }
  76
  77     fn should_emit(&self, emit: &[EmitType]) -> bool {
  78         if emit.is_empty() {
  79             return true;
  80         }
  81         let kind = match self {
  82             SharedResource::Unversioned { .. } => EmitType::Unversioned,
  83             SharedResource::ToolchainSpecific { .. } => EmitType::Toolchain,
  84             SharedResource::InvocationSpecific { .. } => EmitType::InvocationSpecific,
  85         };
  86         emit.contains(&kind)
  87     }
  88 }
  89
  90 impl Context<'_> {
  91     fn suffix_path(&self, filename: &str) -> PathBuf {
  92         // We use splitn vs Path::extension here because we might get a filename
  93         // like `style.min.css` and we want to process that into
  94         // `style-suffix.min.css`.  Path::extension would just return `css`
  95         // which would result in `style.min-suffix.css` which isn't what we
  96         // want.
  97         let (base, ext) = filename.split_once('.').unwrap();
  98         let filename = format!("{}{}.{}", base, self.shared.resource_suffix, ext);
  99         self.dst.join(&filename)
 100     }
 101
 102     fn write_shared<C: AsRef<[u8]>>(
 103         &self,
 104         resource: SharedResource<'_>,
 105         contents: C,
 106         emit: &[EmitType],
 107     ) -> Result<(), Error> {
 108         if resource.should_emit(emit) {
 109             self.shared.fs.write(resource.path(self), contents)
 110         } else {
 111             Ok(())
 112         }
 113     }
 114
 115     fn write_minify(
 116         &self,
 117         resource: SharedResource<'_>,
 118         contents: &str,
 119         minify: bool,
 120         emit: &[EmitType],
 121     ) -> Result<(), Error> {
 122         let tmp;
 123         let contents = if minify {
 124             tmp = if resource.extension() == Some(&OsStr::new("css")) {
 125                 minifier::css::minify(contents).map_err(|e| {
 126                     Error::new(format!("failed to minify CSS file: {}", e), resource.path(self))
 127                 })?
 128             } else {
 129                 minifier::js::minify(contents)
 130             };
 131             tmp.as_bytes()
 132         } else {
 133             contents.as_bytes()
 134         };
 135
 136         self.write_shared(resource, contents, emit)
 137     }
 138 }
 139
 140 pub(super) fn write_shared(
 141     cx: &Context<'_>,
 142     krate: &Crate,
 143     search_index: String,
 144     options: &RenderOptions,
 145 ) -> Result<(), Error> {
 146     // Write out the shared files. Note that these are shared among all rustdoc
 147     // docs placed in the output directory, so this needs to be a synchronized
 148     // operation with respect to all other rustdocs running around.
 149     let lock_file = cx.dst.join(".lock");
 150     let _lock = try_err!(flock::Lock::new(&lock_file, true, true, true), &lock_file);
 151
 152     // The weird `: &_` is to work around a borrowck bug: https://github.com/rust-lang/rust/issues/41078#issuecomment-293646723
 153     let write_minify = |p, c: &_| {
 154         cx.write_minify(
 155             SharedResource::ToolchainSpecific { basename: p },
 156             c,
 157             options.enable_minification,
 158             &options.emit,
 159         )
 160     };
 161     // Toolchain resources should never be dynamic.
 162     let write_toolchain = |p: &'static _, c: &'static _| {
 163         cx.write_shared(SharedResource::ToolchainSpecific { basename: p }, c, &options.emit)
 164     };
 165
 166     // Crate resources should always be dynamic.
 167     let write_crate = |p: &_, make_content: &dyn Fn() -> Result<Vec<u8>, Error>| {
 168         let content = make_content()?;
 169         cx.write_shared(SharedResource::InvocationSpecific { basename: p }, content, &options.emit)
 170     };
 171
 172     // Add all the static files. These may already exist, but we just
 173     // overwrite them anyway to make sure that they're fresh and up-to-date.
 174     write_minify("rustdoc.css", static_files::RUSTDOC_CSS)?;
 175     write_minify("settings.css", static_files::SETTINGS_CSS)?;
 176     write_minify("noscript.css", static_files::NOSCRIPT_CSS)?;
 177
 178     // To avoid "light.css" to be overwritten, we'll first run over the received themes and only
 179     // then we'll run over the "official" styles.
 180     let mut themes: FxHashSet<String> = FxHashSet::default();
 181
 182     for entry in &cx.shared.style_files {
 183         let theme = try_none!(try_none!(entry.path.file_stem(), &entry.path).to_str(), &entry.path);
 184         let extension =
 185             try_none!(try_none!(entry.path.extension(), &entry.path).to_str(), &entry.path);
 186
 187         // Handle the official themes
 188         match theme {
 189             "light" => write_minify("light.css", static_files::themes::LIGHT)?,
 190             "dark" => write_minify("dark.css", static_files::themes::DARK)?,
 191             "ayu" => write_minify("ayu.css", static_files::themes::AYU)?,
 192             _ => {
 193                 // Handle added third-party themes
 194                 let filename = format!("{}.{}", theme, extension);
 195                 write_crate(&filename, &|| Ok(try_err!(fs::read(&entry.path), &entry.path)))?;
 196             }
 197         };
 198
 199         themes.insert(theme.to_owned());
 200     }
 201
 202     if (*cx.shared).layout.logo.is_empty() {
 203         write_toolchain("rust-logo.png", static_files::RUST_LOGO)?;
 204     }
 205     if (*cx.shared).layout.favicon.is_empty() {
 206         write_toolchain("favicon.svg", static_files::RUST_FAVICON_SVG)?;
 207         write_toolchain("favicon-16x16.png", static_files::RUST_FAVICON_PNG_16)?;
 208         write_toolchain("favicon-32x32.png", static_files::RUST_FAVICON_PNG_32)?;
 209     }
 210     write_toolchain("brush.svg", static_files::BRUSH_SVG)?;
 211     write_toolchain("wheel.svg", static_files::WHEEL_SVG)?;
 212     write_toolchain("clipboard.svg", static_files::CLIPBOARD_SVG)?;
 213     write_toolchain("down-arrow.svg", static_files::DOWN_ARROW_SVG)?;
 214
 215     let mut themes: Vec<&String> = themes.iter().collect();
 216     themes.sort();
 217
 218     // FIXME: this should probably not be a toolchain file since it depends on `--theme`.
 219     // But it seems a shame to copy it over and over when it's almost always the same.
 220     // Maybe we can change the representation to move this out of main.js?
 221     write_minify(
 222         "main.js",
 223         &static_files::MAIN_JS.replace(
 224             "/* INSERT THEMES HERE */",
 225             &format!(" = {}", serde_json::to_string(&themes).unwrap()),
 226         ),
 227     )?;
 228     write_minify("search.js", static_files::SEARCH_JS)?;
 229     write_minify("settings.js", static_files::SETTINGS_JS)?;
 230
 231     if cx.shared.include_sources {
 232         write_minify("source-script.js", static_files::sidebar::SOURCE_SCRIPT)?;
 233     }
 234
 235     {
 236         write_minify(
 237             "storage.js",
 238             &format!(
 239                 "var resourcesSuffix = \"{}\";{}",
 240                 cx.shared.resource_suffix,
 241                 static_files::STORAGE_JS
 242             ),
 243         )?;
 244     }
 245
 246     if let Some(ref css) = cx.shared.layout.css_file_extension {
 247         let buffer = try_err!(fs::read_to_string(css), css);
 248         // This varies based on the invocation, so it can't go through the write_minify wrapper.
 249         cx.write_minify(
 250             SharedResource::InvocationSpecific { basename: "theme.css" },
 251             &buffer,
 252             options.enable_minification,
 253             &options.emit,
 254         )?;
 255     }
 256     write_minify("normalize.css", static_files::NORMALIZE_CSS)?;
 257     for (name, contents) in &*FILES_UNVERSIONED {
 258         cx.write_shared(SharedResource::Unversioned { name }, contents, &options.emit)?;
 259     }
 260
 261     fn collect(path: &Path, krate: &str, key: &str) -> io::Result<(Vec<String>, Vec<String>)> {
 262         let mut ret = Vec::new();
 263         let mut krates = Vec::new();
 264
 265         if path.exists() {
 266             let prefix = format!(r#"{}["{}"]"#, key, krate);
 267             for line in BufReader::new(File::open(path)?).lines() {
 268                 let line = line?;
 269                 if !line.starts_with(key) {
 270                     continue;
 271                 }
 272                 if line.starts_with(&prefix) {
 273                     continue;
 274                 }
 275                 ret.push(line.to_string());
 276                 krates.push(
 277                     line[key.len() + 2..]
 278                         .split('"')
 279                         .next()
 280                         .map(|s| s.to_owned())
 281                         .unwrap_or_else(String::new),
 282                 );
 283             }
 284         }
 285         Ok((ret, krates))
 286     }
 287
 288     fn collect_json(path: &Path, krate: &str) -> io::Result<(Vec<String>, Vec<String>)> {
 289         let mut ret = Vec::new();
 290         let mut krates = Vec::new();
 291
 292         if path.exists() {
 293             let prefix = format!("\"{}\"", krate);
 294             for line in BufReader::new(File::open(path)?).lines() {
 295                 let line = line?;
 296                 if !line.starts_with('"') {
 297                     continue;
 298                 }
 299                 if line.starts_with(&prefix) {
 300                     continue;
 301                 }
 302                 if line.ends_with(",\\") {
 303                     ret.push(line[..line.len() - 2].to_string());
 304                 } else {
 305                     // Ends with "\\" (it's the case for the last added crate line)
 306                     ret.push(line[..line.len() - 1].to_string());
 307                 }
 308                 krates.push(
 309                     line.split('"')
 310                         .find(|s| !s.is_empty())
 311                         .map(|s| s.to_owned())
 312                         .unwrap_or_else(String::new),
 313                 );
 314             }
 315         }
 316         Ok((ret, krates))
 317     }
 318
 319     use std::ffi::OsString;
 320
 321     #[derive(Debug)]
 322     struct Hierarchy {
 323         elem: OsString,
 324         children: FxHashMap<OsString, Hierarchy>,
 325         elems: FxHashSet<OsString>,
 326     }
 327
 328     impl Hierarchy {
 329         fn new(elem: OsString) -> Hierarchy {
 330             Hierarchy { elem, children: FxHashMap::default(), elems: FxHashSet::default() }
 331         }
 332
 333         fn to_json_string(&self) -> String {
 334             let mut subs: Vec<&Hierarchy> = self.children.values().collect();
 335             subs.sort_unstable_by(|a, b| a.elem.cmp(&b.elem));
 336             let mut files = self
 337                 .elems
 338                 .iter()
 339                 .map(|s| format!("\"{}\"", s.to_str().expect("invalid osstring conversion")))
 340                 .collect::<Vec<_>>();
 341             files.sort_unstable();
 342             let subs = subs.iter().map(|s| s.to_json_string()).collect::<Vec<_>>().join(",");
 343             let dirs =
 344                 if subs.is_empty() { String::new() } else { format!(",\"dirs\":[{}]", subs) };
 345             let files = files.join(",");
 346             let files =
 347                 if files.is_empty() { String::new() } else { format!(",\"files\":[{}]", files) };
 348             format!(
 349                 "{{\"name\":\"{name}\"{dirs}{files}}}",
 350                 name = self.elem.to_str().expect("invalid osstring conversion"),
 351                 dirs = dirs,
 352                 files = files
 353             )
 354         }
 355     }
 356
 357     if cx.shared.include_sources {
 358         let mut hierarchy = Hierarchy::new(OsString::new());
 359         for source in cx
 360             .shared
 361             .local_sources
 362             .iter()
 363             .filter_map(|p| p.0.strip_prefix(&cx.shared.src_root).ok())
 364         {
 365             let mut h = &mut hierarchy;
 366             let mut elems = source
 367                 .components()
 368                 .filter_map(|s| match s {
 369                     Component::Normal(s) => Some(s.to_owned()),
 370                     _ => None,
 371                 })
 372                 .peekable();
 373             loop {
 374                 let cur_elem = elems.next().expect("empty file path");
 375                 if elems.peek().is_none() {
 376                     h.elems.insert(cur_elem);
 377                     break;
 378                 } else {
 379                     let e = cur_elem.clone();
 380                     h = h.children.entry(cur_elem.clone()).or_insert_with(|| Hierarchy::new(e));
 381                 }
 382             }
 383         }
 384
 385         let dst = cx.dst.join(&format!("source-files{}.js", cx.shared.resource_suffix));
 386         let make_sources = || {
 387             let (mut all_sources, _krates) =
 388                 try_err!(collect(&dst, &krate.name.as_str(), "sourcesIndex"), &dst);
 389             all_sources.push(format!(
 390                 "sourcesIndex[\"{}\"] = {};",
 391                 &krate.name,
 392                 hierarchy.to_json_string()
 393             ));
 394             all_sources.sort();
 395             Ok(format!(
 396                 "var N = null;var sourcesIndex = {{}};\n{}\ncreateSourceSidebar();\n",
 397                 all_sources.join("\n")
 398             )
 399             .into_bytes())
 400         };
 401         write_crate("source-files.js", &make_sources)?;
 402     }
 403
 404     // Update the search index and crate list.
 405     let dst = cx.dst.join(&format!("search-index{}.js", cx.shared.resource_suffix));
 406     let (mut all_indexes, mut krates) = try_err!(collect_json(&dst, &krate.name.as_str()), &dst);
 407     all_indexes.push(search_index);
 408     krates.push(krate.name.to_string());
 409     krates.sort();
 410
 411     // Sort the indexes by crate so the file will be generated identically even
 412     // with rustdoc running in parallel.
 413     all_indexes.sort();
 414     write_crate("search-index.js", &|| {
 415         let mut v = String::from("var searchIndex = JSON.parse('{\\\n");
 416         v.push_str(&all_indexes.join(",\\\n"));
 417         v.push_str("\\\n}');\nif (window.initSearch) {window.initSearch(searchIndex)};");
 418         Ok(v.into_bytes())
 419     })?;
 420
 421     write_crate("crates.js", &|| {
 422         let krates = krates.iter().map(|k| format!("\"{}\"", k)).join(",");
 423         Ok(format!("window.ALL_CRATES = [{}];", krates).into_bytes())
 424     })?;
 425
 426     if options.enable_index_page {
 427         if let Some(index_page) = options.index_page.clone() {
 428             let mut md_opts = options.clone();
 429             md_opts.output = cx.dst.clone();
 430             md_opts.external_html = (*cx.shared).layout.external_html.clone();
 431
 432             crate::markdown::render(&index_page, md_opts, cx.shared.edition())
 433                 .map_err(|e| Error::new(e, &index_page))?;
 434         } else {
 435             let dst = cx.dst.join("index.html");
 436             let page = layout::Page {
 437                 title: "Index of crates",
 438                 css_class: "mod",
 439                 root_path: "./",
 440                 static_root_path: cx.shared.static_root_path.as_deref(),
 441                 description: "List of crates",
 442                 keywords: BASIC_KEYWORDS,
 443                 resource_suffix: &cx.shared.resource_suffix,
 444                 extra_scripts: &[],
 445                 static_extra_scripts: &[],
 446             };
 447
 448             let content = format!(
 449                 "<h1 class=\"fqn\">\
 450                      <span class=\"in-band\">List of all crates</span>\
 451                 </h1><ul class=\"crate mod\">{}</ul>",
 452                 krates
 453                     .iter()
 454                     .map(|s| {
 455                         format!(
 456                             "<li><a class=\"crate mod\" href=\"{}index.html\">{}</a></li>",
 457                             ensure_trailing_slash(s),
 458                             s
 459                         )
 460                     })
 461                     .collect::<String>()
 462             );
 463             let v = layout::render(&cx.shared.layout, &page, "", content, &cx.shared.style_files);
 464             cx.shared.fs.write(&dst, v.as_bytes())?;
 465         }
 466     }
 467
 468     // Update the list of all implementors for traits
 469     let dst = cx.dst.join("implementors");
 470     for (&did, imps) in &cx.cache.implementors {
 471         // Private modules can leak through to this phase of rustdoc, which
 472         // could contain implementations for otherwise private types. In some
 473         // rare cases we could find an implementation for an item which wasn't
 474         // indexed, so we just skip this step in that case.
 475         //
 476         // FIXME: this is a vague explanation for why this can't be a `get`, in
 477         //        theory it should be...
 478         let &(ref remote_path, remote_item_type) = match cx.cache.paths.get(&did) {
 479             Some(p) => p,
 480             None => match cx.cache.external_paths.get(&did) {
 481                 Some(p) => p,
 482                 None => continue,
 483             },
 484         };
 485
 486         #[derive(Serialize)]
 487         struct Implementor {
 488             text: String,
 489             synthetic: bool,
 490             types: Vec<String>,
 491         }
 492
 493         let implementors = imps
 494             .iter()
 495             .filter_map(|imp| {
 496                 // If the trait and implementation are in the same crate, then
 497                 // there's no need to emit information about it (there's inlining
 498                 // going on). If they're in different crates then the crate defining
 499                 // the trait will be interested in our implementation.
 500                 //
 501                 // If the implementation is from another crate then that crate
 502                 // should add it.
 503                 if imp.impl_item.def_id.krate() == did.krate || !imp.impl_item.def_id.is_local() {
 504                     None
 505                 } else {
 506                     Some(Implementor {
 507                         text: imp.inner_impl().print(false, cx).to_string(),
 508                         synthetic: imp.inner_impl().synthetic,
 509                         types: collect_paths_for_type(imp.inner_impl().for_.clone(), cx.cache()),
 510                     })
 511                 }
 512             })
 513             .collect::<Vec<_>>();
 514
 515         // Only create a js file if we have impls to add to it. If the trait is
 516         // documented locally though we always create the file to avoid dead
 517         // links.
 518         if implementors.is_empty() && !cx.cache.paths.contains_key(&did) {
 519             continue;
 520         }
 521
 522         let implementors = format!(
 523             r#"implementors["{}"] = {};"#,
 524             krate.name,
 525             serde_json::to_string(&implementors).unwrap()
 526         );
 527
 528         let mut mydst = dst.clone();
 529         for part in &remote_path[..remote_path.len() - 1] {
 530             mydst.push(part);
 531         }
 532         cx.shared.ensure_dir(&mydst)?;
 533         mydst.push(&format!("{}.{}.js", remote_item_type, remote_path[remote_path.len() - 1]));
 534
 535         let (mut all_implementors, _) =
 536             try_err!(collect(&mydst, &krate.name.as_str(), "implementors"), &mydst);
 537         all_implementors.push(implementors);
 538         // Sort the implementors by crate so the file will be generated
 539         // identically even with rustdoc running in parallel.
 540         all_implementors.sort();
 541
 542         let mut v = String::from("(function() {var implementors = {};\n");
 543         for implementor in &all_implementors {
 544             writeln!(v, "{}", *implementor).unwrap();
 545         }
 546         v.push_str(
 547             "if (window.register_implementors) {\
 548                  window.register_implementors(implementors);\
 549              } else {\
 550                  window.pending_implementors = implementors;\
 551              }",
 552         );
 553         v.push_str("})()");
 554         cx.shared.fs.write(&mydst, &v)?;
 555     }
 556     Ok(())
 557 }