External Issue: Need user docs for new CHPL_LLVM build requirement

17638, "PHHargrove", "Need user docs for new CHPL_LLVM build requirement", "2021-05-04T22:53:40Z"

This issue is a continuation of a thread of comments in pull request #17615 . I will repeat the main points here for convenience.

Since the merge of pull request #17615, our CI testing against chapel's master fails with the following when running make to build the runtime (except when CC/CXX are clang/clang++):

gmake[1]: Entering directory `/[...]/chapel'
Making the compiler...
rm -rf /[...]/chapel/third-party/llvm/install/none
cd llvm && /usr/bin/gmake
Error: Please set the environment variable CHPL_LLVM to a supported value.
Supported values are:
  1) 'none' to build without LLVM support
  2) 'bundled' to build with the LLVM packaged in the third-party directory
  3) 'system' to use a pre-installed system-wide LLVM
See: https://chapel-lang.org/docs/latest/usingchapel/chplenv.html#chpl-llvm
gmake[4]: *** [none] Error 1
gmake[3]: *** [/[...]/chapel/third-party/llvm/install/none] Error 2
gmake[2]: *** [compiler] Error 2
gmake[1]: *** [comprt] Error 2
gmake[1]: Leaving directory `/[...]/chapel'

I have one minor and one major "issue" with the current state of affairs when I do not set CHPL_LLVM (which "just worked" for me before).

The minor issue is my confusion at having configure print CHPL_LLVM: none and the subsequent make command tell me I must set it to one of a list of values which includes the same none which was reported by configure.

The major issue is that I don't see user-facing documentation describing how pick one of the three options to resolve the demand to set CHPL_LLVM. At a minimum I'd like to know the PROs and CONs of the three options, and some explanation of the prerequisites for system. I think that, in terms of current docs, at least usingchapel/QUICKSTART.rst, usingchapel/prereqs.rst and technotes/llvm.rst probably need revisions (though there may be others). Related to this, the prior comment thread mentions that bundled is the default if "bundled is already built" (emphasis mine), implying to me that there may be an additional step needed in the quickstart.

I'd be satisfied with seeing the two items above addressed, but also want to take a moment to enquire about the motivation to switch from something that "just worked" on every system I've attempted to use, to a requirement to explicitly select an option? Why, for instance, is bundled not the default if the prereqs for system are not satisfied?