rust/library/std
Matthias Krüger 13790bec6a
Rollup merge of #109272 - schneems:schneems/add-docs-to-command-env-methods, r=Amanieu
Add Command environment variable inheritance docs

The interaction between the environment variable methods can be confusing. Specifically `env_clear` and `remove_env` have a side effects not mentioned: they disable inheriting environment variables from the parent process. I wanted to fully document this behavior as well as explain relevant edge cases in each of the `Command` env methods.

This is further confused by the return of `get_envs` which will return key/None if `remove_env` has been used, but an empty iterator if `env_clear` has been called. Or a non-empty iterator if `env_clear` was called and later explicit mappings are added. Currently there is no way (that I'm able to find) of observing whether or not the internal `env_clear=true` been toggled on the `Command` struct via its public API.

Ultimately environment variable mappings can be in one of several states:

- Explicitly set value (via `envs` / `env`) will take precedence over parent mapping
- Not explicitly set, will inherit mapping from parent
- Explicitly removed via `remove_env`, this single mapping will not inherit from parent
- Implicitly removed via `env_clear`, no mappings will inherit from parent

I tried to represent this in the relevant sections of the docs.

This is my second-ever doc PR (whoop!). I'm happy to take specific or general doc feedback. Also happy to explain the logic behind any changes or additions I made.
2023-04-14 21:11:11 +02:00
..
benches
primitive_docs
src Rollup merge of #109272 - schneems:schneems/add-docs-to-command-env-methods, r=Amanieu 2023-04-14 21:11:11 +02:00
tests Exclude SGX from create_dir_all_bare test 2023-02-21 18:33:20 +00:00
build.rs socket ancillary data implementation for FreeBSD (from 13 and above). 2023-03-27 16:48:41 +01:00
Cargo.toml Update compiler-builtins to 0.1.91 to bring in msp430 shift primitive fixes. 2023-03-30 00:39:49 -04:00