Skip to content

Commit

Permalink
Add detailed build instructions for OpenJDK8
Browse files Browse the repository at this point in the history 
Add markdown file for building OpenJDK8 with
OpenJ9 on Linux and AIX systems.

Add the yum text file that we reference in the
AIX build instructions.

Issue at github.com/eclipse-openj9/openj9-website/issues/25

[ci skip]

Issue eclipse-openj9#25

Signed-off-by: Sue Chaplain <sue_chaplain@uk.ibm.com>
  • Loading branch information
@SueChaplain
SueChaplain committed Nov 20, 2017
1 parent 762e62a commit ee459e3
Show file tree
Hide file tree
Showing 2 changed files with 372 additions and 0 deletions.
322 changes: 322 additions & 0 deletions buildenv/Build_Instructions_V8.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,322 @@
<!--
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 is also Distributed under one or more Secondary Licenses,
as those terms are defined by the Eclipse Public License, v. 2.0: 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
-->

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&trade; or z Systems&trade;, 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&trade;](https://github.com/eclipse/openj9/blob/master/buildenv/docker/jdk8/ppc64le/ubuntu16/Dockerfile) and [Linux on 64-bit z Systems&trade;](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, `<host_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 <host_directory>:/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 `<host_directory>` 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 /<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
: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=/<my_home_dir>/freemarker.jar /
--with-cups-include=<cups_include_path> /
--disable-warnings-as-errors
```
where `<my_home_dir>` is the location where you stored **freemarker.jar** and `<cups_include_path>` 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!
50 changes: 50 additions & 0 deletions buildenv/aix/jdk8/yum_install_aix-ppc64.txt
View file
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit ee459e3

Please sign in to comment.