Open Urhengulas opened 3 months ago
The reason for the failure is that the dev-dependencies do not get linked via --extern for unit tests, but they do get linked for integration tests.
Put a different way, that command is coercing the [lib]
build target to act as if its the "lib test" build target but dev-dependencies
are not available for the [lib]
target, causing it to fail.
For what you are trying to accomplish, you need the "lib test" build target to build and be documented. The documentation for cargo rustdoc --tests
says it should be documenting the "lib test" target. When running this locally, it seems it isn't and it seems the test target isn't getting --cfg test
passed which I would have assumed it would.
Something is off that cargo rustdoc
provides --test
/--tests
flag while cargo doc
doesn't. I am not sure if that was a deliberate design, though given that is a documented behavior, maybe a patch is needed.
@epage said:
The documentation for
cargo rustdoc --tests
says it should be documenting the "lib test" target.
Exactly, that is what confused me as well.
@weihanglo said:
given that is a documented behavior, maybe a patch is needed.
If someone guides me which parts of the code needs patching, I can take care of it.
The documentation is misleading because it is using the generic documentation used for all commands. It could be customized for cargo rustdoc
to be clearer at the expense of repeating some of the text.
There is no way to specify target selection commands to say "just the unittest of the library".
It is not possible for rustdoc to support documenting both the unittest of the library and the library itself (since it has the same crate name). It is intentional that this is not supported.
We could consider switching the library from just a normal library to a unittested library when specifying --tests
. One thing to be cautious about is whether or not fingerprinting would be able to differentiate that.
Something is off that
cargo rustdoc
provides--test
/--tests
flag whilecargo doc
doesn't. I am not sure if that was a deliberate design, though given that is a documented behavior, maybe a patch is needed.
I believe this was intentional. There weren't known use-cases at the time for documenting things in that manner.
btw a related discussion just started on Internals: https://internals.rust-lang.org/t/generating-a-documentation-for-tests/21442
We could consider switching the library from just a normal library to a unittested library when specifying --tests. One thing to be cautious about is whether or not fingerprinting would be able to differentiate that.
I've just barely started looking at this but I'm assuming remove_duplicate_doc
is what is taking care of that
https://github.com/rust-lang/cargo/blob/ef854d2f66df7bfcd803a6ca1cfa3b619603142c/src/cargo/ops/cargo_compile/mod.rs#L742-L757
To test fingerprinting, it would involve running cargo rustdoc && cargo rustdoc --tests && cargo rustdoc
and making sure it rebuilt in each case, rather than assuming the previous build was successful.
In order to check if remove_duplicate_doc
is the culprit, I ran CARGO_LOG=debug RUSTDOCFLAGS="--cfg test" cargo rustdoc
, but it does not contain "remove", which would be the case due to the tracing::debug!
in line 781.
Problem
I want to use
cargo rustdoc
to document code in my unit and integration test modules. Following command does the trick and generates the documentation I desire:BUT the command fails if I am using dev-dependencies in the unit tests, which I need to. It does not fail when using dev-dependencies in integration tests.
The reason for the failure is that the dev-dependencies do not get linked via
--extern
for unit tests, but they do get linked for integration tests.Steps
The use of the
rand
crate is random (š„), it fails with any dev-dependency.Possible Solution(s)
Linking dev-dependencies when documenting unit test would solve the problem for me.
Notes
No response
Version