rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Auto merge of #49956 - QuietMisdreavus:rustdoc-codegen, r=GuillaumeGomez

Browse Source 
rustdoc: port the -C option from rustc

Blocked on https://github.com/rust-lang/rust/pull/49864. The included test won't work without those changes, so this PR includes those commits as well.

When documenting items that require certain target features, it helps to be able to force those target features into existence. Rather than include a flag just to parse those features, i instead decided to port the `-C` flag from rustc in its entirety. It takes the same parameters, because it runs through the same parsing function. This has the added benefit of being able to control the codegen of doctests as well.

One concern i have with the flag is that i set it to stable here. My rationale is that it is a direct port of functionality on rustc that is currently stable, used only in mechanisms that it is originally used for. If needed, i can set it back to be unstable.
This commit is contained in:
bors
2018-04-16 05:00:14 +00:00
parent 748c549185 a5456bdd87
commit 3e70dfd655
6 changed files with 84 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
src/doc/rustdoc/src/command-line-arguments.md
View File

@@ -141,6 +141,31 @@ Similar to `--library-path`, `--extern` is about specifying the location
of a dependency. `--library-path` provides directories to search in, `--extern`
instead lets you specify exactly which dependency is located where.
## `-C`/`--codegen`: pass codegen options to rustc
Using this flag looks like this:
```bash
$ rustdoc src/lib.rs -C target_feature=+avx
$ rustdoc src/lib.rs --codegen target_feature=+avx
$ rustdoc --test src/lib.rs -C target_feature=+avx
$ rustdoc --test src/lib.rs --codegen target_feature=+avx
$ rustdoc --test README.md -C target_feature=+avx
$ rustdoc --test README.md --codegen target_feature=+avx
```
When rustdoc generates documentation, looks for documentation tests, or executes documentation
tests, it needs to compile some rust code, at least part-way. This flag allows you to tell rustdoc
to provide some extra codegen options to rustc when it runs these compilations. Most of the time,
these options won't affect a regular documentation run, but if something depends on target features
to be enabled, or documentation tests need to use some additional options, this flag allows you to
affect that.
The arguments to this flag are the same as those for the `-C` flag on rustc. Run `rustc -C help` to
get the full list.
## `--passes`: add more rustdoc passes
Using this flag looks like this:

6
src/librustdoc/core.rs
View File

