RFR: JDK-8179892 Update build documentation for JDK 9

[Stuart Monteith]

Hi,
   It's good to see updated documentation - a project always feels a
bit stale if its documentation is out of date. However, I'd appreciate
it if Derek White's issue could be addressed:

"JDK-8182733: aarch64 build documentation misleading"
https://bugs.openjdk.java.net/browse/JDK-8182733

OpenJDK builds perfectly fine on AArch64 machines natively.

I don't think you need to make a specific recommendation for AArch64,
although my smallest machine has 8 cores and 16 GB, while, I'd guess
that the SPARC minimum requirements ought to be sufficient, I'd go
with that.

Thanks,
    Stuart


On 22 June 2017 at 10:31, Volker Simonis <volker.simonis at gmail.com> wrote:
> On Wed, Jun 21, 2017 at 12:59 PM, Magnus Ihse Bursie
> <magnus.ihse.bursie at oracle.com> wrote:
>> 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.
>>
>
> Great stuff Magnus!
>
> Happy midsummer and happy holidays :)
>
>> /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
>>>
>>>
>>