[Chapel Merge] Refresh QUICKSTART.rst and building.rst

Notifications Commits
1

Branch: refs/heads/main
Revision: 975007f
Author: bradcray
Log Message:

Merge pull request #18404 from bradcray/refresh-quickstart-building

Refresh QUICKSTART.rst and building.rst

[reviewed by @mstrout , @e-kayrakli , and @mppf]

Motivated by user issue #18150, I took an editing pass over QUICKSTART.rst and building.rst to refresh them for the upcoming Chapel 1.25 release. Specifically, my high-level goals were to:

  • keep QUICKSTART as lean and mean as possible while having it refer users to other places to avoid common traps
  • make sure that things were still as accurate as possible
  • promote the make install content a bit higher and address the challenge of using Chapel across multiple shells more directly
  • generally wordsmithed and smoothed things over

In more detail, In building.rst, I:

  • removed the reference back to QUICKSTART.rst in this file, promoting chplenv.rst in its place, because I think quickstart should be all about "quick and dirty" with building.rst and chplenv.rst being more about "the complete story in plenty of detail"
  • mentioned printchplenv in the opening paragraph for someone arriving in this file without going through chplenv.rst to understand what we mean by the Chapel environment
  • moved the comment about interpreting the output of make -v into actual text in the document because if someone needs this level of hand-holding, they may not know what a bash comment is and may type it in
  • fixed the updated path to chpl
  • fixed the prefix of the path to the libraries (while leaving the details vague)
  • moved the part about each make command only building the current configuration further down in the document
  • made the part about "now you can compile" allude to the next few sections so that people wouldn't stop reading prematurely (while still knowing that they had a working compile)
  • added a detailed section about using the built Chapel in other shells / terminals, because this is increasingly FAQ'd as we get more beginning users
  • fleshed out the section of ./configure + make install to be a bit more precise about how to use it. I can never remember, and I feel as though those commands currently require more than an ideal amount of expertise. I think we could go even further with hand-holding in these instructions, but I'm not quite clear I could do it justice (not really understanding the full behavior...), and hopefully this is a step in the right direction.
  • took out the paragraph about supported platforms because... what is that doing here? (and who wants to maintain it here)
  • added a section about switching between multiple configurations / supporting them in a single place
  • removed a big section about supporting a new compiler or platform by simply dropping in a Makefile. because I don't think the world is that simple anymore (at least on the compiler side of things)
  • tweaked some details and formatting and wordings in the Makefile-related sections

In QUICKSTART.rst, I:

  • started the document off with a bit more of "What the goal here is", referring people to the "official / full-fledged" instructions if they'd prefer to do that and trying to make the quickstart vs. full-featured branch clearer earlier. Overall, my hope is that most people will head into the quickstart instructions due to lack of patience, but that those patient enough to read these paragraphs may self select into the chplenv + building docs or perhaps jump directly to the preferred configuration if they don't want to waste time with a stripped-down version / are willing to deal with more detail. This also allowed me to make subsequent bullets shorter and sweeter (where my guess is that 80% of readers will just jump to step 0 and start typing stuff... I know I would).
  • changed from "expand" to "unpack" when talking about dealing with the .tar.gz
  • generally switched from hyperlinks that refer to filenames and section names to those that spell out the section (with the assumption that it looks better in web form and that that's where most people see it)
  • removed references to make check since it essentially builds and runs a program which is what the instructions are just about to suggest you do
  • switched hello.chpl to hello3-datapar.chpl just because it's more interesting; may produce more of a "wow!" factor when run; may lead people to look at what hellos 1-3+ are, etc.
  • removed the -o flag from the chpl command lines since we don't generate a.out anymore, so it seems redundant
  • tried to make the section about LLVM in the preferred configuration a bit clearer by breaking the options out into bullets
  • forked the part about using your build in other shells/terminals into its own section (for visibility given that it's FAQ'd) but then had it refer to the relevant section in building.rst to avoid duplication / keep this treatment short and sweet
  • fixed the link about performance tips to point to the more specific page
  • added a note for reassurance that we support the setchplenv scripts for the preferred mode for non-bash shells as well

Resolves #18150.

Modified Files:
M doc/rst/usingchapel/QUICKSTART.rst

M doc/rst/usingchapel/building.rst
M doc/rst/usingchapel/chplenv.rst

Compare: https://github.com/chapel-lang/chapel/compare/d22cf193cbb0...975007fca33a