Docs: add clarity around environment variables #18382
Conversation
lukedyer-peak
force-pushed
the
docs/environment-variables
branch
from
b7e4e54 to
b78f105
Compare
| @@ -68,6 +68,7 @@ Work is broken down into many small units and kept warm in a daemon so that as l | |||
| ### Hermetic execution | |||
|
|
|||
| Pants sandboxes all processes that it executes, ensuring that cache keys are always accurate, and builds are always correct. | |||
| This implies, amongst other things, processes can't access your local [environment variables](docs:reference-subprocess-environment) or even setting stored in your home directory (as this uses `HOME`). | |||
There was a problem hiding this comment.
The subprocess-environment references are only good for the Python backend today; so they risk sounding authoritative and yet being off-point. I think the best you can do is to encourage looking for where / how to pass environment variables for the context you're in. Maybe give the subprocess-environment as a qualified example of how you can do this for Python. N.B. that its not even always the right thing to do for Python! If the env var is only needed for tests, you can reduce scope with https://www.pantsbuild.org/docs/reference-test#extra_env_vars - and that works for any language stack, including Python.
Which is all just to say the concept is clear and easy to explain, the details are all over the place and very hard to explain without misleading folks / helping X% & confusing the heck out of Y%.
There was a problem hiding this comment.
To whit on narrowness of subprocess-environment applicability:
$ git grep SubprocessEnvironment
src/python/pants/backend/python/util_rules/pex_environment.py:from pants.core.util_rules.subprocess_environment import SubprocessEnvironmentVars
src/python/pants/backend/python/util_rules/pex_environment.py: subprocess_env_vars: SubprocessEnvironmentVars,
src/python/pants/core/util_rules/subprocess_environment.py:class SubprocessEnvironment(Subsystem):
src/python/pants/core/util_rules/subprocess_environment.py:class SubprocessEnvironmentVars:
src/python/pants/core/util_rules/subprocess_environment.py: subproc_env: SubprocessEnvironment.EnvironmentAware,
src/python/pants/core/util_rules/subprocess_environment.py:) -> SubprocessEnvironmentVars:
src/python/pants/core/util_rules/subprocess_environment.py: return SubprocessEnvironmentVars(
So no hits in java/scala/jvm/go, etc.
There was a problem hiding this comment.
Also worth noting is that for the tools Pants integrates with, config files from your HOME do get picked up where applicable without any additional configuration needed.
Add clarity to the docs to say that hermetic execution implies enviroment variables won't be passed in. Also add in the example that the
HOMEdirectory won't be able to be found and so global user settings will be ignored.