Introduce a interfaces to expose the current `Command` captured env var logic

[schneems]

Feature gate: #![feature(command_resolved_envs)]

This is a tracking issue for the API Change Proposal (ACP) rust-lang/libs-team#194.

This feature adds two methods to std::process::Command to expose environment variable resolution logic, addressing the inability to observe the effects of env_clear() and the lack of a single source of truth for environment variable resolution.

Public API

// std::process

impl Command {
    pub fn get_env_clear(&self) -> bool;
    pub fn get_resolved_envs(&self) -> CommandResolvedEnvs;
}

// `get_resolved_envs` returns a concrete iterator type:
pub struct CommandResolvedEnvs { /* .. */ }

impl Iterator for CommandResolvedEnvs {
    type Item = (OsString, OsString);
    // ..
}

Explanation:

• get_env_clear This makes sure people have all the information Command stores.
• get_resolved_envs This should include documentation that says it returns the environment as it would be if the command were executed at that point, and will not match if the environment is subsequently changed (including in a pre_exec hook). This avoids duplicating the Command logic.

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: rust-lang/libs-team#194
• Implementation:
  • get_env_clear: Add Command::get_env_clear #149074
  • get_resolved_envs: Add Command::get_resolved_envs #149362
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

Both questions raised at filing time have been resolved during implementation:

• Should this use impl Iterator in the return type, or a concrete iterator type? Resolved: get_resolved_envs returns a concrete iterator type (CommandResolvedEnvs), matching the precedent set by std::env::vars_os / std::env::VarsOs and leaving room to add impls such as Debug. See #149362 and this comment.
• Should we allow borrowing from std::process::Command (or other sources) in the returned iterator, rather than requiring (OsString, OsString) which implies fresh allocations for each environment variable and value on every iteration? Resolved: the iterator yields owned (OsString, OsString), consistent with std::env::vars_os. Anyone able to spawn a process can afford these allocations, which are negligible relative to process spawning.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[schneems]

Should this use impl Iterator in the return type, or a concrete iterator type?

I'm good with either, I picked impl Iterator based on comment from rust-lang/libs-team#194. I think naming is possibly an issue. I think if we want to add things to the implementation like Debug then we should go with concrete.

The closest existing API would be https://doc.rust-lang.org/std/env/fn.vars_os.html which returns https://doc.rust-lang.org/std/env/struct.VarsOs.html (concrete iterator)

Should we allow borrowing from std::process::Command (or other sources) in the returned iterator, rather than requiring (OsString, OsString) which implies fresh allocations for each environment variable and value on every iteration?

For my needs (OsString, OsString) is fine. I think any system where you can spawn a process you can allocate. If you're working with process spawning then I don't think string allocation will be a comparatively large bottleneck. Mentioned above that https://doc.rust-lang.org/std/env/struct.VarsOs.html returns (OsString, OsString).