cargo doc --open always respect request_kind

[0xPoe]

What does this PR try to resolve?

closes #11728

More details:

The open behavior is as follows:
cargo doc --open:

• Pick the first root unit that was built for host.
• If none found, pick the first one(whatever it's target is).

cargo doc --target TARGET --open:

• Pick the first root unit for the given target.
• If none found, pick the first one(whatever it's target is).

How should we test and review this PR?

See the unit test.

[rustbot]

r? @ehuss

(rustbot has picked a reviewer for you, use r? to override)

[0xPoe]

This PR still working in the process. I'll add a test later.

[ehuss]

My suggestion would be to have the following behavior:

• cargo doc --open:

  Pick the first root unit that was built for host.
  If none found, pick the first one.

• cargo doc --target TARGET --open:

  Pick the first root unit for the given target.
  If none found, pick the first one.

This may require extending the Compilation struct to include the necessary information. I would suggest iterating over the root units, filtering out the ones for documentation, and storing the required information (the name and kind).

[0xPoe]

• cargo doc --open:
  Pick the first root unit that was built for host.
  If none found, pick the first one.

How does it interact with forced-target?
My thought is:

1. if the root unit has forced-target, then open the docs of the first root unit built for forced-target.
2. If there is no forced-target, then open the docs of the first root unit built for the host.

• cargo doc --target TARGET --open:
  Pick the first root unit for the given target.
  If none found, pick the first one.

1. If the first root unit has forced-target and it same with --target TARGET, then he docs of the first root unit built for forced-target.
2. If it is conflict with --target TARGET bail out an error for it.
3. If there is no forced-target, then open the docs of the first root unit built for the TARGET.

[ehuss]

How does it interact with forced-target?

It depends, but for the most part the code should not know or care about forced-target. If there is only one root unit, then that's the one that gets opened (whether it is forced-target or not). If there are multiple, such as in a workspace, and one of those is forced-target and the other is not, then it will open the one that is not forced-target.

As for the "first" entry, that is completely arbitrary, and is currently alphabetical I believe.

The operation should be relatively simple, I think it would be something like:

root_units.iter().find(|unit| unit.kind == requested_kind).next().unwrap_or(root_units[0]);

That's a very rough sketch, but the general shape of what I think it should look like.

[0xPoe]

@rustbot author

[0xPoe]

Self check

[0xPoe]

@rustbot ready

[0xPoe]

@ehuss Do you have any suggestion about which target I should use in the test on the stable channel? Thanks!

[ehuss]

The cargo testsuite has various things to help with cross-compiling. At the start of the function, write:

    if cross_compile::disabled() {
        return;
    }

Then, for the target value, use cross_compile::alternate().

[0xPoe]

The cargo testsuite has various things to help with cross-compiling. At the start of the function, write:

    if cross_compile::disabled() {
        return;
    }

Then, for the target value, use cross_compile::alternate().

Thanks for your help! It works.

[dramforever]

Hi, just to confirm, cargo doc -p has-forced-target --open falls into the cargo doc --open case and would find the (only?) target has-forced-target and open its docs with the correct triple, is this right?

[ehuss]

Hi, just to confirm, cargo doc -p has-forced-target --open falls into the cargo doc --open case and would find the (only?) target has-forced-target and open its docs with the correct triple, is this right?

Yes.

[0xPoe]

Hi, just to confirm, cargo doc -p has-forced-target --open falls into the cargo doc --open case and would find the (only?) target has-forced-target and open its docs with the correct triple, is this right?

Added doc_and_open_virtual_manifest_one_project test for it.

[ehuss]

In thinking about this more, I came up with a concern with this approach, to be followed up at #11728 (comment).

[ehuss]

@rustbot blocked

[0xPoe]

@ehuss What should I do to help this PR move forward? Do you think we still need to wait for more discussion about this behavior?

[bors]

☔ The latest upstream changes (presumably #12252) made this pull request unmergeable. Please resolve the merge conflicts.

[rustbot]

☔ The latest upstream changes (possibly 081d7ba) made this pull request unmergeable. Please resolve the merge conflicts.