Better docs around environment variables
- Dominant language
- Java
- Stars
- 25.8k
- Forks
- 4.6k
- Avg merge
- 2d 18h
- Merged PRs (30d)
- 75
Description
### Description of the problem / feature request:
Environment variable handling is under-documented.
After trial-and-error, this is my understanding;
1. If `--incompatible_strict_action_env` (enabled by default) is disabled, then Bazel automatically passes `PATH`, `LD_LIBRARY_PATH`, and `TMPDIR` to actions that use `use_default_shell_env`.
2. `--action_env` passes environment variables to actions for the target configuration that use `use_default_shell_env`.
3. `--host_action_env` passes environment variables to actions for the exec configuration that use `use_default_shell_env`.
4. If `env` and `use_default_shell_env` of `ctx.actions` are both used, the former is ignored.
Assuming these statements are correct, they ought to be documented.
In particular, the following facts are missing from current docs:
(a) `use_default_shell_env` is required to pass any CLI-configured vars to actions.
(b) `use_default_shell_env` causes `env` to be ignored.
---
P.S. `use_default_shell_env` is an awkward name, because it actually has nothing to do with shells.
Contributor guide
Research direction
Start by locating the current documentation for --incompatible_strict_action_env, --action_env, --host_action_env, and use_default_shell_env. Verify the four listed behaviors against the existing documentation, then update it to explain CLI-configured variables and the interaction with env; done means these facts and the naming concern are addressed clearly.
Written by the indexing model from the issue text.
Assessment
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100