search

chapel-lang / chapel

a Productive Parallel Programming Language
https://chapel-lang.org
Other
1.79k stars 421 forks source link

Document CHPL_LAUNCHER_* environment variables #20777

Open bradcray opened 2 years ago

bradcray commented 2 years ago

Chapel's launchers support a number of environment variables prefixed by CHPL_LAUNCHER that provide support for things like selecting a queue name, how much wall-clock time to permit, the job name, etc. These variables are not particularly deeply designed and haven't always been supported uniformly across launchers, but are very helpful nonetheless. Ultimately it'd be nice to unify and commit to these a bit more, as well as providing command-line options for specifying them. In the meantime, though...

Currently, the main way I learn about such variables is through word-of-mouth or by looking through the source code for the launchers. I think we should add some basic documentation for the options we think are most useful to help users out.

https://chapel-lang.org/docs/usingchapel/launcher.html is the place I was imagining this would live, and I am seeing some slurm-based CHPL_LAUNCHER options there, but not others. I imagine we'd keep any mentions of variables that we're not sure we're committed to short and sweet, and to label them as unstable. We could also imagine having the main launcher document point off to more specific documents about families of launchers like slurm-based, pbs-based, etc. if the main document got too unwieldy or monolithic; or if the options varied so much between launchers that it was hard to describe them here.

Recent catalysts for filing this issue are cases like https://github.com/chapel-lang/chapel/issues/20764 where, searching the docs, I don't see mention of the variables that formed the answer; or recent interactions with @sdbachman in which I was learning about options for PBS by reading source code.

bradcray commented 9 months ago

Hit this again this week when a user on Gitter asked for more control over queue and job names, so I found myself reading sources to remind myself about CHPL_LAUNCHER_QUEUE, CHPL_LAUNCHER_JOB_PREFIX, and CHPL_LAUNCHER_JOB_NAME.