Run rustc with --cfg doc when analyzing dependencies in cargo doc.

[jmillikin]

Proposed fix for #8601

This is my first PR to Cargo and I am not familiar with the codebase. If this isn't implemented properly, please tell me and I'd be happy to make changes.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[ehuss]

Hi! Thanks for the PR! Unfortunately I don't think this is a change we can make, because it is backwards incompatible, and some libraries will fail with this change. Unfortunately, I don't have a very clear alternative for your issue. It may be possible to use cfg-if to create fall-throughs for unsupported platforms. Another option is to use the --target flag with cargo doc for one of the supported targets. Otherwise, I think this would require re-architecting how rustdoc works.

[jmillikin]

Thanks for the PR! Unfortunately I don't think this is a change we can make, because it is backwards incompatible, and some libraries will fail with this change.

I don't understand how this change would be backwards incompatible. The same crate gets passed to rustc and then to rustdoc, so if the presence of --cfg doc breaks compilation for a crate, I would expect that to manifest in the current behavior already.

Is it possible to give an example of a crate that would be broken (e.g. from a Crater run), or even a code snippet of something non-pathological that would be broken by this change?

[ehuss]

When rustdoc processes a crate, it doesn't do a full compilation like rustc does. Some examples where this can cause a problem:

• The standard library uses different modules based on cfg, and those modules will not link properly when, for example, documenting libtest.
• hyperbole uses different types based on cfg(doc) which won't build properly in rustc.
• The heim workspace uses deny(unused) which causes a hard error with cfg(doc) since that introduces unused items.

Generally, any circumstance where cfg(doc) is used around code that otherwise won't compile. For example:

#[cfg(any(windows, doc))]
/// Hello!
pub fn foo() {
    some_windows_only_crate::foo();
}

And you try to do cargo check on a non-windows platform with --cfg doc, it will fail since some_windows_only_crate won't exist. Rustdoc happily handles it since it mostly ignores the bodies of functions, but rustc will fail.

[jmillikin]

Would it be OK to run rustc twice? First using the current settings, then if that fails, again with --cfg doc?

[ehuss]

No, I don't think so. Some of the situations fail only when querying the rmeta information, so cargo wouldn't necessarily know which dependencies need to be rebuilt. That would also impose a large cost on all users when there are normal errors unrelated to this.

[jmillikin]

Hmm, that's frustrating, but I think I understand the compat issues now.

Is there any chance this might be available as a Cargo option (CLI flag, manifest field, env var...) or should I just try to find a different macro layout that Cargo can handle?

[ehuss]

Probably not. You can accomplish that today with RUSTFLAGS="--cfg doc" carg doc. Otherwise I would suggest trying some of the workarounds listed above.