Installation documentation in Programmer's Guide should use new recommended configure-make approach

[Scott Baden]

If you install UPC++ using the provided “install script” you’ll get a warning message the “install” script approach
is no longer recommended, that the recommended method is to use the familiar configure - make approach.

The Programmer's Guide makes no mention of the new recommendation.
The language in the guide should be in line with this new recommendation,
and properly deprecate the install-based approach, since new UPC++ features
may not be supported via this interface. 

INSTALL.md, at the top level of the UPC++ source tree, properly
recommends the new approach, and need not change

Lastly, install should no longer be supported in the future, to avoid the risk
that users will be unable to access future UPC++ developments

[Paul Hargrove]

Thanks, Scott, for reporting the out-of-date information in the Prog Guide.
We'll see about getting that updated in git and the online copy in the wiki as well.

I am not sure what you mean when you say the Guide should "properly deprecate the install-based approach". Can you clarify how/why you believe it should make any mention at all of the old approach?

As for "install should no longer be supported in the future".
That is already the plan, but the length of time for deprecation has not been discussed.
We'll probably remove it prior to the next release in September, but that has not decided for certain.

[Scott Baden]

Paul,

I think we are both on the same page.

My use of the word “properly” expressed the need to bring clarity to whether or not the install script would go away one day. Perhaps the word “appropriately” is more accurate.

Why not just modify the warning to say that, one day, the install script may go away and it’s use has been deprecated. Deprecation doesn’t require a schedule for removal, but it usually does imply. one, so I think you reasoning backs up that intenion and doens’t need to appear in print.

‌

My suggestion chage the current language

---

WARNING: This install script exists only to support legacy usage.
WARNING: New features in UPC++ may not be supported via this interface.
WARNING: Users are encouraged to use the 'configure; make; make install'
WARNING: steps as documented in INSTALL.md.

---

to the following (new language in bold)

---

WARNING: This install script exists to support legacy usage only.
WARNING: Since new features in UPC++ may not be supported via this interface,
WARNING: its use is therefore deprecated.
WARNING: Users should instead use the 'configure; make; make install'
WARNING: steps as documented in INSTALL.md.

---

[Paul Hargrove]

Proposed text updates appear in Prog Guide PR#26

That PR goes one step beyond the fix required for this issue to include an update for the not-yet-released cross-configure improvement (issue 353).

It is my hope that (only) the first commit of that PR be used to update the online Guide, but the mechanics of doing so have not yet been determined .

[Paul Hargrove]

The PG now correctly documents the new configure logic as it exists in the develop branch of upcxx