RFR: JDK-8179892 Update build documentation for JDK 9

[Magnus Ihse Bursie]

On 2017-06-21 09:02, Thomas Stüfe wrote:
> Hi Magnus,
>
> excellent work!

Thank you! :-)

> Some minor remarks:
>
> You also mentioned Cygwin hg in the "Special considerations" section. 
> However, because updating Cygwin is a bit of a pain (you need to close 
> all consoles to do this) it may make sense to move the "Install Cygwin 
> and all required packages" up to the beginning of the document and 
> include "mercurial" in the list of cygwin packages to install.
>
> In addition to that (if contributing to the OpenJDK is in the scope 
> for this document?) it may make sense to install at least ksh (for 
> webrevs) and sftp (for uploading webrevs) for Cygwin.

For JDK 10, we can discuss where to draw the line of the responsibility 
of this document. I don't think it can cover all OpenJDK developer 
stories, like webrev, etc. But we should probably make sure that such a 
document exists somewhere, in the repo or on the OpenJDK web site or wiki.

I've tried putting information about what to install and how grouped to 
the specific requirements. This has both drawbacks and benefits. One 
thing you don't get is a "one stop" description of "install all these 
packages". That could perhaps be added to the TL;DR section -- if you 
just want something quick that is likely to work, and you don't care 
why, or if you install slightly too much.

> As for AIX, so far we have not yet broken compatibility with AIX 5.3. 
> While this is something which we may give up in the future, currently 
> jdk9/10 still build and run on AIX 5.3 and 6.1.

Ok, I updated the document to include this information.

> I think we can flesh out this section a lot. We will discuss this in 
> our team.

That sounds great! I realize the AIX part was a bit thin, but at least 
it is mentioned, as compared to the old document. :)

I'm leaving for vacation now, but I'll be happy to discuss with you and 
your team how to improve the documentation for AIX/PPC in JDK 10.

/Magnus

>
> Kind Regards, Thomas
>
>
> On Wed, Jun 21, 2017 at 2:46 AM, Magnus Ihse Bursie 
> <magnus.ihse.bursie at oracle.com <mailto:magnus.ihse.bursie at oracle.com>> 
> wrote:
>
>     Also known as: "!!!!!!!!!!!!!!! THIS IS A MAJOR RE-WRITE of this
>     document. !!!!!!!!!!!!!" :-)
>
>     The build documentation has been in need of an overhaul for a very
>     long time. The document is not very well structured, and contains
>     not only outdated but also irrelevant information, all the while
>     valuable information is missing.
>
>     For some time now, I've worked as a background project to rewrite
>     the build documentation to address these shortcomings. Now it's
>     finally done.
>
>     Here is the new documentation in html format:
>     http://cr.openjdk.java.net/~ihse/demo-new-build-readme/common/doc/building.html
>     <http://cr.openjdk.java.net/%7Eihse/demo-new-build-readme/common/doc/building.html>
>
>     And here it is in markdown:
>     http://cr.openjdk.java.net/~ihse/JDK-8179892-update-build-readme/webrev.01/raw_files/new/common/doc/building.md
>     <http://cr.openjdk.java.net/%7Eihse/JDK-8179892-update-build-readme/webrev.01/raw_files/new/common/doc/building.md>
>
>     I've tried to make the document as readable as possible in raw
>     markdown, hoping it can be of assistance for command-line users.
>
>     Bug: https://bugs.openjdk.java.net/browse/JDK-8179892
>     <https://bugs.openjdk.java.net/browse/JDK-8179892>
>     WebRev:
>     http://cr.openjdk.java.net/~ihse/JDK-8179892-update-build-readme/webrev.01
>     <http://cr.openjdk.java.net/%7Eihse/JDK-8179892-update-build-readme/webrev.01>
>
>     /Magnus
>
>