18150, "ghbrown", "Modification to build and install instructions/docs", "2021-08-03T02:42:15Z"
I recently encountered the apparently common "issue" of the Chapel command (chpl) not persisting across sessions, and opened a thread about it on the Discourse (here). Brad was kind enough to reply, and suggested the conversation be moved here and perhaps expanded in scope a bit.
The thrust of this issue as I see it is to discuss how to make Chapel relatively simple to test drive and install, even for those not intimately familiar with *nix, shells, and building/installing form source. This may involve unifying the various install guides in the docs, or just providing a bit more/less information and relevant links where necessary.
A Focused Look At My Issue
As an example of why the existing documentation may not be satisfactory is my path to the non-persistence error and subsequent resolution:
interested in Chapel and want to try it out ->
Google "Chapel install" or similar ->
go to first result (Download Chapel) ->
using Linux, so get the tar then follow link to Quickstart guide ->
this page has no reference to ./configure or make install so chpl does not persist ->
Google issue of no persistence * ->
find relevant GitHub issue on Chapel (here) ->
use make install (SOLVED)
*Technically, a link to the contents of building.rst IS on the Quickstart page, but it's halfway through a large table at the bottom of the page and is labeled as "for more information". Suffice it to say this link certainly does not stick out.
I think a preferable path might look like:
interested in Chapel and want to try it out ->
Google "Chapel install" or similar ->
go to first result (Download Chapel) ->
using Linux, so get the tar then follow link to Quickstart guide ->
see note about how persistent install requires following instructions in Building Chapel ->
these instruction include ./configure and make install (DONE)
A Slightly Broader Discussion
Reflecting on the situation and looking at things a little more closely, I think the main stumbling block is the Quickstart step. I'm not clear on the target demographic for the Quickstart. Who is spending their time on a full make (or a full make with third party packages) just to end up with a single terminal instance of the Chapel compiler? If they somehow use that single terminal instance to determine they like Chapel and want to install, they're directed to the full build instructions that seem to have them go through the make and make check again, finally getting to a make install at the very end. Brad mentioned most Chapel "pros" historically haven't used a configured and installed version of Chapel, bust since I have no idea what that leaves them to do, perhaps I'm way off base with this paragraph
Of course I'm not intimately familiar with the Chapel project, but the most sensible and familiar thing for many people might be to just combine Quickstart and Building Chapel into a comprehensive build and install guide (perhaps mentioning the user can try things out before make install). make install would just be the final step of this unified guide, making chpl persistent/adding it to the path.
Any thoughts on streamlining and improving the make and install documentation would be appropriate here. Brad already gave a preliminary suggestion in the Discourse (with the caveat that he'd like to look at the docs more closely):
My own quick reaction to this is that we should pare the quickstart instructions back to the bare minimum to get a quick start, and then quickly defer to the more detailed documents (like "building") for follow-on information like "if you want the preferred configuration / if you want to install Chapel".
but any related and general discussion would be great.