[WIP] Add build instructions for OpenJDK11 macOS

New section for building OpenJDK 11 with OpenJ9
for macOS.

Remove the macOS and ARM sections from the OpenJDK 9
and OpenJDK 10 build instructions as we won't be
providing any information here now that these
releases are not supported.

[ci-skip]

Signed-off-by: Sue Chaplain <[email protected]>

doc/build-instructions/Build_Instructions_V10.md

@@ -31,8 +31,7 @@ A more complete set of build instructions are included here for multiple platfor
 - [Linux :penguin:](#linux)
 - [AIX :blue_book:](#aix)
 - [Windows :ledger:](#windows)
-- [MacOS :apple:](#macos)
-- [ARM :iphone:](#arm)
+
 
 ----------------------------------
 
@@ -426,19 +425,3 @@ JCL      - eaa06eb based on jdk-10+46)
 ```
 
 :ledger: *Congratulations!* :tada:
-
-----------------------------------
-
-## MacOS
-:apple:
-
-:construction:
-We haven't created a full build process for macOS yet? Watch this space!
-
-----------------------------------
-
-## ARM
-:iphone:
-
-:construction:
-We haven't created a full build process for ARM yet? Watch this space!

doc/build-instructions/Build_Instructions_V11.md

@@ -31,7 +31,7 @@ A more complete set of build instructions are included here for multiple platfor
 - [Linux :penguin:](#linux)
 - [AIX :blue_book:](#aix)
 - [Windows :ledger:](#windows)
-- [MacOS :apple:](#macos)
+- [macOS :apple:](#macos)
 - [ARM :iphone:](#arm)
 
 ----------------------------------
@@ -448,11 +448,97 @@ JCL      - a786f96b13 based on jdk-11+21)
 
 ----------------------------------
 
-## MacOS
+## macOS
 :apple:
+The following instructions guide you through the process of building a macOS **OpenJDK V11** binary that contains Eclipse OpenJ9. This process can be used to build binaries for macOS 10.
 
-:construction:
-We haven't created a full build process for macOS yet? Watch this space!
+### 1. Prepare your system
+:apple:
+You must install a number of software dependencies to create a suitable build environment on your system:
+
+- [Xcode 9.4]( https://developer.apple.com/download/more/) (requires an Apple account to log in).
+- [macOS OpenJDK 10](https://adoptopenjdk.net/archive.html?variant=openjdk10&jvmVariant=hotspot), which is used as the boot JDK.
+- [nasm 2.13.03](https://formulae.brew.sh/formula/nasm), which can be installed by using [Homebrew](https://brew.sh/).
+- [bash 4.4.23](https://formulae.brew.sh/formula/bash), which can be installed by using [Homebrew](https://brew.sh/).
+- [gnu-tar 1.3](https://formulae.brew.sh/formula/gnu-tar), which can be installed by using [Homebrew](https://brew.sh/).
+- [Freemarker V2.3.8](https://sourceforge.net/projects/freemarker/files/freemarker/2.3.8/freemarker-2.3.8.tar.gz/download), which can be obtained and installed with the following commands:
+
+```
+cd /<my_home_dir>
+wget https://sourceforge.net/projects/freemarker/files/freemarker/2.3.8/freemarker-2.3.8.tar.gz/download -O freemarker.tgz
+tar -xzf freemarker.tgz freemarker-2.3.8/lib/freemarker.jar --strip=2
+rm -f freemarker.tgz
+```
+
+### 2. Get the source
+:apple:
+First you need to clone the Extensions for OpenJDK for OpenJ9 project. This repository is a git mirror of OpenJDK without the HotSpot JVM, but with an **openj9** branch that contains a few necessary patches.
+
+Run the following command:
+```
+git clone https://github.com/ibmruntimes/openj9-openjdk-jdk11.git
+```
+Cloning this repository can take a while because OpenJDK is a large project! When the process is complete, change directory into the cloned repository:
+```
+cd openj9-openjdk-jdk11
+```
+Now fetch additional sources from the Eclipse OpenJ9 project and its clone of Eclipse OMR:
+
+```
+bash ./get_source.sh
+```
+### 3. Configure
+:apple:
+When you have all the source files that you need, run the configure script, which detects how to build in the current build environment.
+
+```
+bash configure --with-freemarker-jar=/<my_home_dir>/freemarker.jar \
+               --with-boot-jdk=<path_to_macOS_JDK11> \
+               --disable-warnings-as-errors
+```
+
+:pencil: Modify the paths for freemarker and the macOS boot JDK that you installed in step 1.
+
+:pencil: If you require a heap size greater than 57GB, enable a noncompressedrefs build with the `--with-noncompressedrefs` option during this step.
+
+### 4. build
+:apple:
+Now you're ready to build OpenJDK with OpenJ9:
+
+```
+make all
+```
+
+A binary for the full developer kit (jdk) is built and stored in the following directory:
+
+- **build/macos-x86_64-normal-server-release/images/jdk**
+
+    :pencil: If you want a binary for the runtime environment (jre), you must run `make legacy-jre-image`, which produces a jre build in the **build/macos-x86_64-normal-server-release/images/jre** directory.
+
+### 5. Test
+:apple:
+For a simple test, try running the `java -version` command.
+Change to the /jdk directory:
+```
+cd build/macos-x86_64-normal-server-release/images/jdk
+```
+Run:
+```
+./bin/java -version
+```
+
+Here is some sample output:
+
+```
+openjdk version "11-internal" 2018-09-25
+OpenJDK Runtime Environment (build 11-internal+0-adhoc.heidinga.openj9-openjdk-jdk11)
+Eclipse OpenJ9 VM (build djh/libjava-72338d7a1, JRE 11 Mac OS X amd64-64-Bit Compressed References 20181104_000000 (JIT enabled, AOT enabled)
+OpenJ9   - 72338d7a1
+OMR      - d4cd7c31
+JCL      - 9da99f8b97 based on jdk-11+28)
+```
+
+:ledger: *Congratulations!* :tada:
 
 ----------------------------------
 

doc/build-instructions/Build_Instructions_V9.md

@@ -31,8 +31,6 @@ A more complete set of build instructions are included here for multiple platfor
 - [Linux :penguin:](#linux)
 - [AIX :blue_book:](#aix)
 - [Windows :ledger:](#windows)
-- [MacOS :apple:](#macos)
-- [ARM :iphone:](#arm)
 
 ----------------------------------
 
@@ -419,19 +417,3 @@ OpenJDK  - 198304337b based on jdk-9+181)
 ```
 
 :ledger: *Congratulations!* :tada:
-
-----------------------------------
-
-## MacOS
-:apple:
-
-:construction:
-We haven't created a full build process for macOS yet? Watch this space!
-
-----------------------------------
-
-## ARM
-:iphone:
-
-:construction:
-We haven't created a full build process for ARM yet? Watch this space!