bazelbuild / bazelbuild/bazel

Better docs around environment variables

Open
#14,692 3 comments 0 reactions 0 assignees View on GitHub
help wanted P2 team-Documentation team-Remote-Exec type: documentation (cleanup)
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.