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

rustdoc: port the -C option from rustc

Blocked on rust-lang#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.

Author: bors

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:

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<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

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<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");
 

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<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);

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<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,

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 <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;