RFR: 8320258: Refresh building.md

[Erik Joelsson]

On Thu, 16 Nov 2023 17:40:36 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> The contents of the build README has been poorly kept up to date in places. With the move to Github, the need to have markdown syntax that looks good on Github has become apparent. The entire document has been in need for a while of a comprehensive oversight to be made more consistent in language and formatting.
> 
> Here is a summary of the most important changes:
> 
> * The entire section on cross-compiling have been restructured to be more logical, and some parts have been rewritten, so it reads more coherent.
> * A section on "make doctor" has been added
> * The fixpath.sh script has been explained more in detail (and references to the old fixpath binary removed)
> * Information about MSYS2 and WSL has been updated
> * References to how things were done in the past, like the hg forest have been removed
> * Version numbers have been updated where needed
> * Some specific paragraphs about e.g. boot JDK detection have been clarified
> * Example output have been updated
> * Remaining references to `run-test` have been updated to just `test`
> * Internal links have been fixed in a few places
> * A few remaining places that confuses "OpenJDK" with the "JDK" have been fixed
> * Markdown formatting has been improved in some places
> * The entire file has gotten more normalized markdown formatting (fix bullet list indentation, add empty lines surrounding the code block markers, etc)
> 
> Note that this PR will can possibly create a merge conflict with 8317357 and 8264425; my intention is to integrate these two first and then resolve any conflicts in this PR.

Thank you for taking on the complete file, this looks much better. Just a few comments.

doc/building.md line 184:

> 182: Oracle, where header files and external libraries from an older version are
> 183: used when building on a more modern version of the OS. (This only applies to
> 184: x64.)

We use a separate OL version for the sysroot on Linux aarch64 too (currently 7.6), so I would remove the note about this only applying to x64. I have updated the wiki page to reflect this more clearly (it was already stated in the comment).

doc/building.md line 273:

> 271: the hood. WSL1 runs the binaries natively by translating Linux kernel calls
> 272: into Windows kernel calls, while WSL2 runs Linux in a virtual machine. Both
> 273: solutions has their pros and cons, and you might need to test both before

Suggestion:

solutions have their pros and cons, and you might need to test both before

doc/building.md line 1339:

> 1337: ### Considerations for specific targets
> 1338: 
> 1339: #### Building for ARM/aarch64

I don't think we need to or recommend setting ABI for aarch64.

doc/building.md line 2069:

> 2067: This conversion is done by the `fixpath.sh` tool, which is a small wrapper that
> 2068: modifies Unix-style paths to Windows-style paths. The fixpath
> 2069: tool is called with the first argument as a sub-command describing the action

Looks like the text needs to be reflowed here.

doc/building.md line 2090:

> 2088: 
> 2089: If you are having strange build issues related to path conversion, you might
> 2090: need to debug how fixpath treats your paths. There are many ways to do this.

many -> "several", or maybe "multiple"? Or perhaps "Here are some ways to do this."

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

PR Review: https://git.openjdk.org/jdk/pull/16696#pullrequestreview-1735175723
PR Review Comment: https://git.openjdk.org/jdk/pull/16696#discussion_r1396174810
PR Review Comment: https://git.openjdk.org/jdk/pull/16696#discussion_r1396178449
PR Review Comment: https://git.openjdk.org/jdk/pull/16696#discussion_r1396208258
PR Review Comment: https://git.openjdk.org/jdk/pull/16696#discussion_r1396216040
PR Review Comment: https://git.openjdk.org/jdk/pull/16696#discussion_r1396217484