Document envvars affecting install/run-tests/upcxx-meta

Our install/run-tests/upcxx-meta scripts have a number of environment variables that critically affect their operation.

None of these scripts currently self-documents these settings (ie --help).

INSTALL.md gives a few isolated build recipes, but leaves out most of the needed information. We need to document the entire list of supported settings, in at least INSTALL.md and ideally eventually also in script --help output.

To my knowledge, the list of envvars currently includes at least the following:

UPCXX_THREADMODE={seq|par} @
UPCXX_BACKEND={gasnet1_seq,gasnetex_par} @
UPCXX_CODEMODE={O3|debug} @
OPTLEV={0,3} @
DBGSYM={0,1} @
UPCXX_GASNET_CONDUIT={smp|udp|aries} @
GASNET_CONDUIT={smp|udp|aries} @
GASNET=/path/to/external/gasnet
GASNET_CONFIGURE_ARGS=...
GASNET_INSTALL_TO=/path/to/install/gasnet
CROSS=cray-{aries,gemini}-{alps,slurm}
CC=/path/to/compiler
CXX=/path/to/compiler
LDFLAGS=...

Some are only valid/effective for some of the scripts.
Some are only effective/supported in certain contexts (eg install --single mode, or internal gasnet).
Some do similar things but have different key/value spellings based on context (those marked with "@")
Some possibly are not intended for end users at all. Given the current lack of docs, the user won't know which he is permitted/expected to set in what context.

We should eventually talk about cleaning up this somewhat haphazard set (eg using a uniform naming prefix and removing pointlessly duplicated settings), however given the release deadline we at least need to document what we have.

Initially assigning to John to provide the needed information here and either write the documentation himself or assign to someone else to do so.

CC: @PHHargrove

Comments (6)