diff --git a/buildenv/Build_Instructions_V8.md b/buildenv/Build_Instructions_V8.md new file mode 100644 index 00000000000..d323997aefb --- /dev/null +++ b/buildenv/Build_Instructions_V8.md @@ -0,0 +1,322 @@ + + +Building OpenJDK Version 8 with OpenJ9 +====================================== + +Our website describes a simple [build process](http://www.eclipse.org/openj9/oj9_build.html) +that uses Docker and Dockerfiles to create a build environment that contains everything +you need to easily build a Linux binary of OpenJDK V8 with the Eclipse OpenJ9 virtual machine. +A more complete set of build instructions are included here for multiple platforms: + +- [Linux :penguin:](#linux) +- [AIX :blue_book:](#aix) +- [Windows :ledger:](#windows) +- [MacOS :apple:](#macos) +- [ARM :iphone:](#arm) + + +---------------------------------- + +## Linux +:penguin: +This build process provides detailed instructions for building a Linux x86-64 binary of OpenJDK V8 with OpenJ9 on Ubuntu 16.04. The binary can be built directly on your system, in a virtual +machine, or in a Docker container :whale:. + +If you are using a different Linux distribution, you might have to review the list of libraries that are bundled with your distribution and/or modify the instructions to use equivalent commands to the Advanced Packaging Tool (APT). For example, for Centos, substitute the `apt-get` command with `yum`. + +If you want to build a binary for Linux on a different architecture, such as Power Systems™ or z Systems™, the process is very similar and any additional information for those architectures are included as Notes :pencil: as we go along. + + +### 1. Prepare your system +:penguin: +Instructions are provided for preparing your system with and without the use of Docker technology. + +Skip to [Setting up your build environment without Docker](#setting-up-your-build-environment-without-docker). + +#### Setting up your build environment with Docker :whale: +If you want to build a binary by using a Docker container, follow these steps to prepare your system: + +1. The first thing you need to do is install Docker. You can download the free Community edition from [here](https://docs.docker.com/engine/installation/), which also contains instructions for installing Docker on your system. You should also read the [Getting started](https://docs.docker.com/get-started/) guide to familiarise yourself with the basic Docker concepts and terminology. + +2. Obtain the [Linux on 64-bit x86 systems Dockerfile](https://github.com/eclipse/openj9/blob/master/buildenv/docker/jdk8/x86_64/ubuntu16/Dockerfile) to build and run a container that has all the correct software pre-requisites. + + :pencil: Dockerfiles are also available for the following Linux architectures: [Linux on 64-bit Power systems™](https://github.com/eclipse/openj9/blob/master/buildenv/docker/jdk8/ppc64le/ubuntu16/Dockerfile) and [Linux on 64-bit z Systems™](https://github.com/eclipse/openj9/blob/master/buildenv/docker/jdk8/s390x/ubuntu16/Dockerfile) + + Either download one of these Dockerfiles to your local system or copy and paste one of the following commands: + + - For Linux on 64-bit x86 systems, run: +``` +wget https://raw.githubusercontent.com/eclipse/openj9/master/buildenv/docker/jdk8/x86_64/ubuntu16/Dockerfile +``` + + - For Linux on 64-bit Power systems, run: +``` +wget https://raw.githubusercontent.com/eclipse/openj9/master/buildenv/docker/jdk8/ppc64le/ubuntu16/Dockerfile +``` + + - For Linux on 64-bit z Systems, run: +``` +wget https://raw.githubusercontent.com/eclipse/openj9/master/buildenv/docker/jdk8/s390x/ubuntu16/Dockerfile +``` + +3. Next, run the following command to build a Docker image, called **openj9**: +``` +docker build -t openj9 Dockerfile . +``` + +4. Start a Docker container from the **openj9** image with the following command, where `-v` maps any directory, ``, +on your local system to the containers `/root/hostdir` directory so that you can store the binaries, once they are built: +``` +docker run -v :/root/hostdir -it openj9 +``` + +:pencil: Depending on your [Docker system configuration](https://docs.docker.com/engine/reference/commandline/cli/#description), you might need to prefix the `docker` commands with `sudo`. + +Now that you have the Docker image running, you are ready to move to the next step, [Get the source](#2-get-the-source). + +#### Setting up your build environment without Docker + +If you don't want to user Docker, you can still build an OpenJDK V8 with OpenJ9 directly on your Ubuntu system or in a Ubuntu virtual machine. Use the +[Linux on x86 Dockerfile](https://github.com/eclipse/openj9/blob/master/buildenv/docker/jdk8/x86_64/ubuntu16/Dockerfile) like a recipe card to determine the software dependencies +that must be installed on the system, plus a few configuration steps. + +:pencil: +Not on x86? We also have Dockerfiles for the following Linux architectures: [Linux on Power systems](https://github.com/eclipse/openj9/blob/master/buildenv/docker/jdk8/ppc64le/ubuntu16/Dockerfile) and [Linux on z Systems](https://github.com/eclipse/openj9/blob/master/buildenv/docker/jdk8/s390x/ubuntu16/Dockerfile). + + +1. Install the list of dependencies that can be obtained with the `apt-get` command from the following section of the Dockerfile: + +``` +apt-get update \ + && apt-get install -qq -y --no-install-recommends \ + autoconf \ + ca-certificates \ + ... + ... +``` + +:warning: For Linux on z Systems, the `openjdk-7-jdk` package does not contain a JIT compiler, which means that the initial compile time will take several hours. + +2. This build uses the same gcc and g++ compiler levels as OpenJDK, which might be +backlevel compared with the versions you use on your system. Create links for +the compilers with the following commands: +``` +ln -s g++ /usr/bin/c++ +ln -s g++-4.8 /usr/bin/g++ +ln -s gcc /usr/bin/cc +ln -s gcc-4.8 /usr/bin/gcc +``` + +3. Download and setup **freemarker.jar** into a directory. The example commands use `/root` to be consistent with the Docker instructions. If you aren't using Docker, you probably want to store the **freemarker.jar** in your home directory. +``` +cd /root +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 +:penguin: +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-jdk8 +``` +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-jdk8 +``` +Now fetch additional sources from the Eclipse OpenJ9 project and its clone of Eclipse OMR: +``` +bash ./get_source.sh +``` + +### 3. Configure +:penguin: +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=/root/freemarker.jar +``` +:warning: You must give an absolute path to freemarker.jar + +### 4. Build +:penguin: +Now you're ready to build OpenJDK V8 with OpenJ9: +``` +make all +``` +:warning: If you just type `make`, rather than `make all` your build will fail, because the default `make` target is `exploded-image`. If you want to specify `make` instead of `make all`, you must add `--default-make-target=images` when you run the configure script. For more information, read this [issue](https://github.com/ibmruntimes/openj9-openjdk-jdk9/issues/34). + +Two Java builds are produced: a full developer kit (jdk) and a runtime environment (jre) +- **build/linux-x86_64-normal-server-release/images/jdk** +- **build/linux-x86_64-normal-server-release/images/jre** + + :whale: If you built your binaries in a Docker container, copy the binaries to the containers **/root/hostdir** directory so that you can access them on your local system. You'll find them in the directory you set for `` when you started your Docker container. See [Setting up your build environment with Docker](#setting-up-your-build-environment-with-docker). + + :pencil: On other architectures the **/jdk** and **/jre** directories are in **build/linux-ppc64le-normal-server-release/images** (Linux on 64-bit Power systems) and **build/linux-s390x-normal-server-release/images** (Linux on 64-bit z Systems) + +### 5. Test +:penguin: +For a simple test, try running the `java -version` command. +Change to the /jre directory: +``` +cd build/linux-x86_64-normal-server-release/images/jre +``` +Run: +``` +./bin/java -version +``` + +Here is some sample output: + +``` +openjdk version "1.8.0-internal" +OpenJDK Runtime Environment (build 1.8.0-internal-admin_2017_10_31_10_46-b00) +Eclipse OpenJ9 VM (build 2.9, JRE 1.8.0 Linux amd64-64 Compressed References 20171031_000000 (JIT enabled, AOT enabled) +OpenJ9 - 68d6fdb +OMR - 7c3d3d7 +OpenJDK - 27f5b8f based on jdk8u152-b03) +``` +:penguin: *Congratulations!* :tada: + +---------------------------------- + +## AIX +:blue_book: + +:construction: +This section is still under construction. Further contributions expected. + +The following instructions guide you through the process of building an OpenJDK V8 binary that contains Eclipse OpenJ9 on AIX 7.2. + +### 1. Prepare your system +:blue_book: +You must install the following AIX Licensed Program Products (LPPs): + +- [Java7_64](https://developer.ibm.com/javasdk/support/aix-download-service/) +- [xlc/C++ 13.1.3](https://www.ibm.com/developerworks/downloads/r/xlcplusaix/) +- x11.adt.ext + +A number of RPM packages are also required. The easiest method for installing these packages is to use `yum`, because `yum` takes care of any additional dependent packages for you. + +Download the following file: [yum_install_aix-ppc64.txt](aix/jdk8/yum_install_aix-ppc64.txt) + +This file contains a list of required RPM packages that you can install by specifying the following command: +``` +yum shell yum_install_aix-ppc64.txt +``` + +It is important to take the list of package dependencies from this file because it is kept right up to date by our developers. + +Download and setup freemarker.jar into your home directory by running the following commands: + +``` +cd / +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 +:blue_book: +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-jdk8 +``` +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-jdk8 +``` +Now fetch additional sources from the Eclipse OpenJ9 project and its clone of Eclipse OMR: + +``` +bash ./get_source.sh +``` +### 3. Configure +:blue_book: +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=//freemarker.jar / + --with-cups-include= / + --disable-warnings-as-errors +``` +where `` is the location where you stored **freemarker.jar** and `` is the absolute path to CUPS. For example `/opt/freeware/include`. + +### 4. build +:blue_book: +Now you're ready to build OpenJDK with OpenJ9: +``` +make all +``` +:warning: If you just type `make`, rather than `make all` your build will fail, because the default `make` target is `exploded-image`. If you want to specify `make` instead of `make all`, you must add `--default-make-target=images` when you run the configure script. For more information, read this [issue](https://github.com/ibmruntimes/openj9-openjdk-jdk9/issues/34). + +Two Java builds are produced: a full developer kit (jdk) and a runtime environment (jre) +- **build/aix-ppc64-normal-server-release/images/jdk** +- **build/aix-ppc64-normal-server-release/images/jre** + + :pencil: A JRE binary is not currently generated due to an OpenJDK bug. + + +### 5. Test +:blue_book: +For a simple test, try running the `java -version` command. +Change to the /jdk directory: +``` +cd build/aix-ppc64-normal-server-release/images/jdk +``` +Run: +``` +./bin/java -version +``` + +Here is some sample output: + +``` +openjdk version "1.8.0-internal" +OpenJDK Runtime Environment (build 1.8.0-internal-admin_2017_10_31_10_46-b00) +Eclipse OpenJ9 VM (build 2.9, JRE 8 AIX ppc-64 Compressed References 20171031_000000 (JIT enabled, AOT enabled) +OpenJ9 - 68d6fdb +OMR - 7c3d3d7 +OpenJDK - 27f5b8f based on jdk8u152-b03) +``` +:blue_book: *Congratulations!* :tada: + +---------------------------------- + +## Windows +:ledger: + +:construction: +We haven't created a full build process for Windows yet? Watch this space! + +---------------------------------- + +## 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! diff --git a/buildenv/aix/jdk8/yum_install_aix-ppc64.txt b/buildenv/aix/jdk8/yum_install_aix-ppc64.txt new file mode 100644 index 00000000000..f500a596ad0 --- /dev/null +++ b/buildenv/aix/jdk8/yum_install_aix-ppc64.txt @@ -0,0 +1,50 @@ +# Copyright (c) 2017, 2017 IBM Corp. and others +# +# This program and the accompanying materials are made available under +# the terms of the Eclipse Public License 2.0 which accompanies this +# distribution and is available at https://www.eclipse.org/legal/epl-2.0/ +# or the Apache License, Version 2.0 which accompanies this distribution and +# is available at https://www.apache.org/licenses/LICENSE-2.0. +# +# This Source Code may also be made available under the following +# Secondary Licenses when the conditions for such availability set +# forth in the Eclipse Public License, v. 2.0 are satisfied: GNU +# General Public License, version 2 with the GNU Classpath +# Exception [1] and GNU General Public License, version 2 with the +# OpenJDK Assembly Exception [2]. +# +# [1] https://www.gnu.org/software/classpath/license.html +# [2] http://openjdk.java.net/legal/assembly-exception.html +# +# SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + +# This file installs package dependencies for building OpenJDK V8 with OpenJ9 on AIX 64-bit systems +# To use this file, specify `yum shell yum_install_aix-ppc64.txt` + +install autoconf-2.69-1.noarch +install git-2.8.1-1.ppc +install unzip-6.0-3.ppc +install wget-1.17.1-1.ppc +install zip-3.0-2.ppc +install zsh-4.0.4-3.ppc +install gcc-6.3.0-1.ppc +install bc-1.06-2.ppc +install bison-1.875-3.ppc +update bzip2.ppc +install cpio-2.12-2.ppc +update glib2.ppc +install pkg-config-0.19-6.ppc +install freetype2-2.6.3-1.ppc +install gawk-3.1.3-1.ppc +install popt-1.16-3.ppc +update curl.ppc +install pcre-8.33-1.ppc +install wget-1.17.1-1.ppc +install sed-4.1.1-1.ppc +install make-4.1-2.ppc +install libXrender-devel-0.9.8-1waixX11.ppc +install libXft-2.3.2-2waixX11.ppc +install libffi-devel-3.0.12-1.ppc +install cups-devel-2.0.2-2.ppc +install freetype2-devel-2.6.3-1.ppc +run