Documentation "nits" related to new configure/build infrastructure

[Paul Hargrove]

We have identified the following which should be addressed in our documentation prior to the 2020.3.0 release:

• In the configure section of INSTALL.md, where it mentions existence of platform-specific instructions, place a list of the those platforms (intra-doc links would be great, but bitbucket doesn't render them right).
• Probably move Cray XC ahead of Linux and macOS in the order of platform-specific instructions.
• Maybe apply "Quick Start Guide" approach to identifying key points for XC (--with-cross) and macOS (Xcode CLT). Not clear if this would be part of INSTALL.md or a document to be read before it.
• make gasnet … has been implemented but not documented anywhere (Makefile comments don't count). This is intended for troubleshooting, and as such may belong in a new markdown document.

I have self-assigned, but may delegate some of the items above and/or ask for editing help in PR.

[Paul Hargrove]

I have created pull request 154 to address the first two items, related to the platform-specific configure instructions in INSTALL.ms

EDIT/UPDATE: pull request 154 was merged

[Paul Hargrove]

Regarding 'Maybe apply "Quick Start Guide" approach...'

The Requirements section of INSTALL.md is already providing much of the information I'd expect in a Quick Start Guide.
So, perhaps that section just needs some minor edits OR maybe this item can be dropped from the list.

[Dan Bonachea]

I'm fine with dropping the QuickStart guide, I was never convinced this was a good proposed organization.

We should consider augmenting the macOS section with the OS-specific mantra needed to enable debugging of codes (including UPC++ code):

sudo dscl . append /Groups/_developer GroupMembership <username> and DevToolsSecurity -enable

[Paul Hargrove]

Reading up on macOS debugger stuff I've pieced together the following using multiple soures:

IF DevToolsSecurity -enable run by an Administrator
THEN debugger attach by signed apps (of which lldbis one) will be allowed for any user
ELSE you see a prompt for the account name and password of a member of the Developer's group for every attach

So, the group membership thing is for cases where finer-grained access control is desired and STILL requires the permitted users to enter a p/w for every backtrace.

ADDITIONALLY, for many/most macOS developers the DevToolsSecurity -enable is normally a matter of answering Yes when Xcode asks permission to enable it.

Still hoping to find a single page (ideally at apple.com) that explains all of this in one place.

[Paul Hargrove]

My initial shot at macOS Developer Mode docs has been added to pull request 154

[Paul Hargrove]

Re: make gasnet ...

I am thinking that perhaps the existing debugging.md page might be expanded to include Troubleshooting.
If we do that, then we have a place for GASNet-level testing instructions.

It might not hurt to have a "how to write a usable bug report" section (though I am not signing myself up for that task).

[Paul Hargrove]

Merge of pull request 154 has resolved the first two items in the Description.
The 3rd item (which was "maybe" to begin with) has been dismissed in discussion.

Documentation for make gasnet ... remains unresolved.

[john bachan]

Here's a nit: There is an inconsistency in the docs and scripts on the abbreviation for OPTLEV vs OPTLVL. The new Paul system uses OPTLVL in code but claims OPTLEV in the docs. The only non-nobs occurrence of OPTLEV I found in a script is in "utils/system-checks.sh".

[Paul Hargrove]

re: OPTLEV / OPTLVL.
Yikes! Will correct the implementation to match the spelling used in the docs (and nobs usage) when able (hopefully tonight).

EDIT/UPDATE: Pull request 159 created to fix this.
EDIT/UPDATE: Pull request 159 has been merged.

[Paul Hargrove]

Documentation for make gasnet ...

I am not sure how to proceed on this (last remaining) item without some input.

I proposed (somewhere above) that the existing markdown page on Debugging could expand scope to include Troubleshooting. However, the more I think about that, the more I think that such a section (or new page) should cover higher-level things (like "did you try compiling with -g to enable assertions?") before getting down into the details of how to determine if your problem is at the GASNet-EX level. So, I am less sure I want to pursue this approach.

An alternative approach would be to include documentation on this capability in the same section of INSTALL.md in which we cover make check. In particular, it could be recommended for users who see failures from the run stage of make check as something to try before reporting the problem to us.

One final alternative that comes to mind is to leave this capability undocumented (at least for now) and just pul out the magic incantation(s) in user-support scenarios such as email and issue tracker. This approach may (depends on your point of view) have a benefit of ensuring that folks running GASNet-level tests are doing so after having engaged with us, ensuring they get instructions tailored to their circumstances.

Thoughts?

[Dan Bonachea]

the more I think that such a section (or new page) should cover higher-level things (like "did you try compiling with -g to enable assertions?")

Not sure what this comment is referring to - the very first suggestion (in bold) on the debugging page is to use -g debug mode.

One final alternative that comes to mind is to leave this capability undocumented (at least for now) and just pul out the magic incantation(s) in user-support scenarios such as email and issue tracker.

How about a compromise resolution - lets "pseudo-document" in docs/build-devel.md, so at least the people doing the support have this in our internal notes and don't need to go trolling through Makefiles to find the targets.

[Paul Hargrove]

With the merge of pull request 166 to update docs/build-devel.md, I declare this issue resolved.

Please reopen if the individual "nits" identified here have not been satisfactorily resolved (either w/ prose or dismissed in discussion here).

For new "nits", please open one or more new issues.