'cargo doc --open' seemingly does nothing if target is different from forced-target

[dramforever]

Problem

Currently if you have a forced-target (with -Zper-package-target) that's not the default, cargo doc --open builds the docs in target/{target_name}/doc but doesn't open it, which is confusing.

Steps

• Clone this repo: https://github.com/dramforever/cargo-doc-forced-target
• Make sure your default target isn't somehow riscv64gc-unknown-none-elf
• Run cargo doc --open

$ cargo doc --open
 Documenting forced-target v0.1.0 (/home/dram/tmp/cargo-doc-forced-target)
    Finished dev [unoptimized + debuginfo] target(s) in 0.20s
$ # Nothing opens

Possible Solution(s)

cargo doc --target riscv64gc-unknown-none-elf --open works. Maybe we can have cargo doc default to that for forced-target?

I originally encountered this in a workspace. I don't really know how this should interact with workspaces, but I think it should at least work if I explicitly choose cargo doc -p forced_target or use e.g. a --bin from it

Notes

No response

Version

cargo 1.69.0-nightly (82c3bb79e 2023-02-04)
release: 1.69.0-nightly
commit-hash: 82c3bb79e3a19a5164e33819ef81bfc2c984bc56
commit-date: 2023-02-04
host: x86_64-unknown-linux-gnu
libgit2: 1.5.0 (sys:0.16.0 vendored)
libcurl: 7.86.0-DEV (sys:0.4.59+curl-7.86.0 vendored ssl:OpenSSL/1.1.1q)
os: NixOS 23.5.0 [64-bit]

[weihanglo]

Thanks for the report!

Sounds like a good start to push that unstable feature forward. To fix it, we need to make this path respect not only forced-target but default-target as well. I haven't yet thought about the interaction too much but the behavior definitely needs to be defined before hand-on code.

Note that now Cargo can have multiple --targrt in a single cargo command invocation. Anyone who wants to help should take care of that.

[0xPoe]

@rustbot claim

I will try to support it.

[0xPoe]

Note that now Cargo can have multiple --targrt in a single cargo command invocation. Anyone who wants to help should take care of that.

For cargo doc, we only support one target.

➜  cargo-doc-forced-target git:(main) cargo doc --target riscv64gc-unknown-none-elf  --target aarch64-apple-darwin --open      
    Finished dev [unoptimized + debuginfo] target(s) in 0.10s
error: only one `--target` argument is supported

So probably we can just keep it.

[0xPoe]

@weihanglo Also, I found forced-target should conflict with default-target, right? I think we should bail out an error if we use it at the same time. What do you think?

[weihanglo]

@weihanglo Also, I found forced-target should conflict with default-target, right? I think we should bail out an error if we use it at the same time. What do you think?

Hmm… I don't think so. Perhaps a warning is sufficient. However, I feel like it is out of scope of this issue and not really worth putting effort on the warning for such an unstable feature.

[ehuss]

I'm wondering about what the correct behavior should be for this when there is a mixture of normal and target-specific crates. If cargo generates docs for different targets, then there isn't a way to navigate between them. From the user's perspective, the docs for the other targets are essentially invisible. (And which one gets opened is kinda arbitrary.)

I'm wondering if it would instead make sense to ignore the forced-target when generating documentation? A concern would be if there is target-specific documentation differences. But I would not expect those to be too common, and in theory #[doc(cfg)] is the long-term solution for platform-specific documentation.

What do people think?

[0xPoe]

I'm wondering about what the correct behavior should be for this when there is a mixture of normal and target-specific crates.

If we use -p to indicate a specific package, then I think we should open its docs for forced-target. Because this is consistent with the current building/generating behavior. I think us already down it correctly in #11804.
If we use -p or -workspace to indicate a bunch of packages, as you suggested in #11804 we should always try to find a document for the host target. I think it quite makes sense. Because there is nothing special about any one of those packages. Opening the first document targeting the host seems very intuitive.

I'm wondering if it would instead make sense to ignore the forced target when generating documentation.

I suppose this would be quite confusing that forced-target only works for build instead of generating documentation. Also, consider this issue, @dramforever wants to see documentation opened for the forced-target. Opening the document targeting the forced target seems also intuitive.