@@ -42,7 +42,7 @@ use clean;
use clean::Clean;
use html::render::RenderInfo;
pub use rustc::session::config::Input;
pub use rustc::session::config::{Input, CodegenOptions};
pub use rustc::session::search_paths::SearchPaths;
pub type ExternalPaths = FxHashMap<DefId, (Vec<String>, clean::TypeKind)>;
@@ -125,7 +125,8 @@ pub fn run_core(search_paths: SearchPaths,
allow_warnings: bool,
crate_name: Option<String>,
force_unstable_if_unmarked: bool,
edition: Edition) -> (clean::Crate, RenderInfo)
edition: Edition,
cg: CodegenOptions) -> (clean::Crate, RenderInfo)
{
// Parse, resolve, and typecheck the given crate.
@@ -143,6 +144,7 @@ pub fn run_core(search_paths: SearchPaths,
crate_types: vec![config::CrateTypeRlib],
lint_opts: if !allow_warnings { vec![(warning_lint, lint::Allow)] } else { vec![] },
lint_cap: Some(lint::Allow),
cg,
externs,
target_triple: triple.unwrap_or(host_triple),
// Ensure that rustdoc works even if rustc is feature-staged

22
src/librustdoc/lib.rs
View File

@@ -61,7 +61,8 @@ use std::sync::mpsc::channel;
use syntax::edition::Edition;
use externalfiles::ExternalHtml;
use rustc::session::search_paths::SearchPaths;
use rustc::session::config::{ErrorOutputType, RustcOptGroup, nightly_options, Externs};
use rustc::session::config::{ErrorOutputType, RustcOptGroup, Externs, CodegenOptions};
use rustc::session::config::{nightly_options, build_codegen_options};
use rustc_back::target::TargetTriple;
#[macro_use]
@@ -155,6 +156,9 @@ pub fn opts() -> Vec<RustcOptGroup> {
stable("plugin-path", |o| {
o.optmulti("", "plugin-path", "directory to load plugins from", "DIR")
}),
stable("C", |o| {
o.optmulti("C", "codegen", "pass a codegen option to rustc", "OPT[=VALUE]")
}),
stable("passes", |o| {
o.optmulti("", "passes",
"list of passes to also run, you might want \
@@ -441,14 +445,16 @@ pub fn main_args(args: &[String]) -> isize {
}
};
let cg = build_codegen_options(&matches, ErrorOutputType::default());
match (should_test, markdown_input) {
(true, true) => {
return markdown::test(input, cfgs, libs, externs, test_args, maybe_sysroot,
display_warnings, linker, edition)
display_warnings, linker, edition, cg)
}
(true, false) => {
return test::run(Path::new(input), cfgs, libs, externs, test_args, crate_name,
maybe_sysroot, display_warnings, linker, edition)
maybe_sysroot, display_warnings, linker, edition, cg)
}
(false, true) => return markdown::render(Path::new(input),
output.unwrap_or(PathBuf::from("doc")),
@@ -458,7 +464,7 @@ pub fn main_args(args: &[String]) -> isize {
}
let output_format = matches.opt_str("w");
let res = acquire_input(PathBuf::from(input), externs, edition, &matches, move |out| {
let res = acquire_input(PathBuf::from(input), externs, edition, cg, &matches, move |out| {
let Output { krate, passes, renderinfo } = out;
info!("going to format");
match output_format.as_ref().map(|s| &**s) {
@@ -500,14 +506,15 @@ fn print_error<T>(error_message: T) where T: Display {
fn acquire_input<R, F>(input: PathBuf,
externs: Externs,
edition: Edition,
cg: CodegenOptions,
matches: &getopts::Matches,
f: F)
-> Result<R, String>
where R: 'static + Send, F: 'static + Send + FnOnce(Output) -> R {
match matches.opt_str("r").as_ref().map(|s| &**s) {
Some("rust") => Ok(rust_input(input, externs, edition, matches, f)),
Some("rust") => Ok(rust_input(input, externs, edition, cg, matches, f)),
Some(s) => Err(format!("unknown input format: {}", s)),
None => Ok(rust_input(input, externs, edition, matches, f))
None => Ok(rust_input(input, externs, edition, cg, matches, f))
}
}
@@ -536,6 +543,7 @@ fn parse_externs(matches: &getopts::Matches) -> Result<Externs, String> {
fn rust_input<R, F>(cratefile: PathBuf,
externs: Externs,
edition: Edition,
cg: CodegenOptions,
matches: &getopts::Matches,
f: F) -> R
where R: 'static + Send,
@@ -589,7 +597,7 @@ where R: 'static + Send,
let (mut krate, renderinfo) =
core::run_core(paths, cfgs, externs, Input::File(cratefile), triple, maybe_sysroot,
display_warnings, crate_name.clone(),
force_unstable_if_unmarked, edition);
force_unstable_if_unmarked, edition, cg);
info!("finished with rustc");

7
src/librustdoc/markdown.rs
View File

@@ -16,7 +16,7 @@ use std::path::{PathBuf, Path};
use getopts;
use testing;
use rustc::session::search_paths::SearchPaths;
use rustc::session::config::Externs;
use rustc::session::config::{Externs, CodegenOptions};
use syntax::codemap::DUMMY_SP;
use syntax::edition::Edition;
@@ -140,7 +140,8 @@ pub fn render(input: &Path, mut output: PathBuf, matches: &getopts::Matches,
/// Run any tests/code examples in the markdown file `input`.
pub fn test(input: &str, cfgs: Vec<String>, libs: SearchPaths, externs: Externs,
mut test_args: Vec<String>, maybe_sysroot: Option<PathBuf>,
display_warnings: bool, linker: Option<PathBuf>, edition: Edition) -> isize {
display_warnings: bool, linker: Option<PathBuf>, edition: Edition,
cg: CodegenOptions) -> isize {
let input_str = match load_string(input) {
Ok(s) => s,
Err(LoadStringError::ReadFail) => return 1,
@@ -150,7 +151,7 @@ pub fn test(input: &str, cfgs: Vec<String>, libs: SearchPaths, externs: Externs,
let mut opts = TestOptions::default();
opts.no_crate_inject = true;
opts.display_warnings = display_warnings;
let mut collector = Collector::new(input.to_owned(), cfgs, libs, externs,
let mut collector = Collector::new(input.to_owned(), cfgs, libs, cg, externs,
true, opts, maybe_sysroot, None,
Some(PathBuf::from(input)),
linker, edition);

23
src/librustdoc/test.rs
View File

@@ -24,7 +24,7 @@ use rustc_lint;
use rustc::hir;
use rustc::hir::intravisit;
use rustc::session::{self, CompileIncomplete, config};
use rustc::session::config::{OutputType, OutputTypes, Externs};
use rustc::session::config::{OutputType, OutputTypes, Externs, CodegenOptions};
use rustc::session::search_paths::{SearchPaths, PathKind};
use rustc_metadata::dynamic_lib::DynamicLibrary;
use tempdir::TempDir;
@@ -64,7 +64,8 @@ pub fn run(input_path: &Path,
maybe_sysroot: Option<PathBuf>,
display_warnings: bool,
linker: Option<PathBuf>,
edition: Edition)
edition: Edition,
cg: CodegenOptions)
-> isize {
let input = config::Input::File(input_path.to_owned());
@@ -73,6 +74,7 @@ pub fn run(input_path: &Path,
|| Some(env::current_exe().unwrap().parent().unwrap().parent().unwrap().to_path_buf())),
search_paths: libs.clone(),
crate_types: vec![config::CrateTypeDylib],
cg: cg.clone(),
externs: externs.clone(),
unstable_features: UnstableFeatures::from_environment(),
lint_cap: Some(::rustc::lint::Level::Allow),
@@ -125,6 +127,7 @@ pub fn run(input_path: &Path,
let mut collector = Collector::new(crate_name,
cfgs,
libs,
cg,
externs,
false,
opts,
@@ -190,7 +193,7 @@ fn scrape_test_config(krate: &::rustc::hir::Crate) -> TestOptions {
fn run_test(test: &str, cratename: &str, filename: &FileName, line: usize,
cfgs: Vec<String>, libs: SearchPaths,
externs: Externs,
cg: CodegenOptions, externs: Externs,
should_panic: bool, no_run: bool, as_test_harness: bool,
compile_fail: bool, mut error_codes: Vec<String>, opts: &TestOptions,
maybe_sysroot: Option<PathBuf>, linker: Option<PathBuf>, edition: Edition) {
@@ -215,7 +218,7 @@ fn run_test(test: &str, cratename: &str, filename: &FileName, line: usize,
cg: config::CodegenOptions {
prefer_dynamic: true,
linker,
.. config::basic_codegen_options()
..cg
},
test: as_test_harness,
unstable_features: UnstableFeatures::from_environment(),
@@ -478,6 +481,7 @@ pub struct Collector {
cfgs: Vec<String>,
libs: SearchPaths,
cg: CodegenOptions,
externs: Externs,
use_headers: bool,
cratename: String,
@@ -491,15 +495,16 @@ pub struct Collector {
}
impl Collector {
pub fn new(cratename: String, cfgs: Vec<String>, libs: SearchPaths, externs: Externs,
use_headers: bool, opts: TestOptions, maybe_sysroot: Option<PathBuf>,
codemap: Option<Lrc<CodeMap>>, filename: Option<PathBuf>,
linker: Option<PathBuf>, edition: Edition) -> Collector {
pub fn new(cratename: String, cfgs: Vec<String>, libs: SearchPaths, cg: CodegenOptions,
externs: Externs, use_headers: bool, opts: TestOptions,
maybe_sysroot: Option<PathBuf>, codemap: Option<Lrc<CodeMap>>,
filename: Option<PathBuf>, linker: Option<PathBuf>, edition: Edition) -> Collector {
Collector {
tests: Vec::new(),
names: Vec::new(),
cfgs,
libs,
cg,
externs,
use_headers,
cratename,
@@ -524,6 +529,7 @@ impl Collector {
let name = self.generate_name(line, &filename);
let cfgs = self.cfgs.clone();
let libs = self.libs.clone();
let cg = self.cg.clone();
let externs = self.externs.clone();
let cratename = self.cratename.to_string();
let opts = self.opts.clone();
@@ -552,6 +558,7 @@ impl Collector {
line,
cfgs,
libs,
cg,
externs,
should_panic,
no_run,

21
src/test/rustdoc/force-target-feature.rs Normal file
View File

@@ -0,0 +1,21 @@
// Copyright 2017 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
// only-x86_64
// compile-flags:--test -C target-feature=+avx
// should-fail
/// (written on a spider's web) Some Struct
///
/// ```
/// panic!("oh no");
/// ```
#[doc(cfg(target_feature = "avx"))]
pub struct SomeStruct;