doc PEX_* env vars

[lahosken]

A question came up on a pants-devel thread for which the answer was "use PEX_ROOT". https://groups.google.com/forum/#!topic/pants-devel/HKgKqUIUUIk . To explain it, JSirois had to link to two places: a docstring that mentions the pex_root property and the pex_root-property code that checks the env for PEX_ROOT. I dunno how often questions come up around these; if the answer is "often", then it probably makes sense to describe them in a doc somewhere.

'PEX_ALWAYS_CACHE'
'PEX_COVERAGE'
'PEX_FORCE_LOCAL'
'PEX_INHERIT_PATH'
'PEX_INTERPRETER'
'PEX_MODULE'
'PEX_PROFILE'
'PEX_PROFILE_ENTRIES'
'PEX_PROFILE_SORT'
'PEX_ROOT'
'PEX_TEARDOWN_VERBOSE'
'PEX_VERBOSE'

[lahosken]

snippet from some wickman-mail

To get information about the environment bootstrapping
PEX_VERBOSE=1 ./foo.pex

To drop into an interpreter w/ the environment bootstrapped:
PEX_INTERPRETER=1 ./foo.pex

There's a few other environment variables you can set but those are two handy ones.

[esazhin]

+1 we had to dig into the code to find the way of specifying the folder where the .pex folder can be created.

[wickman]

this is now more discoverable via pex --help-variables. is this sufficient to close the issue?

[areitz]

I think it would also be good to add some notes about this to a doc. Two obvious candidates are the README.rst in the root of the pex repo, and this page on the pants site:

http://pantsbuild.github.io/python-readme.html#manipulating-pex-behavior-with-environment-variables

[jhermann]

Might be a good idea to also make this available for the PEX files themselves, in the form of a '--pex--help-variables' option. I think the '--pex--' prefix thoroughly ensures there are no naming conflicts to a contained script and its options.

[jsirois]

@areitz's suggestion has long since been covered by the pex docs, in particular: https://docs.pex-tool.org/api/vars.html

@jhermann's suggestion is a bit tricker. Although Pex does carve out PEX* env var space, as is common in tools, it carves out no command line argument space for PEX files. I'd like to keep it that way. Considering, even if PEX files did support --pex--help-variables, you'd still have to know about that magic flag in the 1st place to get the help output by the PEX instead of running its entry point, having to know the 1 magic PEX_HELP_VARIABLES (or even just PEX_HELP) env var would have the exact same size barrier to entry. I think Larry's suggestion has been fully addressed; so I'll close this issue and let @jhermann open a feature request for PEX_HELP support if he wants.