RFR: 8294689: The SA transported_core.html file needs quite a bit of work [v4]

[Serguei Spitsyn]

On Sat, 8 Oct 2022 15:35:24 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

>> The main issues I set out to address are:
>> 
>> - legacy Solaris references can be removed
>> - add help with dealing with Windows core files, most of important of which is use of PATH to find the dlls referenced by the core file.
>> - add help with dealing with macOS core files, most of important of which is using JAVA_HOME or DYLD_LIBRARY_PATH to find the dlls referenced by the core file. 
>> 
>> However, in the end it turned out to be a pretty substantial restructuring and rewrite.
>> 
>> Here are links to the rendered old and new copies of the file:
>> [old file](https://htmlpreview.github.io/?https://github.com/openjdk/jdk/blob/master/src/jdk.hotspot.agent/doc/transported_core.html)
>> [new file rev1](https://htmlpreview.github.io/?https://github.com/openjdk/jdk/blob/6778a202a855a534754c4b47a6cd99cb912869d3/src/jdk.hotspot.agent/doc/transported_core.html)
>> [new file rev2](https://htmlpreview.github.io/?https://github.com/openjdk/jdk/blob/7448593f0a9142e5d99844f349b4d54819735540/src/jdk.hotspot.agent/doc/transported_core.html)
>> [new file rev3](https://htmlpreview.github.io/?https://github.com/openjdk/jdk/blob/ce5c808ca5af4e551bf78d593d865a1f228ad950/src/jdk.hotspot.agent/doc/transported_core.html)
>> [new file rev4](https://htmlpreview.github.io/?https://github.com/openjdk/jdk/blob/3b16e560499eb526d283a9c16531cc1c3f63394e/src/jdk.hotspot.agent/doc/transported_core.html)
>
> Chris Plummer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   some minor edits

Looks good to me.
I've posted several nits though.
Thanks,
Serguei

src/jdk.hotspot.agent/doc/transported_core.html line 66:

> 64:  set <b>SA_ALTROOT=/altroot</b>, then <b>/altroot</b> will be prepended to any path found
> 65:  in the core file, and also prepended to any subdir with the root part stripped off. For example,
> 66:  when looking up <b>/usr/lib/libfoo.so</b>, SA will try to find <b>/altroot/usr/lib/libfoo.so</b>,

Nit: Not sure if it makes sense to say: "SA will first try to find".

src/jdk.hotspot.agent/doc/transported_core.html line 70:

> 68: </p>
> 69: 
> 70: <h3>Using  transported core dumps on Windows</h3>

Nit: an extra space after "Using".

src/jdk.hotspot.agent/doc/transported_core.html line 89:

> 87: </p>
> 88: 
> 89: <h3>Using  transported core dumps on macOS</h3>

Nit: an extra space after "Using".

src/jdk.hotspot.agent/doc/transported_core.html line 91:

> 89: <h3>Using  transported core dumps on macOS</h3>
> 90: <p>
> 91: SA normally uses the path to the specified java executable to locate the JDK libraries. It will look in the following subdirectories for them (relative to the path to the specified java executable): <b>../lib</b>, <b>../lib/server</b>, <b>../jre/lib</b>, and <b>../jre/lib/server</b>. If not found in any of those locations, it will look in the same subdirectories relative to the <b>JAVA_HOME</b> environment variable, but using <b>JAVA_HOME</b> normally should not be necessary.

Nit: too long line - hard to review.

src/jdk.hotspot.agent/doc/transported_core.html line 95:

> 93: 
> 94: <p>
> 95: For locating the user JNI libraries, SA uses <b>DYLD_LIBRARY_PATH</b>. It can contain more than one directory separated by a colon. <b>DYLD_LIBRARY_PATH</b> can also be used for locating the JDK libraries, but it needs to specify the full path to the libraries. SA will not automatically search subdirs such as <b>lib/server</b> as it does for <b>JAVA_HOME</b>.

Nit: too long line - hard to review.

src/jdk.hotspot.agent/doc/transported_core.html line 99:

> 97: 
> 98: <p>
> 99: For locating the macOS libraries, SA uses <b>SA_ALTROOT</b> similar to the linux support, except it does not use it to map all the subdirs. It just appends <b>SA_ALTROOT</b> to the full path of each macOS library. So if you specify <b>SA_ALTROOT=/altroot</b>, SA will prepend <b>/altroot</b> to the full path of each macOS library. Note however, due to <a href="https://bugs.openjdk.org/browse/JDK-8249779">JDK-8249779</a> , SA will not even try to open macOS libraries, so at the moment there is no need to try to match up the macOS libraries by pointing to them with <b>SA_ALTROOT</b>.

Nit: too long line - hard to review.

-------------

Marked as reviewed by sspitsyn (Reviewer).

PR: https://git.openjdk.org/jdk/pull/10518