diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index b43070510413a..c51e278c5a7dc 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -250,14 +250,14 @@ details. Using this flag looks like this: ```bash -$ rustdoc src/lib.rs -Z unstable-options --extern-html-root-url some-crate=https://example.com/some-crate/1.0.1 +$ rustdoc src/lib.rs -Z unstable-options --extern-html-root-url libsome_crate.rlib=https://example.com/some-crate/1.0.1 ``` Ordinarily, when rustdoc wants to link to a type from a different crate, it looks in two places: docs that already exist in the output directory, or the `#![doc(doc_html_root)]` set in the other crate. However, if you want to link to docs that exist in neither of those places, you can use these -flags to control that behavior. When the `--extern-html-root-url` flag is given with a name matching -one of your dependencies, rustdoc use that URL for those docs. Keep in mind that if those docs exist +flags to control that behavior. When the `--extern-html-root-url` flag is given with a filename matching +one of your dependencies, rustdoc will use that URL for those docs. Keep in mind that if those docs exist in the output directory, those local docs will still override this flag. ### `-Z force-unstable-if-unmarked` diff --git a/src/librustdoc/clean/mod.rs b/src/librustdoc/clean/mod.rs index bfc747058185e..1c87716af9d73 100644 --- a/src/librustdoc/clean/mod.rs +++ b/src/librustdoc/clean/mod.rs @@ -14,7 +14,7 @@ use rustc_attr as attr; use rustc_data_structures::fx::{FxHashMap, FxHashSet}; use rustc_hir as hir; use rustc_hir::def::{CtorKind, DefKind, Res}; -use rustc_hir::def_id::{CrateNum, DefId, CRATE_DEF_INDEX}; +use rustc_hir::def_id::{CrateNum, DefId, CRATE_DEF_INDEX, LOCAL_CRATE}; use rustc_index::vec::{Idx, IndexVec}; use rustc_infer::infer::region_constraints::{Constraint, RegionConstraintData}; use rustc_middle::bug; @@ -30,6 +30,7 @@ use rustc_typeck::hir_ty_to_ty; use std::collections::hash_map::Entry; use std::default::Default; +use std::ffi::OsStr; use std::hash::Hash; use std::rc::Rc; use std::{mem, vec}; @@ -211,9 +212,20 @@ impl Clean for CrateNum { cx.tcx.item_children(root).iter().map(|item| item.res).filter_map(as_keyword).collect() }; + let extern_files = if *self == LOCAL_CRATE { + vec![] + } else { + cx.tcx + .crate_extern_paths(*self) + .into_iter() + .filter_map(|path| path.file_name().map(OsStr::to_owned)) + .collect() + }; + ExternalCrate { name: cx.tcx.crate_name(*self).to_string(), src: krate_src, + extern_files, attrs: cx.tcx.get_attrs(root).clean(cx), primitives, keywords, diff --git a/src/librustdoc/clean/types.rs b/src/librustdoc/clean/types.rs index 32b3f69ecd4f0..a698e4f206c16 100644 --- a/src/librustdoc/clean/types.rs +++ b/src/librustdoc/clean/types.rs @@ -1,5 +1,6 @@ use std::cell::RefCell; use std::default::Default; +use std::ffi::OsString; use std::fmt; use std::hash::{Hash, Hasher}; use std::iter::FromIterator; @@ -66,6 +67,7 @@ pub struct Crate { pub struct ExternalCrate { pub name: String, pub src: FileName, + pub extern_files: Vec, pub attrs: Attributes, pub primitives: Vec<(DefId, PrimitiveType, Attributes)>, pub keywords: Vec<(DefId, String, Attributes)>, diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs index 02885f519363c..a9cd80c8a6376 100644 --- a/src/librustdoc/config.rs +++ b/src/librustdoc/config.rs @@ -1,6 +1,6 @@ use std::collections::{BTreeMap, HashMap}; use std::convert::TryFrom; -use std::ffi::OsStr; +use std::ffi::{OsStr, OsString}; use std::fmt; use std::path::PathBuf; @@ -214,8 +214,8 @@ pub struct RenderOptions { pub themes: Vec, /// If present, CSS file that contains rules to add to the default CSS. pub extension_css: Option, - /// A map of crate names to the URL to use instead of querying the crate's `html_root_url`. - pub extern_html_root_urls: BTreeMap, + /// A map of crate source filenames to the URL to use instead of querying the crate's `html_root_url`. + pub extern_html_root_urls: BTreeMap, /// A map of the default settings (values are as for DOM storage API). Keys should lack the /// `rustdoc-` prefix. pub default_settings: HashMap, @@ -690,13 +690,13 @@ fn check_deprecated_options(matches: &getopts::Matches, diag: &rustc_errors::Han /// describing the issue. fn parse_extern_html_roots( matches: &getopts::Matches, -) -> Result, &'static str> { +) -> Result, &'static str> { let mut externs = BTreeMap::new(); for arg in &matches.opt_strs("extern-html-root-url") { let mut parts = arg.splitn(2, '='); let name = parts.next().ok_or("--extern-html-root-url must not be empty")?; let url = parts.next().ok_or("--extern-html-root-url must be of the form name=url")?; - externs.insert(name.to_string(), url.to_string()); + externs.insert(name.into(), url.to_string()); } Ok(externs) diff --git a/src/librustdoc/formats/cache.rs b/src/librustdoc/formats/cache.rs index b99321e8484c9..7ae9b01ed4934 100644 --- a/src/librustdoc/formats/cache.rs +++ b/src/librustdoc/formats/cache.rs @@ -1,5 +1,6 @@ use std::cell::RefCell; use std::collections::BTreeMap; +use std::ffi::OsString; use std::mem; use std::path::{Path, PathBuf}; use std::sync::Arc; @@ -128,7 +129,7 @@ impl Cache { pub fn from_krate( render_info: RenderInfo, document_private: bool, - extern_html_root_urls: &BTreeMap, + extern_html_root_urls: &BTreeMap, dst: &Path, mut krate: clean::Crate, ) -> (clean::Crate, Cache) { @@ -173,7 +174,12 @@ impl Cache { }, _ => PathBuf::new(), }; - let extern_url = extern_html_root_urls.get(&e.name).map(|u| &**u); + let extern_url = e + .extern_files + .iter() + .filter_map(|file_name| extern_html_root_urls.get(file_name)) + .next() + .map(|u| &**u); cache .extern_locations .insert(n, (e.name.clone(), src_root, extern_location(e, extern_url, &dst))); diff --git a/src/librustdoc/html/render/cache.rs b/src/librustdoc/html/render/cache.rs index cf785d362cd11..1bbd94aa5739e 100644 --- a/src/librustdoc/html/render/cache.rs +++ b/src/librustdoc/html/render/cache.rs @@ -13,6 +13,7 @@ use crate::html::render::{plain_text_summary, shorten}; use crate::html::render::{Generic, IndexItem, IndexItemFunctionType, RenderType, TypeWithKind}; /// Indicates where an external crate can be found. +#[derive(Debug)] pub enum ExternalLocation { /// Remote URL root of the external crate Remote(String), diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 616b031814fa5..bd96edbbe9f44 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -146,7 +146,7 @@ fn opts() -> Vec { stable("cfg", |o| o.optmulti("", "cfg", "pass a --cfg to rustc", "")), stable("extern", |o| o.optmulti("", "extern", "pass an --extern to rustc", "NAME[=PATH]")), unstable("extern-html-root-url", |o| { - o.optmulti("", "extern-html-root-url", "base URL to use for dependencies", "NAME=URL") + o.optmulti("", "extern-html-root-url", "base URL to use for dependencies", "PATH=URL") }), stable("plugin-path", |o| o.optmulti("", "plugin-path", "removed", "DIR")), stable("C", |o| { diff --git a/src/test/rustdoc/auxiliary/extern-html-root-url.rs b/src/test/rustdoc/auxiliary/extern-html-root-url.rs new file mode 100644 index 0000000000000..b5eb8528e73f8 --- /dev/null +++ b/src/test/rustdoc/auxiliary/extern-html-root-url.rs @@ -0,0 +1,2 @@ +// compile-flags: -C metadata=1 +pub mod iter {} diff --git a/src/test/rustdoc/auxiliary/issue-76296-1.rs b/src/test/rustdoc/auxiliary/issue-76296-1.rs new file mode 100644 index 0000000000000..b73e76a7732db --- /dev/null +++ b/src/test/rustdoc/auxiliary/issue-76296-1.rs @@ -0,0 +1,6 @@ +// compile-flags: -C metadata=1 +// compile-flags: -C extra-filename=-1 +#![crate_name="foo"] +#![doc(html_root_url="https://example.com/foo/v1")] + +pub struct Foo1; diff --git a/src/test/rustdoc/auxiliary/issue-76296-2.rs b/src/test/rustdoc/auxiliary/issue-76296-2.rs new file mode 100644 index 0000000000000..61ebc80336ab5 --- /dev/null +++ b/src/test/rustdoc/auxiliary/issue-76296-2.rs @@ -0,0 +1,6 @@ +// compile-flags: -C metadata=2 +// compile-flags: -C extra-filename=-2 +#![crate_name = "foo"] +#![doc(html_root_url="https://example.com/foo/v2")] + +pub struct Foo2; diff --git a/src/test/rustdoc/extern-html-root-url.rs b/src/test/rustdoc/extern-html-root-url.rs index 60b7b28ae4acf..7a6de25ecbb13 100644 --- a/src/test/rustdoc/extern-html-root-url.rs +++ b/src/test/rustdoc/extern-html-root-url.rs @@ -1,6 +1,9 @@ -// compile-flags:-Z unstable-options --extern-html-root-url core=https://example.com/core/0.1.0 +// aux-crate: priv:extern_html_root_url=extern-html-root-url.rs +// compile-flags: -Z unstable-options +// compile-flags: --edition 2018 +// compile-flags: --extern-html-root-url libextern_html_root_url.so=https://example.com/core/0.1.0 // @has extern_html_root_url/index.html -// @has - '//a/@href' 'https://example.com/core/0.1.0/core/iter/index.html' +// @has - '//a/@href' 'https://example.com/core/0.1.0/extern_html_root_url/iter/index.html' #[doc(no_inline)] -pub use std::iter; +pub use extern_html_root_url::iter; diff --git a/src/test/rustdoc/issue-76296-override.rs b/src/test/rustdoc/issue-76296-override.rs new file mode 100644 index 0000000000000..51cf27087e472 --- /dev/null +++ b/src/test/rustdoc/issue-76296-override.rs @@ -0,0 +1,32 @@ +// aux-build: issue-76296-1.rs +// aux-build: issue-76296-2.rs +// compile-flags: -Z unstable-options +// compile-flags: --edition 2018 +// compile-flags: --extern priv:foo1={{build-base}}/issue-76296-override/auxiliary/libfoo-1.so +// compile-flags: --extern priv:foo2={{build-base}}/issue-76296-override/auxiliary/libfoo-2.so +// compile-flags: --extern-html-root-url libfoo-1.so=https://example.com/override/v1 +// compile-flags: --extern-html-root-url libfoo-2.so=https://example.com/override/v2 + +// @has 'issue_76296_override/index.html' +// @matches - '//a[@href="https://example.com/override/v1/foo/struct.Foo1.html"]' '^Foo1$' +// @matches - '//a[@href="https://example.com/override/v2/foo/struct.Foo2.html"]' '^Foo2$' + +#[doc(no_inline)] +pub use foo1::Foo1; + +#[doc(no_inline)] +pub use foo2::Foo2; + +// @has 'issue_76296_override/fn.foo1.html' +// @matches - '//a[@href="https://example.com/override/v1/foo/struct.Foo1.html"]' '^foo1::Foo1$' +// @matches - '//a[@href="https://example.com/override/v1/foo/struct.Foo1.html"]' '^Foo1$' + +/// Makes a [`foo1::Foo1`] +pub fn foo1() -> Foo1 { foo1::Foo1 } + +// @has 'issue_76296_override/fn.foo2.html' +// @matches - '//a[@href="https://example.com/override/v2/foo/struct.Foo2.html"]' '^foo2::Foo2$' +// @matches - '//a[@href="https://example.com/override/v2/foo/struct.Foo2.html"]' '^Foo2$' + +/// Makes a [`foo2::Foo2`] +pub fn foo2() -> Foo2 { foo2::Foo2 } diff --git a/src/test/rustdoc/issue-76296.rs b/src/test/rustdoc/issue-76296.rs new file mode 100644 index 0000000000000..5cb39e14c414c --- /dev/null +++ b/src/test/rustdoc/issue-76296.rs @@ -0,0 +1,30 @@ +// aux-build: issue-76296-1.rs +// aux-build: issue-76296-2.rs +// compile-flags: -Z unstable-options +// compile-flags: --edition 2018 +// compile-flags: --extern priv:foo1={{build-base}}/issue-76296/auxiliary/libfoo-1.so +// compile-flags: --extern priv:foo2={{build-base}}/issue-76296/auxiliary/libfoo-2.so + +// @has 'issue_76296/index.html' +// @matches - '//a[@href="https://example.com/foo/v1/foo/struct.Foo1.html"]' '^Foo1$' +// @matches - '//a[@href="https://example.com/foo/v2/foo/struct.Foo2.html"]' '^Foo2$' + +#[doc(no_inline)] +pub use foo1::Foo1; + +#[doc(no_inline)] +pub use foo2::Foo2; + +// @has 'issue_76296/fn.foo1.html' +// @matches - '//a[@href="https://example.com/foo/v1/foo/struct.Foo1.html"]' '^foo1::Foo1$' +// @matches - '//a[@href="https://example.com/foo/v1/foo/struct.Foo1.html"]' '^Foo1$' + +/// Makes a [`foo1::Foo1`] +pub fn foo1() -> Foo1 { foo1::Foo1 } + +// @has 'issue_76296/fn.foo2.html' +// @matches - '//a[@href="https://example.com/foo/v2/foo/struct.Foo2.html"]' '^foo2::Foo2$' +// @matches - '//a[@href="https://example.com/foo/v2/foo/struct.Foo2.html"]' '^Foo2$' + +/// Makes a [`foo2::Foo2`] +pub fn foo2() -> Foo2 { foo2::Foo2 }