From 97059397caa797cd9a56585d43c2ee873baf9cde Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20BRANSTETT?= Date: Sat, 19 Feb 2022 14:31:20 +0100 Subject: [PATCH 1/2] Wire up --check-cfg to rustdoc --- src/librustdoc/config.rs | 5 +++++ src/librustdoc/core.rs | 4 +++- src/librustdoc/doctest.rs | 8 +++++++- src/librustdoc/lib.rs | 1 + src/test/rustdoc-ui/check-cfg-test.rs | 12 ++++++++++++ src/test/rustdoc-ui/check-cfg-test.stderr | 11 +++++++++++ src/test/rustdoc-ui/check-cfg-test.stdout | 6 ++++++ src/test/rustdoc-ui/check-cfg-unstable.rs | 2 ++ src/test/rustdoc-ui/check-cfg-unstable.stderr | 2 ++ src/test/rustdoc-ui/check-cfg.rs | 7 +++++++ src/test/rustdoc-ui/check-cfg.stderr | 10 ++++++++++ 11 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 src/test/rustdoc-ui/check-cfg-test.rs create mode 100644 src/test/rustdoc-ui/check-cfg-test.stderr create mode 100644 src/test/rustdoc-ui/check-cfg-test.stdout create mode 100644 src/test/rustdoc-ui/check-cfg-unstable.rs create mode 100644 src/test/rustdoc-ui/check-cfg-unstable.stderr create mode 100644 src/test/rustdoc-ui/check-cfg.rs create mode 100644 src/test/rustdoc-ui/check-cfg.stderr diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs index 6e483d27f336b..93f90b90e0a0d 100644 --- a/src/librustdoc/config.rs +++ b/src/librustdoc/config.rs @@ -80,6 +80,8 @@ crate struct Options { crate extern_strs: Vec, /// List of `cfg` flags to hand to the compiler. Always includes `rustdoc`. crate cfgs: Vec, + /// List of check cfg flags to hand to the compiler. + crate check_cfgs: Vec, /// Codegen options to hand to the compiler. crate codegen_options: CodegenOptions, /// Codegen options strings to hand to the compiler. @@ -172,6 +174,7 @@ impl fmt::Debug for Options { .field("libs", &self.libs) .field("externs", &FmtExterns(&self.externs)) .field("cfgs", &self.cfgs) + .field("check-cfgs", &self.check_cfgs) .field("codegen_options", &"...") .field("debugging_options", &"...") .field("target", &self.target) @@ -506,6 +509,7 @@ impl Options { }; let cfgs = matches.opt_strs("cfg"); + let check_cfgs = matches.opt_strs("check-cfg"); let extension_css = matches.opt_str("e").map(|s| PathBuf::from(&s)); @@ -677,6 +681,7 @@ impl Options { externs, extern_strs, cfgs, + check_cfgs, codegen_options, codegen_options_strs, debugging_opts, diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index c2f6f7aea757e..2b82575f71083 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -192,6 +192,7 @@ crate fn create_config( libs, externs, mut cfgs, + check_cfgs, codegen_options, debugging_opts, target, @@ -219,6 +220,7 @@ crate fn create_config( // these are definitely not part of rustdoc, but we want to warn on them anyway. rustc_lint::builtin::RENAMED_AND_REMOVED_LINTS.name.to_string(), rustc_lint::builtin::UNKNOWN_LINTS.name.to_string(), + rustc_lint::builtin::UNEXPECTED_CFGS.name.to_string(), ]; lints_to_show.extend(crate::lint::RUSTDOC_LINTS.iter().map(|lint| lint.name.to_string())); @@ -253,7 +255,7 @@ crate fn create_config( interface::Config { opts: sessopts, crate_cfg: interface::parse_cfgspecs(cfgs), - crate_check_cfg: interface::parse_check_cfg(vec![]), + crate_check_cfg: interface::parse_check_cfg(check_cfgs), input, input_path: cpath, output_file: None, diff --git a/src/librustdoc/doctest.rs b/src/librustdoc/doctest.rs index 5ccc3dabe83b7..cc68defd5a957 100644 --- a/src/librustdoc/doctest.rs +++ b/src/librustdoc/doctest.rs @@ -91,7 +91,7 @@ crate fn run(options: RustdocOptions) -> Result<(), ErrorReported> { let config = interface::Config { opts: sessopts, crate_cfg: interface::parse_cfgspecs(cfgs), - crate_check_cfg: interface::parse_check_cfg(vec![]), + crate_check_cfg: interface::parse_check_cfg(options.check_cfgs.clone()), input, input_path: None, output_file: None, @@ -321,6 +321,12 @@ fn run_test( for cfg in &rustdoc_options.cfgs { compiler.arg("--cfg").arg(&cfg); } + if !rustdoc_options.check_cfgs.is_empty() { + compiler.arg("-Z").arg("unstable-options"); + for check_cfg in &rustdoc_options.check_cfgs { + compiler.arg("--check-cfg").arg(&check_cfg); + } + } if let Some(sysroot) = rustdoc_options.maybe_sysroot { compiler.arg("--sysroot").arg(sysroot); } diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 7eff725989cc9..365934e91a110 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -259,6 +259,7 @@ fn opts() -> Vec { o.optmulti("L", "library-path", "directory to add to crate search path", "DIR") }), stable("cfg", |o| o.optmulti("", "cfg", "pass a --cfg to rustc", "")), + unstable("check-cfg", |o| o.optmulti("", "check-cfg", "pass a --check-cfg to rustc", "")), stable("extern", |o| o.optmulti("", "extern", "pass an --extern to rustc", "NAME[=PATH]")), unstable("extern-html-root-url", |o| { o.optmulti( diff --git a/src/test/rustdoc-ui/check-cfg-test.rs b/src/test/rustdoc-ui/check-cfg-test.rs new file mode 100644 index 0000000000000..626cc838704b3 --- /dev/null +++ b/src/test/rustdoc-ui/check-cfg-test.rs @@ -0,0 +1,12 @@ +// check-pass +// compile-flags: --test --nocapture --check-cfg=values(feature,"test") -Z unstable-options +// normalize-stderr-test: "src/test/rustdoc-ui" -> "$$DIR" +// normalize-stdout-test: "src/test/rustdoc-ui" -> "$$DIR" +// normalize-stdout-test "finished in \d+\.\d+s" -> "finished in $$TIME" + +/// The doctest will produce a warning because feature invalid is unexpected +/// ``` +/// #[cfg(feature = "invalid")] +/// assert!(false); +/// ``` +pub struct Foo; diff --git a/src/test/rustdoc-ui/check-cfg-test.stderr b/src/test/rustdoc-ui/check-cfg-test.stderr new file mode 100644 index 0000000000000..dc25205da772e --- /dev/null +++ b/src/test/rustdoc-ui/check-cfg-test.stderr @@ -0,0 +1,11 @@ +warning: unexpected `cfg` condition value + --> $DIR/check-cfg-test.rs:9:7 + | +LL | #[cfg(feature = "invalid")] + | ^^^^^^^^^^^^^^^^^^^ + | + = note: `#[warn(unexpected_cfgs)]` on by default + = note: expected values for `feature` are: test + +warning: 1 warning emitted + diff --git a/src/test/rustdoc-ui/check-cfg-test.stdout b/src/test/rustdoc-ui/check-cfg-test.stdout new file mode 100644 index 0000000000000..b7db49bcfa87a --- /dev/null +++ b/src/test/rustdoc-ui/check-cfg-test.stdout @@ -0,0 +1,6 @@ + +running 1 test +test $DIR/check-cfg-test.rs - Foo (line 8) ... ok + +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME + diff --git a/src/test/rustdoc-ui/check-cfg-unstable.rs b/src/test/rustdoc-ui/check-cfg-unstable.rs new file mode 100644 index 0000000000000..5c500ce6ce082 --- /dev/null +++ b/src/test/rustdoc-ui/check-cfg-unstable.rs @@ -0,0 +1,2 @@ +// check-fail +// compile-flags: --check-cfg=names() diff --git a/src/test/rustdoc-ui/check-cfg-unstable.stderr b/src/test/rustdoc-ui/check-cfg-unstable.stderr new file mode 100644 index 0000000000000..9b27c2bc058a7 --- /dev/null +++ b/src/test/rustdoc-ui/check-cfg-unstable.stderr @@ -0,0 +1,2 @@ +error: the `-Z unstable-options` flag must also be passed to enable the flag `check-cfg` + diff --git a/src/test/rustdoc-ui/check-cfg.rs b/src/test/rustdoc-ui/check-cfg.rs new file mode 100644 index 0000000000000..fa8789ad3ede4 --- /dev/null +++ b/src/test/rustdoc-ui/check-cfg.rs @@ -0,0 +1,7 @@ +// check-pass +// compile-flags: --check-cfg=names() -Z unstable-options + +/// uniz is nor a builtin nor pass as arguments so is unexpected +#[cfg(uniz)] +//~^ WARNING unexpected `cfg` condition name +pub struct Bar; diff --git a/src/test/rustdoc-ui/check-cfg.stderr b/src/test/rustdoc-ui/check-cfg.stderr new file mode 100644 index 0000000000000..1db8e1d91c249 --- /dev/null +++ b/src/test/rustdoc-ui/check-cfg.stderr @@ -0,0 +1,10 @@ +warning: unexpected `cfg` condition name + --> $DIR/check-cfg.rs:5:7 + | +LL | #[cfg(uniz)] + | ^^^^ help: did you mean: `unix` + | + = note: `#[warn(unexpected_cfgs)]` on by default + +warning: 1 warning emitted + From a31ae159bc29ae26396160b1f3cb0fb358b4eae7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20BRANSTETT?= Date: Sun, 20 Feb 2022 17:13:38 +0100 Subject: [PATCH 2/2] Add documentation for `--check-cfg` in rustdoc book --- src/doc/rustdoc/src/unstable-features.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index c7fd5ed6fcb2e..141d5d2d2b2d0 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -512,3 +512,17 @@ crate being documented (`foobar`) and a path to output the calls To scrape examples from test code, e.g. functions marked `#[test]`, then add the `--scrape-tests` flag. + +### `--check-cfg`: check configuration flags + +This flag accepts the same values as `rustc --check-cfg`, and uses it to check configuration flags. + +Using this flag looks like this: + +```bash +$ rustdoc src/lib.rs -Z unstable-options \ + --check-cfg='names()' --check-cfg='values(feature, "foo", "bar")' +``` + +The example above check every well known names (`target_os`, `doc`, `test`, ... via `names()`) +and check the values of `feature`: `foo` and `bar`.