diff --git a/src/doc/rustdoc/src/command-line-arguments.md b/src/doc/rustdoc/src/command-line-arguments.md index e51c63cf00898..417608cc5ca0a 100644 --- a/src/doc/rustdoc/src/command-line-arguments.md +++ b/src/doc/rustdoc/src/command-line-arguments.md @@ -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: diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 6e2be2610cec0..781379d2d8c3e 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -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, clean::TypeKind)>; @@ -125,7 +125,8 @@ pub fn run_core(search_paths: SearchPaths, allow_warnings: bool, crate_name: Option, 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 diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 8463475afabda..1339a66f8b2e9 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -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 { 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(error_message: T) where T: Display { fn acquire_input(input: PathBuf, externs: Externs, edition: Edition, + cg: CodegenOptions, matches: &getopts::Matches, f: F) -> Result 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 { fn rust_input(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"); diff --git a/src/librustdoc/markdown.rs b/src/librustdoc/markdown.rs index f14d4c602d070..8ada5ce1a4df9 100644 --- a/src/librustdoc/markdown.rs +++ b/src/librustdoc/markdown.rs @@ -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, libs: SearchPaths, externs: Externs, mut test_args: Vec, maybe_sysroot: Option, - display_warnings: bool, linker: Option, edition: Edition) -> isize { + display_warnings: bool, linker: Option, 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, 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); diff --git a/src/librustdoc/test.rs b/src/librustdoc/test.rs index a166bca709edb..600e9eaa05f14 100644 --- a/src/librustdoc/test.rs +++ b/src/librustdoc/test.rs @@ -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, display_warnings: bool, linker: Option, - 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, 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, opts: &TestOptions, maybe_sysroot: Option, linker: Option, 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, 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, libs: SearchPaths, externs: Externs, - use_headers: bool, opts: TestOptions, maybe_sysroot: Option, - codemap: Option>, filename: Option, - linker: Option, edition: Edition) -> Collector { + pub fn new(cratename: String, cfgs: Vec, libs: SearchPaths, cg: CodegenOptions, + externs: Externs, use_headers: bool, opts: TestOptions, + maybe_sysroot: Option, codemap: Option>, + filename: Option, linker: Option, 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, diff --git a/src/test/rustdoc/force-target-feature.rs b/src/test/rustdoc/force-target-feature.rs new file mode 100644 index 0000000000000..08f1f06baa319 --- /dev/null +++ b/src/test/rustdoc/force-target-feature.rs @@ -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 or the MIT license +// , 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;