docs: clarify path search behavior in std::process::Command::new#153469
docs: clarify path search behavior in std::process::Command::new#153469rust-bors[bot] merged 2 commits intorust-lang:mainfrom
Conversation
rustbot
added
S-waiting-on-review
|
r? @joboet rustbot has assigned @joboet. Use Why was this reviewer chosen?The reviewer was selected based on:
|
This comment has been minimized.
This comment has been minimized.
Albab-Hasan
force-pushed
the
doc/command-path-search-behavior
branch
from
f2c6cb2 to
4d5ce27
Compare
|
r? @ChrisDenton |
|
|
There was a problem hiding this comment.
The tricky bit here is that we do want to reserve the right to change it in the future. At this point the Windows implementation is mostly for historic reasons. It was in a fairly broken state for awhile and while that has now been cleaned up, I'm not sure it's in the end state we want (then again. I'm not sure how much we can change it without breaking people).
I'm going to nominate this for libs-api to at least discuss the Unix behaviour. I'm not sure how much we want to guarantee there.
ChrisDenton
added
the
I-libs-api-nominated
|
@ChrisDenton would a caveat on windows + keeping Unix as is address your concern or do you want unix stripped back too? just want to know your opinion. gladly will wait for libs api decision. |
|
There are a wide variety of Unix (and unix-like) systems so my personal instinct would favour being cautious about what we guarantee. But that is a very tentative opinion. And I do think it's useful to document the current behaviour in any case. |
|
This was discussed today in today's @rust-lang/libs-api meeting. It was felt we should keep the option open to make changes in the future, even for Unix where changes are much less likely. Could you move this under the "Platform-specific behavior" heading and start with a paragraph that says these details may change in the future? |
Albab-Hasan
force-pushed
the
doc/command-path-search-behavior
branch
from
4d5ce27 to
97761a0
Compare
|
This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed. Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers. |
|
@ChrisDenton moved everything under "# Platform-specific behavior" and added the "may change" caveat like you said. also corrected the windows search order. the application directory step was missing from my original. verified against |
Co-authored-by: Chris Denton <[email protected]>
|
@ChrisDenton sorry dont even know how that ended up in the pr lol. probably forgot to clean it up after copy pasting from my notes |
ChrisDenton
removed
the
I-libs-api-nominated
|
Thanks for working on this. I've did a last check and this all looks good so... @bors r+ rollup |
rust-bors
Bot
added
S-waiting-on-bors
Rollup of 13 pull requests Successful merges: - #154882 (Gate tuple const params behind `min_adt_const_params` feature) - #155259 (explicit-tail-calls: disable two tests on LoongArch) - #155293 (fix arch names in cfg pretty printer) - #155314 (`BorrowedBuf`: Update outdated safety comments in `set_init` users.) - #153469 (docs: clarify path search behavior in std::process::Command::new) - #154765 (Clarify ascii whitespace exclusion of vertical tab in the doc) - #155172 (Some small nits for supertrait_item_shadowing, and additional testing) - #155279 (Test/lexer unicode pattern white space) - #155280 (Tests for precise-capture through RPIT and TAIT) - #155301 (Delete unused `rustc_trait_selection` errors.) - #155303 (remove ibraheemdev from review rotation) - #155304 (remove PointeeParser) - #155319 (Remove dead diagnostic structs.)
Rollup merge of #153469 - Albab-Hasan:doc/command-path-search-behavior, r=ChrisDenton docs: clarify path search behavior in std::process::Command::new the existing docs mentioned that `PATH` is searched in an "os defined way" and that it could be controlled by setting PATH on the command but never explained which `PATH` is actually used. on unix the key thing to understand is that when you modify the childs environment (via `env()`, `env_remove()`, or `env_clear()`), the `PATH` search uses whatever `PATH` ends up in the child's environment not the parents. so if you call `env_clear()` and forget to set `PATH`, you don't get the parents `PATH` as a fallback; you get the OS default (typically `/bin:/usr/bin`) which often won't find what you need. the three cases are now documented: - unmodified env: child inherits parents `PATH`, that gets searched - `PATH` explicitly set `via env()`: the new value is searched - `PATH` removed (`env_clear` or `env_remove`): falls back to OS default, not the parents `PATH` on windows rust resolves the executable before spawning rather than letting `CreateProcessW` do it. the search order is: childs `PATH` (if explicitly set) first then system-defined directories then the parents `PATH`. the existing note about issue #37519 is preserved. limitations in this doc: - the unix fallback path behavior ("typically `/bin:/usr/bin`") is verified for linux/glibc. behavior on macOS, BSD, and musl is similar in practice but not fully confirmed here. - the windows search order is summarized as "system-defined directories" which actually includes the application directory (the directory of the calling process's executable) as a distinct step before the system dirs that detail is omitted for brevity. - `posix_spawnp` `PATH` source (calling process environ vs envp argument) is ambiguous in the `POSIX` spec; the behavior here is inferred from the guard in `unix.rs` that bypasses `posix_spawn` when `PATH` has been modified. closes #137286 (hopefully)
4 participants
the existing docs mentioned that
PATHis searched in an "os defined way" and that it could be controlled by setting PATH on the command but never explained whichPATHis actually used.on unix the key thing to understand is that when you modify the childs environment (via
env(),env_remove(), orenv_clear()), thePATHsearch uses whateverPATHends up in the child's environment not the parents. so if you callenv_clear()and forget to setPATH, you don't get the parentsPATHas a fallback; you get the OS default (typically/bin:/usr/bin) which often won't find what you need.the three cases are now documented:
PATH, that gets searchedPATHexplicitly setvia env(): the new value is searchedPATHremoved (env_clearorenv_remove): falls back to OS default, not the parentsPATHon windows rust resolves the executable before spawning rather than letting
CreateProcessWdo it. the search order is: childsPATH(if explicitly set) first then system-defined directories then the parentsPATH. the existing note about issue #37519 is preserved.limitations in this doc:
/bin:/usr/bin") is verified for linux/glibc. behavior on macOS, BSD, and musl is similar in practice but not fully confirmed here.posix_spawnpPATHsource (calling process environ vs envp argument) is ambiguous in thePOSIXspec; the behavior here is inferred from the guard inunix.rsthat bypassesposix_spawnwhenPATHhas been modified.closes #137286 (hopefully)