Doctests should not inherit features

[peter-lyons-kehl]

Code

Have a crate that

• has feature(s), like with Cargo.toml:

  ❯ cat Cargo.toml 
   [package]
   name = "macro_def"
   version = "0.1.0"
   edition = "2024"
    
   [dependencies]
    
   [features]
   macro_def_cfg = []

• exports a macro_rules! that (incorrectly, of course) generates code conditional on such feature(s), like

     #[macro_export]
     macro_rules! generate_unknown_cfg {
       () => {
           #[cfg(feature="macro_def_cfg")]
           let _ = {};
        }
     }

• have a doctest in that crate
  • containing #![forbid(unexpected_cfgs)] (or a deny), and
  • invoking that macro

    /// ```
    /// #![forbid(unexpected_cfgs)]
    ///
    /// use macro_def::generate_unknown_cfg;
    ///
    /// let _: () = {
    ///     generate_unknown_cfg!();
    /// };
    /// ```    
    

• OR, if the doctest itself doesn't define forbid or deny, then have the crate's src/lib.rs contain: #![doc(test(attr(forbid(unexpected_cfgs))))] (or a deny)

```

Reproduction Steps

cargo test

Expected Outcome

---- src/lib.rs - generate_unknown_cfg (line 3) stdout ----
error: unexpected `cfg` condition value: `macro_def_cfg`
 --> src/lib.rs:8:5
  |
8 |     generate_unknown_cfg!();
  |     ^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: no expected values for `feature`

---- YES, expecting NO features to be inherited from the crate

  = note: using a cfg inside a macro will use the cfgs from the destination crate and not the ones from the defining crate
  = help: try referring to `generate_unknown_cfg` crate for guidance on how handle this unexpected cfg
  = help: the macro `generate_unknown_cfg` may come from an old version of the `macro_def` crate, try updating your dependency with `cargo update -p macro_def`
  = note: see <https://doc.rust-lang.org/nightly/rustc/check-cfg/cargo-specifics.html> for more information about checking conditional configuration
note: the lint level is defined here
 --> src/lib.rs:1:11
  |
1 | #![forbid(unexpected_cfgs)]

Expecting this error, because as https://doc.rust-lang.org/nightly/rustdoc/write-documentation/the-doc-attribute.html#testno_crate_inject clearly implies that doctests are build in a separate crate. PLUS, since doctests can't test non-public functionality, they shouldn't inherit any features at all.

Actual Output

Compiles fine - so it hides the error in the macro.

Version

1.89.0 (and probably also older); 1.91.1; and December 1, 2025 nightly

[peter-lyons-kehl]

Example at https://github.com/peter-lyons-kehl/unexpected_cfgs_in_doctests

git clone https://github.com/peter-lyons-kehl/unexpected_cfgs_in_doctests
cd unexpected_cfgs_in_doctests
cd macro_use
cargo check
# -> error: unexpected `cfg` condition value: `macro_def_cfg`
#    -- GOOD: error as it should be

cd ../
cd macro_def
cargo test
# BAD: both two test pass, even though the macro generates an incorrect #[cfg(...)] conditional incorrectly based on the crate's feature(s)

[peter-lyons-kehl]

Of course, changing the current behavior would be a breaking change for any doctests that would use features in the actual doctest code themselves.

If such a change would be a problem (and we don't want this to change across edtitions), or if the current behavior is so by design, could we have some flag or a doctest-only lint to warn/deny/forbid this?

[jyn514]

i suspect this is because of doctest merging; you can check by changing edition to 2021 and seeing if that changes the behavior.

cc @GuillaumeGomez

[GuillaumeGomez]

I confirm, gonna take a look when I have time.

[fmease]

This has nothing to do with doctest merging.

We simply forward certain classes of CLI options from rustdoc to the compiler that builds a given doctest. This list has grown in recent times but I honestly don't know the underlying "admission criteria" (we almost certainly don't want to forward every single option (that's actually one of my bigger worries when it comes to #141083 wrt. feasibility)).

Namely: --cfg, --check-cfg, -L, --extern, -C*, -Z* & everything passed via --doctest-build-arg (source).

So this works as intended and it would indeed be a breaking change to cease forwarding --cfg. I haven't thought much about this yet, so I don't know what would be more useful in practice: Forwarding --cfg or not. Theoretically we could of course add yet another flag to somehow control this automatic forwarding at the cost of complexity & a potential risk of tying rustdoc (even more) to some of its implementation details.

[peter-lyons-kehl]

Thank you all.

The only use case not to forward --cfg that I can think of is macros. But even there it would only help detect a bug in the macro (as in my example) earlier. Such a bug would be detected outside of doctests sooner or later (in "real" crates). So closing this as not planned.