document the platform-specific behavior of Command::current_dir

[oconnor663]

See also #37868.

Here's my initial wording:

Note that if the program path is relative (e.g. "./script.sh"), the interaction between that path and current_dir varies across platforms. Windows currently ignores current_dir when locating the program, but Unix-like systems interpret the program path relative to current_dir. These implementation details aren't considered stable, and it's recommended to call canonicalize to get an absolute program path instead of using relative paths and current_dir together.

I'd like to get feedback on:

• Should we consider those details stable? It might be disruptive to change them, regardless of what I can get away with claiming in docs :)
• Is canonicalize an appropriate recommendation? As discussed in std::process::Command's current_dir behaves differently on Unix and Windows, with respect to relative exe paths #37868 above, there are reasons it's not called automatically in the Command implementation.

[rust-highfive]

r? @aidanhs

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

[frewsxcv]

Should we consider those details stable? It might be disruptive to change them, regardless of what I can get away with claiming in docs :)

cc @rust-lang/libs w.r.t. this question

[alexcrichton]

I would personally prefer not to document this in the sense that it makes it a larger hazard to fix in the future. Ideally we'd fix this as opposed to documenting the bug as expected behavior

[SimonSapin]

Without documenting specifics of the current behavior, maybe we should still document that the interaction (or lack thereof, either way) of current_dir with relative command paths should not be relied on?

[oconnor663]

Do we know what fix we want? This might not be specifically the ticket to discuss it, but I'm partial towards "have the Unix implementation call canonicalize, and in the unlikely event that it fails, fall back to best-effort-just-using-strings-ignoring-symlinks canonicalization." Would that worry anyone?

[alexcrichton]

I'm not sure what sort of fix we want, but I like @SimonSapin's idea of basically documenting that this is a hazard and should likely be avoided as opposed to documenting specific behavior.

[oconnor663]

I've changed the wording and rebased:

If the program path is relative (e.g. "./script.sh"), it's ambiguous whether it should be interpreted relative to the parent's working directory or relative to current_dir. The behavior in this case is platform specific and unstable, and it's recommended to use canonicalize to get an absolute program path instead.

[alexcrichton]

@bors: r+

Thanks!

[bors]

📌 Commit 2842027f860ecd731eb0f38e28a10f9e7a8d7fa2 has been approved by alexcrichton

[oconnor663]

@alexcrichton is it normal for bors to take a week to merge something? Anything I need to fix?

[alexcrichton]

@bors: r+

hm it seems bors forgot about this PR!

[bors]

📌 Commit 0945b74 has been approved by alexcrichton

[bors]

⌛ Testing commit 0945b74 with merge ca63a4e...

[bors]

☀️ Test successful - status-appveyor, status-travis
Approved by: alexcrichton
Pushing ca63a4e to master...