Problem
Some packages such as llvm-sys have workarounds that allow their docs to build on docs.rs despite the fact that no usable binary can be generated (in this case because it relies on a platform binary that is not present on docs.rs). Essentially it uses detection of #[cfg(doc)] to allow builds to succeed when they would otherwise fail. This works well today.
However, when this project is a dependency in another project, cargo doc will not just run rustdoc, it will also invoke rustc to perform a check build. This bypasses any #[cfg(doc)] protections because it runs without --cfg doc. It is currently not possible to detect that your crate is being compiled in check mode as part of a larger doc run. The desired build characteristics, however, are the same. We don't need a working binary, and we're invoking the compiler for the purpose of docs.
It's also very strange to have a case where cargo doc works on a project but not when that project is a dependency.
I've produced a minimal example of this that demonstrates the issue without all the cruft of thinking about LLVM and system dependencies.
Steps
- Clone
djrenren/cargo-doc-failure
cd appcargo rustdoc
Notice this fails while cargo rustdoc in the dependency succeeds.
Current Workarounds
Local workaround:
$ RUSTFLAGS="--cfg doc" cargo doc
Docs.rs workaround:
Cargo.toml:
[package.metadata.docs.rs]
rustc-args = [ "--cfg" , "doc"]
Suggested Solution(s)
-
As suggested in the title of the issue, pass the doc config flag in while doing check builds as part of cargo rustdoc
-
Provide a standard way to add cfg flags to libraries when built as part of rustdoc. That is, standardize what docs.rs already does so that it works locally as well.
Notes
This occurs on all cargo versions I've been able to find so the version is largely irrelevant, but let's say latest stable 1.47.0
Passing a doc flag by default to check builds could produce strange results if downstream crates use doc cfg's to change the interface of their crate, which may be a point in favor of solution 2.
Problem
Some packages such as
llvm-syshave workarounds that allow their docs to build on docs.rs despite the fact that no usable binary can be generated (in this case because it relies on a platform binary that is not present on docs.rs). Essentially it uses detection of#[cfg(doc)]to allow builds to succeed when they would otherwise fail. This works well today.However, when this project is a dependency in another project,
cargo docwill not just runrustdoc, it will also invokerustcto perform a check build. This bypasses any#[cfg(doc)]protections because it runs without--cfg doc. It is currently not possible to detect that your crate is being compiled incheckmode as part of a largerdocrun. The desired build characteristics, however, are the same. We don't need a working binary, and we're invoking the compiler for the purpose of docs.It's also very strange to have a case where
cargo docworks on a project but not when that project is a dependency.I've produced a minimal example of this that demonstrates the issue without all the cruft of thinking about LLVM and system dependencies.
Steps
djrenren/cargo-doc-failurecd appcargo rustdocNotice this fails while
cargo rustdocin the dependency succeeds.Current Workarounds
Local workaround:
$ RUSTFLAGS="--cfg doc" cargo docDocs.rs workaround:
Cargo.toml:
Suggested Solution(s)
As suggested in the title of the issue, pass the doc config flag in while doing check builds as part of
cargo rustdocProvide a standard way to add
cfgflags to libraries when built as part of rustdoc. That is, standardize what docs.rs already does so that it works locally as well.Notes
This occurs on all cargo versions I've been able to find so the version is largely irrelevant, but let's say latest stable 1.47.0
Passing a doc flag by default to check builds could produce strange results if downstream crates use doc cfg's to change the interface of their crate, which may be a point in favor of solution 2.