[Chapel Merge] Reduce CHPL_HOME assumptions when running 'make do

Branch: refs/heads/main
Revision: 76e8cfe
Author: bradcray
Link: Reduce CHPL_HOME assumptions when running 'make docs' by bradcray · Pull Request #19753 · chapel-lang/chapel · GitHub
Log Message:

Merge pull request #19753 from bradcray/reduce-chpl-home-assumptions-in-chpldoc

Reduce CHPL_HOME assumptions when running 'make docs'

[reviewed by @lydia-duncan , and perhaps @mppf to an extent]

This makes two changes to 'make docs' to improve its robustness.
Specifically, it:

  • removes the need to have CHPL_HOME set when running
    make docs by changing $$CHPL_HOME references in our
    Makefiles into $(CHPL_MAKE_HOME) to leverage the existing
    Makefile technology for inferring CHPL_HOME

  • updates the logic I added in #19584 to work when make docs is
    run from a CHPL_HOME that is a symbolic link.

For this second bullet, the specific problem was that some of our
nightly test configurations use a symbolic link for CHPL_HOME and
were failing when running make docs because the logic in
#19584 relied on distinguishing internal modules from others by
comparing the paths to the modules to the compiler's value of
CHPL_HOME. When symbolic links were involved, there was the
chance that the paths wouldn't match even though they referred
to the same file, causing us to mis-classify internal modules as

Here, the fix is to add a '--home' developer flag to 'chpldoc', similar
to the one supported on 'chpl' which permits the user to specify
the value of CHPL_HOME that should be used by the compiler.
Then, within the Makefile for chpldoc-ing the modules, we use the
Makefile's CHPL_MAKE_HOME variable when specifying the
values for both --home and the paths to the internal modules to
ensure they match. During discussion, Michael pointed out that
a similar-but-different approach would've been to support a
--noindex-module-prefix flag, letting us do something like
chpldoc --noindex-module-prefix internal and then use relative
paths like internal/Foo.chpl and standard/Bar.chpl rather than
requiring the absolute paths for the internal modules.

Modified Files:
M compiler/include/driver.h

M compiler/main/commonFlags.h
M compiler/main/docsDriver.cpp
M compiler/main/driver.cpp
M doc/Makefile
M modules/Makefile

Compare: https://github.com/chapel-lang/chapel/compare/5bdc0a45a44d...76e8cfe006bf