cargo doc --open hijacks terminal if browser is not already opened

[Seeker14491]

When the command cargo doc --open is invoked while the user's browser is not open, the browser is started in a non-detached manner, and the user's terminal blocks until the browser is closed. This is in contrast to running the same cargo doc --open command with a browser already open, in which case the terminal does not block.

This discrepancy is confusing, and having your terminal blocked is annoying, as you're now forced to either open another terminal instance or close the docs before you can input any commands. Therefore I propose cargo doc --open never block the user's terminal.

I tested on Windows 10 and Linux, and observed the same behavior on both platforms.

[dwijnand]

I couldn't reproduce this with macOS and Chrome. Whether my browser is already opened or not I get the docs and an unblocked terminal:

09:03:29 $ cargo doc --open
    Finished dev [unoptimized + debuginfo] target(s) in 0.24s
     Opening /d/cargo/target/doc/cargo/index.html
   Launching open

09:03:30 $

[Seeker14491]

Looking at the code that handles opening the docs, different code is executed for Windows, Mac, and other platforms, which explains why Mac isn't affected.

[Seeker14491]

I've got a fix for Windows; I'll look into fixing it on Linux and then send a pull request.

[dwijnand]

Nice one. Thanks @Seeker14491! (I was going to suggest copying what rustup uses)

[Seeker14491]

@dwijnand great idea about looking at rustup. Indeed, the rustup doc command doesn't have this bug. This is the code that handles opening a path in the browser in rustup: link. The Windows code there takes quite a different approach, calling a Windows API function. I'm not sure what the benefit is over the simpler approach taken by cargo. The fix I implemented was simply replacing cmd /C with explorer in the Windows code.

[Seeker14491]

This rustup commit contains justification for going the Windows API route, so I suppose we should do the same. I don't like the idea of just copy-pasting the code though; I think it would be better if cargo and rustup used the same code to handle this by pulling in a crate like webbrowser. webbrowser doesn't use the Windows API method though, so I'd want to change it so that it does before we use it. Does this sound like a good idea?

edit: There is also the open crate.

[dwijnand]

WDYT @alexcrichton and @Diggsey? Should we lift what Rustup does into a crate and reuse it here?

[Diggsey]

I'd be happy to accept a PR to rustup pulling this functionality out into a crate, assuming it is at least as functional.

[alexcrichton]

Seems reasonable to me!

[Seeker14491]

I've published the opener crate. I've run into a problem when integrating it into cargo though, namely, the browser will not open at all on Windows! I believe this is due to Cargo's Windows-specific handling of killing its child processes when it exits, an issue similar to what's happening in #5598. If I add in a 10 second sleep after calling the open doc function, the browser opens, but then abruptly closes after the 10 seconds.

[alexcrichton]

@Seeker14491 oh that's #5598 I believe which I believe we can indeed fix!

[siddharthgpta]

I don't know if this is being tracked in a separate issue, but I see this behavior on my MacBook when running:
BROWSER=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome cargo doc --open

MacOS: 12.2.1 (21D62)
Model: MBP 16" M1 Pro
Cargo: 1.59.0 (49d8809dc 2022-02-10)