< prev index next >
doc/building.md
Print this page
rev 50850 : 8205956: Fix usage of "OpenJDK" in build and test instructions
*** 1,12 ****
! % Building OpenJDK
## TL;DR (Instructions for the Impatient)
! If you are eager to try out building OpenJDK, these simple steps works most of
the time. They assume that you have installed Mercurial (and Cygwin if running
! on Windows) and cloned the top-level OpenJDK repository that you want to build.
1. [Get the complete source code](#getting-the-source-code): \
`hg clone http://hg.openjdk.java.net/jdk/jdk`
2. [Run configure](#running-configure): \
--- 1,12 ----
! % Building the JDK
## TL;DR (Instructions for the Impatient)
! If you are eager to try out building the JDK, these simple steps works most of
the time. They assume that you have installed Mercurial (and Cygwin if running
! on Windows) and cloned the top-level JDK repository that you want to build.
1. [Get the complete source code](#getting-the-source-code): \
`hg clone http://hg.openjdk.java.net/jdk/jdk`
2. [Run configure](#running-configure): \
*** 32,49 ****
If any of these steps failed, or if you want to know more about build
requirements or build functionality, please continue reading this document.
## Introduction
! OpenJDK is a complex software project. Building it requires a certain amount of
technical expertise, a fair number of dependencies on external software, and
reasonably powerful hardware.
! If you just want to use OpenJDK and not build it yourself, this document is not
for you. See for instance [OpenJDK installation](
http://openjdk.java.net/install) for some methods of installing a prebuilt
! OpenJDK.
## Getting the Source Code
Make sure you are getting the correct version. As of JDK 10, the source is no
longer split into separate repositories so you only need to clone one single
--- 32,49 ----
If any of these steps failed, or if you want to know more about build
requirements or build functionality, please continue reading this document.
## Introduction
! The JDK is a complex software project. Building it requires a certain amount of
technical expertise, a fair number of dependencies on external software, and
reasonably powerful hardware.
! If you just want to use the JDK and not build it yourself, this document is not
for you. See for instance [OpenJDK installation](
http://openjdk.java.net/install) for some methods of installing a prebuilt
! JDK.
## Getting the Source Code
Make sure you are getting the correct version. As of JDK 10, the source is no
longer split into separate repositories so you only need to clone one single
*** 78,106 ****
* On Windows, extra care must be taken to make sure the [Cygwin](#cygwin)
environment is consistent. It is recommended that you follow this
procedure:
* Create the directory that is going to contain the top directory of the
! OpenJDK clone by using the `mkdir` command in the Cygwin bash shell.
That is, do *not* create it using Windows Explorer. This will ensure
that it will have proper Cygwin attributes, and that it's children will
inherit those attributes.
! * Do not put the OpenJDK clone in a path under your Cygwin home
directory. This is especially important if your user name contains
spaces and/or mixed upper and lower case letters.
! * Clone the OpenJDK repository using the Cygwin command line `hg` client
as instructed in this document. That is, do *not* use another Mercurial
client such as TortoiseHg.
Failure to follow this procedure might result in hard-to-debug build
problems.
## Build Hardware Requirements
! OpenJDK is a massive project, and require machines ranging from decent to
powerful to be able to build in a reasonable amount of time, or to be able to
complete a build at all.
We *strongly* recommend usage of an SSD disk for the build, since disk speed is
one of the limiting factors for build performance.
--- 78,106 ----
* On Windows, extra care must be taken to make sure the [Cygwin](#cygwin)
environment is consistent. It is recommended that you follow this
procedure:
* Create the directory that is going to contain the top directory of the
! JDK clone by using the `mkdir` command in the Cygwin bash shell.
That is, do *not* create it using Windows Explorer. This will ensure
that it will have proper Cygwin attributes, and that it's children will
inherit those attributes.
! * Do not put the JDK clone in a path under your Cygwin home
directory. This is especially important if your user name contains
spaces and/or mixed upper and lower case letters.
! * Clone the JDK repository using the Cygwin command line `hg` client
as instructed in this document. That is, do *not* use another Mercurial
client such as TortoiseHg.
Failure to follow this procedure might result in hard-to-debug build
problems.
## Build Hardware Requirements
! The JDK is a massive project, and require machines ranging from decent to
powerful to be able to build in a reasonable amount of time, or to be able to
complete a build at all.
We *strongly* recommend usage of an SSD disk for the build, since disk speed is
one of the limiting factors for build performance.
*** 125,143 ****
This is not recommended. Instead, see the section on [Cross-compiling](
#cross-compiling).
## Operating System Requirements
! The mainline OpenJDK project supports Linux, Solaris, macOS, AIX and Windows.
Support for other operating system, e.g. BSD, exists in separate "port"
projects.
! In general, OpenJDK can be built on a wide range of versions of these operating
systems, but the further you deviate from what is tested on a daily basis, the
more likely you are to run into problems.
! This table lists the OS versions used by Oracle when building OpenJDK. Such
information is always subject to change, but this table is up to date at the
time of writing.
Operating system Vendor/version used
----------------- -------------------------------------------------------
--- 125,143 ----
This is not recommended. Instead, see the section on [Cross-compiling](
#cross-compiling).
## Operating System Requirements
! The mainline JDK project supports Linux, Solaris, macOS, AIX and Windows.
Support for other operating system, e.g. BSD, exists in separate "port"
projects.
! In general, the JDK can be built on a wide range of versions of these operating
systems, but the further you deviate from what is tested on a daily basis, the
more likely you are to run into problems.
! This table lists the OS versions used by Oracle when building the JDK. Such
information is always subject to change, but this table is up to date at the
time of writing.
Operating system Vendor/version used
----------------- -------------------------------------------------------
*** 146,176 ****
macOS Mac OS X 10.9 (Mavericks) / 10.10 (Yosemite)
Windows Windows Server 2012 R2
The double version numbers for Linux, Solaris and macOS is due to the hybrid
model used at Oracle, where header files and external libraries from an older
! version is used when building on a more modern version of the OS.
The Build Group has a wiki page with [Supported Build Platforms](
https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms). From
! time to time, this is updated by the community to list successes or failures of
building on different platforms.
### Windows
Windows XP is not a supported platform, but all newer Windows should be able to
! build OpenJDK.
On Windows, it is important that you pay attention to the instructions in the
[Special Considerations](#special-considerations).
! Windows is the only non-POSIX OS supported by OpenJDK, and as such, requires
some extra care. A POSIX support layer is required to build on Windows.
Currently, the only supported such layer is Cygwin. (Msys is no longer
supported due to a too old bash; msys2 and the new Windows Subsystem for Linux
(WSL) would likely be possible to support in a future version but that would
! require a community effort to implement.)
Internally in the build system, all paths are represented as Unix-style paths,
e.g. `/cygdrive/c/hg/jdk9/Makefile` rather than `C:\hg\jdk9\Makefile`. This
rule also applies to input to the build system, e.g. in arguments to
`configure`. So, use `--with-msvcr-dll=/cygdrive/c/msvcr100.dll` rather than
--- 146,176 ----
macOS Mac OS X 10.9 (Mavericks) / 10.10 (Yosemite)
Windows Windows Server 2012 R2
The double version numbers for Linux, Solaris and macOS is due to the hybrid
model used at Oracle, where header files and external libraries from an older
! version are used when building on a more modern version of the OS.
The Build Group has a wiki page with [Supported Build Platforms](
https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms). From
! time to time, this is updated by contributors to list successes or failures of
building on different platforms.
### Windows
Windows XP is not a supported platform, but all newer Windows should be able to
! build the JDK.
On Windows, it is important that you pay attention to the instructions in the
[Special Considerations](#special-considerations).
! Windows is the only non-POSIX OS supported by the JDK, and as such, requires
some extra care. A POSIX support layer is required to build on Windows.
Currently, the only supported such layer is Cygwin. (Msys is no longer
supported due to a too old bash; msys2 and the new Windows Subsystem for Linux
(WSL) would likely be possible to support in a future version but that would
! require effort to implement.)
Internally in the build system, all paths are represented as Unix-style paths,
e.g. `/cygdrive/c/hg/jdk9/Makefile` rather than `C:\hg\jdk9\Makefile`. This
rule also applies to input to the build system, e.g. in arguments to
`configure`. So, use `--with-msvcr-dll=/cygdrive/c/msvcr100.dll` rather than
*** 178,197 ****
on [Fixpath](#fixpath).
#### Cygwin
A functioning [Cygwin](http://www.cygwin.com/) environment is thus required for
! building OpenJDK on Windows. If you have a 64-bit OS, we strongly recommend
using the 64-bit version of Cygwin.
**Note:** Cygwin has a model of continuously updating all packages without any
easy way to install or revert to a specific version of a package. This means
that whenever you add or update a package in Cygwin, you might (inadvertently)
! update tools that are used by the OpenJDK build process, and that can cause
unexpected build problems.
! OpenJDK requires GNU Make 4.0 or greater on Windows. This is usually not a
problem, since Cygwin currently only distributes GNU Make at a version above
4.0.
Apart from the basic Cygwin installation, the following packages must also be
installed:
--- 178,197 ----
on [Fixpath](#fixpath).
#### Cygwin
A functioning [Cygwin](http://www.cygwin.com/) environment is thus required for
! building the JDK on Windows. If you have a 64-bit OS, we strongly recommend
using the 64-bit version of Cygwin.
**Note:** Cygwin has a model of continuously updating all packages without any
easy way to install or revert to a specific version of a package. This means
that whenever you add or update a package in Cygwin, you might (inadvertently)
! update tools that are used by the JDK build process, and that can cause
unexpected build problems.
! The JDK requires GNU Make 4.0 or greater on Windows. This is usually not a
problem, since Cygwin currently only distributes GNU Make at a version above
4.0.
Apart from the basic Cygwin installation, the following packages must also be
installed:
*** 227,252 ****
### macOS
Apple is using a quite aggressive scheme of pushing OS updates, and coupling
these updates with required updates of Xcode. Unfortunately, this makes it
! difficult for a project like OpenJDK to keep pace with a continuously updated
machine running macOS. See the section on [Apple Xcode](#apple-xcode) on some
strategies to deal with this.
It is recommended that you use at least Mac OS X 10.9 (Mavericks). At the time
! of writing, OpenJDK has been successfully compiled on macOS versions up to
10.12.5 (Sierra), using XCode 8.3.2 and `--disable-warnings-as-errors`.
The standard macOS environment contains the basic tooling needed to build, but
! for external libraries a package manager is recommended. OpenJDK uses
[homebrew](https://brew.sh/) in the examples, but feel free to use whatever
manager you want (or none).
### Linux
! It is often not much problem to build OpenJDK on Linux. The only general advice
is to try to use the compilers, external libraries and header files as provided
by your distribution.
The basic tooling is provided as part of the core operating system, but you
will most likely need to install developer packages.
--- 227,252 ----
### macOS
Apple is using a quite aggressive scheme of pushing OS updates, and coupling
these updates with required updates of Xcode. Unfortunately, this makes it
! difficult for a project such as the JDK to keep pace with a continuously updated
machine running macOS. See the section on [Apple Xcode](#apple-xcode) on some
strategies to deal with this.
It is recommended that you use at least Mac OS X 10.9 (Mavericks). At the time
! of writing, the JDK has been successfully compiled on macOS versions up to
10.12.5 (Sierra), using XCode 8.3.2 and `--disable-warnings-as-errors`.
The standard macOS environment contains the basic tooling needed to build, but
! for external libraries a package manager is recommended. The JDK uses
[homebrew](https://brew.sh/) in the examples, but feel free to use whatever
manager you want (or none).
### Linux
! It is often not much problem to build the JDK on Linux. The only general advice
is to try to use the compilers, external libraries and header files as provided
by your distribution.
The basic tooling is provided as part of the core operating system, but you
will most likely need to install developer packages.
*** 267,277 ****
supported. See the [OpenJDK PowerPC Port Status Page](
http://cr.openjdk.java.net/~simonis/ppc-aix-port) for details.
## Native Compiler (Toolchain) Requirements
! Large portions of OpenJDK consists of native code, that needs to be compiled to
be able to run on the target platform. In theory, toolchain and operating
system should be independent factors, but in practice there's more or less a
one-to-one correlation between target operating system and toolchain.
Operating system Supported toolchain
--- 267,277 ----
supported. See the [OpenJDK PowerPC Port Status Page](
http://cr.openjdk.java.net/~simonis/ppc-aix-port) for details.
## Native Compiler (Toolchain) Requirements
! Large portions of the JDK consists of native code, that needs to be compiled to
be able to run on the target platform. In theory, toolchain and operating
system should be independent factors, but in practice there's more or less a
one-to-one correlation between target operating system and toolchain.
Operating system Supported toolchain
*** 282,293 ****
AIX IBM XL C/C++
Windows Microsoft Visual Studio
Please see the individual sections on the toolchains for version
recommendations. As a reference, these versions of the toolchains are used, at
! the time of writing, by Oracle for the daily builds of OpenJDK. It should be
! possible to compile OpenJDK with both older and newer versions, but the closer
you stay to this list, the more likely you are to compile successfully without
issues.
Operating system Toolchain version
------------------ -------------------------------------------------------
--- 282,293 ----
AIX IBM XL C/C++
Windows Microsoft Visual Studio
Please see the individual sections on the toolchains for version
recommendations. As a reference, these versions of the toolchains are used, at
! the time of writing, by Oracle for the daily builds of the JDK. It should be
! possible to compile the JDK with both older and newer versions, but the closer
you stay to this list, the more likely you are to compile successfully without
issues.
Operating system Toolchain version
------------------ -------------------------------------------------------
*** 299,309 ****
### gcc
The minimum accepted version of gcc is 4.8. Older versions will generate a warning
by `configure` and are unlikely to work.
! OpenJDK is currently known to be able to compile with at least version 7.4 of
gcc.
In general, any version between these two should be usable.
### clang
--- 299,309 ----
### gcc
The minimum accepted version of gcc is 4.8. Older versions will generate a warning
by `configure` and are unlikely to work.
! The JDK is currently known to be able to compile with at least version 7.4 of
gcc.
In general, any version between these two should be usable.
### clang
*** 316,341 ****
### Apple Xcode
The oldest supported version of Xcode is 5.
You will need the Xcode command lines developers tools to be able to build
! OpenJDK. (Actually, *only* the command lines tools are needed, not the IDE.)
The simplest way to install these is to run:
```
xcode-select --install
```
! It is advisable to keep an older version of Xcode for building OpenJDK when
updating Xcode. This [blog page](
http://iosdevelopertips.com/xcode/install-multiple-versions-of-xcode.html) has
good suggestions on managing multiple Xcode versions. To use a specific version
of Xcode, use `xcode-select -s` before running `configure`, or use
`--with-toolchain-path` to point to the version of Xcode to use, e.g.
`configure --with-toolchain-path=/Applications/Xcode5.app/Contents/Developer/usr/bin`
If you have recently (inadvertently) updated your OS and/or Xcode version, and
! OpenJDK can no longer be built, please see the section on [Problems with the
Build Environment](#problems-with-the-build-environment), and [Getting
Help](#getting-help) to find out if there are any recent, non-merged patches
available for this update.
### Oracle Solaris Studio
--- 316,341 ----
### Apple Xcode
The oldest supported version of Xcode is 5.
You will need the Xcode command lines developers tools to be able to build
! the JDK. (Actually, *only* the command lines tools are needed, not the IDE.)
The simplest way to install these is to run:
```
xcode-select --install
```
! It is advisable to keep an older version of Xcode for building the JDK when
updating Xcode. This [blog page](
http://iosdevelopertips.com/xcode/install-multiple-versions-of-xcode.html) has
good suggestions on managing multiple Xcode versions. To use a specific version
of Xcode, use `xcode-select -s` before running `configure`, or use
`--with-toolchain-path` to point to the version of Xcode to use, e.g.
`configure --with-toolchain-path=/Applications/Xcode5.app/Contents/Developer/usr/bin`
If you have recently (inadvertently) updated your OS and/or Xcode version, and
! the JDK can no longer be built, please see the section on [Problems with the
Build Environment](#problems-with-the-build-environment), and [Getting
Help](#getting-help) to find out if there are any recent, non-merged patches
available for this update.
### Oracle Solaris Studio
*** 393,432 ****
See the [OpenJDK PowerPC Port Status Page](
http://cr.openjdk.java.net/~simonis/ppc-aix-port) for details.
## Boot JDK Requirements
! Paradoxically, building OpenJDK requires a pre-existing JDK. This is called the
! "boot JDK". The boot JDK does not have to be OpenJDK, though. If you are
! porting OpenJDK to a new platform, chances are that there already exists
! another JDK for that platform that is usable as boot JDK.
The rule of thumb is that the boot JDK for building JDK major version *N*
should be a JDK of major version *N-1*, so for building JDK 9 a JDK 8 would be
! suitable as boot JDK. However, OpenJDK should be able to "build itself", so an
! up-to-date build of the current OpenJDK source is an acceptable alternative. If
you are following the *N-1* rule, make sure you've got the latest update
version, since JDK 8 GA might not be able to build JDK 9 on all platforms.
Early in the release cycle, version *N-1* may not yet have been released. In
that case, the preferred boot JDK will be version *N-2* until version *N-1*
is available.
! If the Boot JDK is not automatically detected, or the wrong JDK is picked, use
`--with-boot-jdk` to point to the JDK to use.
### Getting JDK binaries
! OpenJDK binaries for Linux, Windows and macOS can be downloaded from
[jdk.java.net](http://jdk.java.net). An alternative is to download the
[Oracle JDK](http://www.oracle.com/technetwork/java/javase/downloads). Another
is the [Adopt OpenJDK Project](https://adoptopenjdk.net/), which publishes
experimental prebuilt binaries for various platforms.
! On Linux you can also get OpenJDK from the Linux distribution. On apt-based
distros (like Debian and Ubuntu), `sudo apt-get install openjdk-<VERSION>-jdk`
! is typically enough to install OpenJDK \<VERSION\>. On rpm-based distros (like
Fedora and Red Hat), try `sudo yum install java-<VERSION>-openjdk-devel`.
## External Library Requirements
Different platforms require different external libraries. In general, libraries
--- 393,433 ----
See the [OpenJDK PowerPC Port Status Page](
http://cr.openjdk.java.net/~simonis/ppc-aix-port) for details.
## Boot JDK Requirements
! Paradoxically, building the JDK requires a pre-existing JDK. This is called the
! "boot JDK". The boot JDK does not, however, have to be a JDK built directly from
! the source code available in the OpenJDK Community. If you are porting the JDK
! to a new platform, chances are that there already exists another JDK for that
! platform that is usable as boot JDK.
The rule of thumb is that the boot JDK for building JDK major version *N*
should be a JDK of major version *N-1*, so for building JDK 9 a JDK 8 would be
! suitable as boot JDK. However, the JDK should be able to "build itself", so an
! up-to-date build of the current JDK source is an acceptable alternative. If
you are following the *N-1* rule, make sure you've got the latest update
version, since JDK 8 GA might not be able to build JDK 9 on all platforms.
Early in the release cycle, version *N-1* may not yet have been released. In
that case, the preferred boot JDK will be version *N-2* until version *N-1*
is available.
! If the boot JDK is not automatically detected, or the wrong JDK is picked, use
`--with-boot-jdk` to point to the JDK to use.
### Getting JDK binaries
! JDK binaries for Linux, Windows and macOS can be downloaded from
[jdk.java.net](http://jdk.java.net). An alternative is to download the
[Oracle JDK](http://www.oracle.com/technetwork/java/javase/downloads). Another
is the [Adopt OpenJDK Project](https://adoptopenjdk.net/), which publishes
experimental prebuilt binaries for various platforms.
! On Linux you can also get a JDK from the Linux distribution. On apt-based
distros (like Debian and Ubuntu), `sudo apt-get install openjdk-<VERSION>-jdk`
! is typically enough to install a JDK \<VERSION\>. On rpm-based distros (like
Fedora and Red Hat), try `sudo yum install java-<VERSION>-openjdk-devel`.
## External Library Requirements
Different platforms require different external libraries. In general, libraries
*** 445,455 ****
### FreeType
FreeType2 from [The FreeType Project](http://www.freetype.org/) is not required
on any platform. The exception is on Unix-based platforms when configuring such
that the build artifacts will reference a system installed library,
! rather than bundling OpenJDK's own copy.
* To install on an apt-based Linux, try running `sudo apt-get install
libfreetype6-dev`.
* To install on an rpm-based Linux, try running `sudo yum install
freetype-devel`.
--- 446,456 ----
### FreeType
FreeType2 from [The FreeType Project](http://www.freetype.org/) is not required
on any platform. The exception is on Unix-based platforms when configuring such
that the build artifacts will reference a system installed library,
! rather than bundling the JDK’s own copy.
* To install on an apt-based Linux, try running `sudo apt-get install
libfreetype6-dev`.
* To install on an rpm-based Linux, try running `sudo yum install
freetype-devel`.
*** 520,530 ****
## Build Tools Requirements
### Autoconf
! OpenJDK requires [Autoconf](http://www.gnu.org/software/autoconf) on all
platforms. At least version 2.69 is required.
* To install on an apt-based Linux, try running `sudo apt-get install
autoconf`.
* To install on an rpm-based Linux, try running `sudo yum install
--- 521,531 ----
## Build Tools Requirements
### Autoconf
! The JDK requires [Autoconf](http://www.gnu.org/software/autoconf) on all
platforms. At least version 2.69 is required.
* To install on an apt-based Linux, try running `sudo apt-get install
autoconf`.
* To install on an rpm-based Linux, try running `sudo yum install
*** 540,550 ****
AUTOCONF=<path to autoconf> configure ...
```
### GNU Make
! OpenJDK requires [GNU Make](http://www.gnu.org/software/make). No other flavors
of make are supported.
At least version 3.81 of GNU Make must be used. For distributions supporting
GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful
functionality to handle parallel building (supported by `--with-output-sync`)
--- 541,551 ----
AUTOCONF=<path to autoconf> configure ...
```
### GNU Make
! The JDK requires [GNU Make](http://www.gnu.org/software/make). No other flavors
of make are supported.
At least version 3.81 of GNU Make must be used. For distributions supporting
GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful
functionality to handle parallel building (supported by `--with-output-sync`)
*** 564,583 ****
On Solaris, it is common to call the GNU version of make by using `gmake`.
### GNU Bash
! OpenJDK requires [GNU Bash](http://www.gnu.org/software/bash). No other shells
are supported.
At least version 3.2 of GNU Bash must be used.
## Running Configure
! To build OpenJDK, you need a "configuration", which consists of a directory
where to store the build output, coupled with information about the platform,
! the specific build machine, and choices that affect how OpenJDK is built.
The configuration is created by the `configure` script. The basic invocation of
the `configure` script looks like this:
```
--- 565,584 ----
On Solaris, it is common to call the GNU version of make by using `gmake`.
### GNU Bash
! The JDK requires [GNU Bash](http://www.gnu.org/software/bash). No other shells
are supported.
At least version 3.2 of GNU Bash must be used.
## Running Configure
! To build the JDK, you need a "configuration", which consists of a directory
where to store the build output, coupled with information about the platform,
! the specific build machine, and choices that affect how the JDK is built.
The configuration is created by the `configure` script. The basic invocation of
the `configure` script looks like this:
```
*** 617,627 ****
```
bash configure --help
```
(Note that this help text also include general autoconf options, like
! `--dvidir`, that is not relevant to OpenJDK. To list only OpenJDK specific
features, use `bash configure --help=short` instead.)
#### Configure Arguments for Tailoring the Build
* `--enable-debug` - Set the debug level to `fastdebug` (this is a shorthand
--- 618,628 ----
```
bash configure --help
```
(Note that this help text also include general autoconf options, like
! `--dvidir`, that is not relevant to the JDK. To list only JDK-specific
features, use `bash configure --help=short` instead.)
#### Configure Arguments for Tailoring the Build
* `--enable-debug` - Set the debug level to `fastdebug` (this is a shorthand
*** 678,690 ****
* `--with-alsa=<path>` - Set the path to [ALSA](#alsa)
* `--with-libffi=<path>` - Set the path to [libffi](#libffi)
* `--with-jtreg=<path>` - Set the path to JTReg. See [Running Tests](
#running-tests)
! Certain third-party libraries used by OpenJDK (libjpeg, giflib, libpng, lcms
! and zlib) are included in the OpenJDK repository. The default behavior of the
! OpenJDK build is to use this version of these libraries, but they might be
replaced by an external version. To do so, specify `system` as the `<source>`
option in these arguments. (The default is `bundled`).
* `--with-libjpeg=<source>` - Use the specified source for libjpeg
* `--with-giflib=<source>` - Use the specified source for giflib
--- 679,691 ----
* `--with-alsa=<path>` - Set the path to [ALSA](#alsa)
* `--with-libffi=<path>` - Set the path to [libffi](#libffi)
* `--with-jtreg=<path>` - Set the path to JTReg. See [Running Tests](
#running-tests)
! Certain third-party libraries used by the JDK (libjpeg, giflib, libpng, lcms
! and zlib) are included in the JDK repository. The default behavior of the
! JDK build is to use this version of these libraries, but they might be
replaced by an external version. To do so, specify `system` as the `<source>`
option in these arguments. (The default is `bundled`).
* `--with-libjpeg=<source>` - Use the specified source for libjpeg
* `--with-giflib=<source>` - Use the specified source for giflib
*** 724,734 ****
accomplish anything. Instead use `--with-extra-cflags` (and similar for
`cxxflags` and `ldflags`).
## Running Make
! When you have a proper configuration, all you need to do to build OpenJDK is to
run `make`. (But see the warning at [GNU Make](#gnu-make) about running the
correct version of make.)
When running `make` without any arguments, the default target is used, which is
the same as running `make default` or `make jdk`. This will build a minimal (or
--- 725,735 ----
accomplish anything. Instead use `--with-extra-cflags` (and similar for
`cxxflags` and `ldflags`).
## Running Make
! When you have a proper configuration, all you need to do to build the JDK is to
run `make`. (But see the warning at [GNU Make](#gnu-make) about running the
correct version of make.)
When running `make` without any arguments, the default target is used, which is
the same as running `make default` or `make jdk`. This will build a minimal (or
*** 804,814 ****
Multiple Configurations](#using-multiple-configurations)
#### Test Make Control Variables
These make control variables only make sense when running tests. Please see
! [Testing OpenJDK](testing.html) for details.
* `TEST`
* `TEST_JOBS`
* `JTREG`
* `GTEST`
--- 805,815 ----
Multiple Configurations](#using-multiple-configurations)
#### Test Make Control Variables
These make control variables only make sense when running tests. Please see
! [Testing the JDK](testing.html) for details.
* `TEST`
* `TEST_JOBS`
* `JTREG`
* `GTEST`
*** 824,834 ****
* `COMPARE_BUILD`
* `JDK_FILTER`
## Running Tests
! Most of the OpenJDK tests are using the [JTReg](http://openjdk.java.net/jtreg)
test framework. Make sure that your configuration knows where to find your
installation of JTReg. If this is not picked up automatically, use the
`--with-jtreg=<path to jtreg home>` option to point to the JTReg framework.
Note that this option should point to the JTReg home, i.e. the top directory,
containing `lib/jtreg.jar` etc.
--- 825,835 ----
* `COMPARE_BUILD`
* `JDK_FILTER`
## Running Tests
! Most of the JDK tests are using the [JTReg](http://openjdk.java.net/jtreg)
test framework. Make sure that your configuration knows where to find your
installation of JTReg. If this is not picked up automatically, use the
`--with-jtreg=<path to jtreg home>` option to point to the JTReg framework.
Note that this option should point to the JTReg home, i.e. the top directory,
containing `lib/jtreg.jar` etc.
*** 843,853 ****
```
make run-test-tier1
```
For more details on how to run tests, please see the [Testing
! OpenJDK](testing.html) document.
## Cross-compiling
Cross-compiling means using one platform (the *build* platform) to generate
output that can ran on another platform (the *target* platform).
--- 844,854 ----
```
make run-test-tier1
```
For more details on how to run tests, please see the [Testing
! the JDK](testing.html) document.
## Cross-compiling
Cross-compiling means using one platform (the *build* platform) to generate
output that can ran on another platform (the *target* platform).
*** 858,873 ****
arise when building for embedded is due to this separation of *build* and
*target* systems.
This requires a more complex setup and build procedure. This section assumes
you are familiar with cross-compiling in general, and will only deal with the
! particularities of cross-compiling OpenJDK. If you are new to cross-compiling,
please see the [external links at Wikipedia](
https://en.wikipedia.org/wiki/Cross_compiler#External_links) for a good start
on reading materials.
! Cross-compiling OpenJDK requires you to be able to build both for the build
platform and for the target platform. The reason for the former is that we need
to build and execute tools during the build process, both native tools and Java
tools.
If all you want to do is to compile a 32-bit version, for the same OS, on a
--- 859,874 ----
arise when building for embedded is due to this separation of *build* and
*target* systems.
This requires a more complex setup and build procedure. This section assumes
you are familiar with cross-compiling in general, and will only deal with the
! particularities of cross-compiling the JDK. If you are new to cross-compiling,
please see the [external links at Wikipedia](
https://en.wikipedia.org/wiki/Cross_compiler#External_links) for a good start
on reading materials.
! Cross-compiling the JDK requires you to be able to build both for the build
platform and for the target platform. The reason for the former is that we need
to build and execute tools during the build process, both native tools and Java
tools.
If all you want to do is to compile a 32-bit version, for the same OS, on a
*** 1022,1034 ****
A common cross-compilation target is the ARM CPU. When building for ARM, it is
useful to set the ABI profile. A number of pre-defined ABI profiles are
available using `--with-abi-profile`: arm-vfp-sflt, arm-vfp-hflt, arm-sflt,
armv5-vfp-sflt, armv6-vfp-hflt. Note that soft-float ABIs are no longer
! properly supported on OpenJDK.
! OpenJDK contains two different ports for the aarch64 platform, one is the
original aarch64 port from the [AArch64 Port Project](
http://openjdk.java.net/projects/aarch64-port) and one is a 64-bit version of
the Oracle contributed ARM port. When targeting aarch64, by the default the
original aarch64 port is used. To select the Oracle ARM 64 port, use
`--with-cpu-port=arm64`. Also set the corresponding value (`aarch64` or
--- 1023,1035 ----
A common cross-compilation target is the ARM CPU. When building for ARM, it is
useful to set the ABI profile. A number of pre-defined ABI profiles are
available using `--with-abi-profile`: arm-vfp-sflt, arm-vfp-hflt, arm-sflt,
armv5-vfp-sflt, armv6-vfp-hflt. Note that soft-float ABIs are no longer
! properly supported by the JDK.
! The JDK contains two different ports for the aarch64 platform, one is the
original aarch64 port from the [AArch64 Port Project](
http://openjdk.java.net/projects/aarch64-port) and one is a 64-bit version of
the Oracle contributed ARM port. When targeting aarch64, by the default the
original aarch64 port is used. To select the Oracle ARM 64 port, use
`--with-cpu-port=arm64`. Also set the corresponding value (`aarch64` or
*** 1045,1055 ****
Copy these folders to your *target* system. Then you can run e.g.
`images/jdk/bin/java -version`.
## Build Performance
! Building OpenJDK requires a lot of horsepower. Some of the build tools can be
adjusted to utilize more or less of resources such as parallel threads and
memory. The `configure` script analyzes your system and selects reasonable
values for such options based on your hardware. If you encounter resource
problems, such as out of memory conditions, you can modify the detected values
with:
--- 1046,1056 ----
Copy these folders to your *target* system. Then you can run e.g.
`images/jdk/bin/java -version`.
## Build Performance
! Building the JDK requires a lot of horsepower. Some of the build tools can be
adjusted to utilize more or less of resources such as parallel threads and
memory. The `configure` script analyzes your system and selects reasonable
values for such options based on your hardware. If you encounter resource
problems, such as out of memory conditions, you can modify the detected values
with:
*** 1090,1105 ****
as well as (if possible) the build tools.
### Virus Checking
The use of virus checking software, especially on Windows, can *significantly*
! slow down building of OpenJDK. If possible, turn off such software, or exclude
! the directory containing the OpenJDK source code from on-the-fly checking.
### Ccache
! The OpenJDK build supports building with ccache when using gcc or clang. Using
ccache can radically speed up compilation of native code if you often rebuild
the same sources. Your milage may vary however, so we recommend evaluating it
for yourself. To enable it, make sure it's on the path and configure with
`--enable-ccache`.
--- 1091,1106 ----
as well as (if possible) the build tools.
### Virus Checking
The use of virus checking software, especially on Windows, can *significantly*
! slow down building of the JDK. If possible, turn off such software, or exclude
! the directory containing the JDK source code from on-the-fly checking.
### Ccache
! The JDK build supports building with ccache when using gcc or clang. Using
ccache can radically speed up compilation of native code if you often rebuild
the same sources. Your milage may vary however, so we recommend evaluating it
for yourself. To enable it, make sure it's on the path and configure with
`--enable-ccache`.
*** 1115,1125 ****
### Icecc / icecream
[icecc/icecream](http://github.com/icecc/icecream) is a simple way to setup a
distributed compiler network. If you have multiple machines available for
! building OpenJDK, you can drastically cut individual build times by utilizing
it.
To use, setup an icecc network, and install icecc on the build machine. Then
run `configure` using `--enable-icecc`.
--- 1116,1126 ----
### Icecc / icecream
[icecc/icecream](http://github.com/icecc/icecream) is a simple way to setup a
distributed compiler network. If you have multiple machines available for
! building the JDK, you can drastically cut individual build times by utilizing
it.
To use, setup an icecc network, and install icecc on the build machine. Then
run `configure` using `--enable-icecc`.
*** 1224,1236 ****
Most of the time, the build will fail due to incorrect changes in the source
code.
Sometimes the build can fail with no apparent changes that have caused the
! failure. If this is the first time you are building OpenJDK on this particular
computer, and the build fails, the problem is likely with your build
! environment. But even if you have previously built OpenJDK with success, and it
now fails, your build environment might have changed (perhaps due to OS
upgrades or similar). But most likely, such failures are due to problems with
the incremental rebuild.
#### Problems with the Build Environment
--- 1225,1237 ----
Most of the time, the build will fail due to incorrect changes in the source
code.
Sometimes the build can fail with no apparent changes that have caused the
! failure. If this is the first time you are building the JDK on this particular
computer, and the build fails, the problem is likely with your build
! environment. But even if you have previously built the JDK with success, and it
now fails, your build environment might have changed (perhaps due to OS
upgrades or similar). But most likely, such failures are due to problems with
the incremental rebuild.
#### Problems with the Build Environment
*** 1241,1251 ****
`$BUILD/configure.log`.
Verify that the summary at the end looks correct. Are you indeed using the Boot
JDK and native toolchain that you expect?
! By default, OpenJDK has a strict approach where warnings from the compiler is
considered errors which fail the build. For very new or very old compiler
versions, this can trigger new classes of warnings, which thus fails the build.
Run `configure` with `--disable-warnings-as-errors` to turn of this behavior.
(The warnings will still show, but not make the build fail.)
--- 1242,1252 ----
`$BUILD/configure.log`.
Verify that the summary at the end looks correct. Are you indeed using the Boot
JDK and native toolchain that you expect?
! By default, the JDK has a strict approach where warnings from the compiler is
considered errors which fail the build. For very new or very old compiler
versions, this can trigger new classes of warnings, which thus fails the build.
Run `configure` with `--disable-warnings-as-errors` to turn of this behavior.
(The warnings will still show, but not make the build fail.)
*** 1339,1360 ****
If none of the suggestions in this document helps you, or if you find what you
believe is a bug in the build system, please contact the Build Group by sending
a mail to [build-dev@openjdk.java.net](mailto:build-dev@openjdk.java.net).
Please include the relevant parts of the configure and/or build log.
! If you need general help or advice about developing for OpenJDK, you can also
contact the Adoption Group. See the section on [Contributing to OpenJDK](
#contributing-to-openjdk) for more information.
## Hints and Suggestions for Advanced Users
### Setting Up a Forest for Pushing Changes (defpath)
To help you prepare a proper push path for a Mercurial repository, there exists
a useful tool known as [defpath](
http://openjdk.java.net/projects/code-tools/defpath). It will help you setup a
! proper push path for pushing changes to OpenJDK.
Install the extension by cloning
`http://hg.openjdk.java.net/code-tools/defpath` and updating your `.hgrc` file.
Here's one way to do this:
--- 1340,1361 ----
If none of the suggestions in this document helps you, or if you find what you
believe is a bug in the build system, please contact the Build Group by sending
a mail to [build-dev@openjdk.java.net](mailto:build-dev@openjdk.java.net).
Please include the relevant parts of the configure and/or build log.
! If you need general help or advice about developing for the JDK, you can also
contact the Adoption Group. See the section on [Contributing to OpenJDK](
#contributing-to-openjdk) for more information.
## Hints and Suggestions for Advanced Users
### Setting Up a Forest for Pushing Changes (defpath)
To help you prepare a proper push path for a Mercurial repository, there exists
a useful tool known as [defpath](
http://openjdk.java.net/projects/code-tools/defpath). It will help you setup a
! proper push path for pushing changes to the JDK.
Install the extension by cloning
`http://hg.openjdk.java.net/code-tools/defpath` and updating your `.hgrc` file.
Here's one way to do this:
*** 1458,1468 ****
product.
#### Building Individual Modules
The safe way to use fine-grained make targets is to use the module specific
! make targets. All source code in OpenJDK is organized so it belongs to a
module, e.g. `java.base` or `jdk.jdwp.agent`. You can build only a specific
module, by giving it as make target: `make jdk.jdwp.agent`. If the specified
module depends on other modules (e.g. `java.base`), those modules will be built
first.
--- 1459,1469 ----
product.
#### Building Individual Modules
The safe way to use fine-grained make targets is to use the module specific
! make targets. All source code in the JDK is organized so it belongs to a
module, e.g. `java.base` or `jdk.jdwp.agent`. You can build only a specific
module, by giving it as make target: `make jdk.jdwp.agent`. If the specified
module depends on other modules (e.g. `java.base`), those modules will be built
first.
*** 1510,1531 ****
jdk.jdwp.agent`) and then on subsequent builds, use the `-only` make target.
#### Rebuilding Part of java.base (JDK\_FILTER)
If you are modifying files in `java.base`, which is the by far largest module
! in OpenJDK, then you need to rebuild all those files whenever a single file has
changed. (This inefficiency will hopefully be addressed in JDK 10.)
As a hack, you can use the make control variable `JDK_FILTER` to specify a
pattern that will be used to limit the set of files being recompiled. For
instance, `make java.base JDK_FILTER=javax/crypto` (or, to combine methods,
`make java.base-java-only JDK_FILTER=javax/crypto`) will limit the compilation
to files in the `javax.crypto` package.
### Learn About Mercurial
! To become an efficient OpenJDK developer, it is recommended that you invest in
learning Mercurial properly. Here are some links that can get you started:
* [Mercurial for git users](http://www.mercurial-scm.org/wiki/GitConcepts)
* [The official Mercurial tutorial](http://www.mercurial-scm.org/wiki/Tutorial)
* [hg init](http://hginit.com/)
--- 1511,1532 ----
jdk.jdwp.agent`) and then on subsequent builds, use the `-only` make target.
#### Rebuilding Part of java.base (JDK\_FILTER)
If you are modifying files in `java.base`, which is the by far largest module
! in the JDK, then you need to rebuild all those files whenever a single file has
changed. (This inefficiency will hopefully be addressed in JDK 10.)
As a hack, you can use the make control variable `JDK_FILTER` to specify a
pattern that will be used to limit the set of files being recompiled. For
instance, `make java.base JDK_FILTER=javax/crypto` (or, to combine methods,
`make java.base-java-only JDK_FILTER=javax/crypto`) will limit the compilation
to files in the `javax.crypto` package.
### Learn About Mercurial
! To become an efficient JDK developer, it is recommended that you invest in
learning Mercurial properly. Here are some links that can get you started:
* [Mercurial for git users](http://www.mercurial-scm.org/wiki/GitConcepts)
* [The official Mercurial tutorial](http://www.mercurial-scm.org/wiki/Tutorial)
* [hg init](http://hginit.com/)
*** 1597,1607 ****
Windows path typically look like `C:\User\foo`, while Unix paths look like
`/home/foo`. Tools with roots from Unix often experience issues related to this
mismatch when running on Windows.
! In the OpenJDK build, we always use Unix paths internally, and only just before
calling a tool that does not understand Unix paths do we convert them to
Windows paths.
This conversion is done by the `fixpath` tool, which is a small wrapper that
modifies unix-style paths to Windows-style paths in command lines. Fixpath is
--- 1598,1608 ----
Windows path typically look like `C:\User\foo`, while Unix paths look like
`/home/foo`. Tools with roots from Unix often experience issues related to this
mismatch when running on Windows.
! In the JDK build, we always use Unix paths internally, and only just before
calling a tool that does not understand Unix paths do we convert them to
Windows paths.
This conversion is done by the `fixpath` tool, which is a small wrapper that
modifies unix-style paths to Windows-style paths in command lines. Fixpath is
*** 1612,1622 ****
Native libraries and executables can have debug symbol (and other debug
information) associated with them. How this works is very much platform
dependent, but a common problem is that debug symbol information takes a lot of
disk space, but is rarely needed by the end user.
! The OpenJDK supports different methods on how to handle debug symbols. The
method used is selected by `--with-native-debug-symbols`, and available methods
are `none`, `internal`, `external`, `zipped`.
* `none` means that no debug symbols will be generated during the build.
--- 1613,1623 ----
Native libraries and executables can have debug symbol (and other debug
information) associated with them. How this works is very much platform
dependent, but a common problem is that debug symbol information takes a lot of
disk space, but is rarely needed by the end user.
! The JDK supports different methods on how to handle debug symbols. The
method used is selected by `--with-native-debug-symbols`, and available methods
are `none`, `internal`, `external`, `zipped`.
* `none` means that no debug symbols will be generated during the build.
*** 1637,1647 ****
### Autoconf Details
The `configure` script is based on the autoconf framework, but in some details
deviate from a normal autoconf `configure` script.
! The `configure` script in the top level directory of OpenJDK is just a thin
wrapper that calls `make/autoconf/configure`. This in turn will run `autoconf`
to create the runnable (generated) configure script, as
`.build/generated-configure.sh`. Apart from being responsible for the
generation of the runnable script, the `configure` script also provides
functionality that is not easily expressed in the normal Autoconf framework. As
--- 1638,1648 ----
### Autoconf Details
The `configure` script is based on the autoconf framework, but in some details
deviate from a normal autoconf `configure` script.
! The `configure` script in the top level directory of the JDK is just a thin
wrapper that calls `make/autoconf/configure`. This in turn will run `autoconf`
to create the runnable (generated) configure script, as
`.build/generated-configure.sh`. Apart from being responsible for the
generation of the runnable script, the `configure` script also provides
functionality that is not easily expressed in the normal Autoconf framework. As
*** 1649,1668 ****
The build system will detect if the Autoconf source files have changed, and
will trigger a regeneration of the generated script if needed. You can also
manually request such an update by `bash configure autogen`.
! In previous versions of the OpenJDK, the generated script was checked in at
`make/autoconf/generated-configure.sh`. This is no longer the case.
### Developing the Build System Itself
This section contains a few remarks about how to develop for the build system
itself. It is not relevant if you are only making changes in the product source
code.
! While technically using `make`, the make source files of the OpenJDK does not
resemble most other Makefiles. Instead of listing specific targets and actions
(perhaps using patterns), the basic modus operandi is to call a high-level
function (or properly, macro) from the API in `make/common`. For instance, to
compile all classes in the `jdk.internal.foo` package in the `jdk.foo` module,
a call like this would be made:
--- 1650,1669 ----
The build system will detect if the Autoconf source files have changed, and
will trigger a regeneration of the generated script if needed. You can also
manually request such an update by `bash configure autogen`.
! In previous versions of the JDK, the generated script was checked in at
`make/autoconf/generated-configure.sh`. This is no longer the case.
### Developing the Build System Itself
This section contains a few remarks about how to develop for the build system
itself. It is not relevant if you are only making changes in the product source
code.
! While technically using `make`, the make source files of the JDK does not
resemble most other Makefiles. Instead of listing specific targets and actions
(perhaps using patterns), the basic modus operandi is to call a high-level
function (or properly, macro) from the API in `make/common`. For instance, to
compile all classes in the `jdk.internal.foo` package in the `jdk.foo` module,
a call like this would be made:
*** 1703,1719 ****
Please check that you adhere to the [Code Conventions for the Build System](
http://openjdk.java.net/groups/build/doc/code-conventions.html) before
submitting patches.
! ## Contributing to OpenJDK
! So, now you've build your OpenJDK, and made your first patch, and want to
! contribute it back to the OpenJDK community.
! First of all: Thank you! We gladly welcome your contribution to the OpenJDK.
! However, please bear in mind that OpenJDK is a massive project, and we must ask
you to follow our rules and guidelines to be able to accept your contribution.
The official place to start is the ['How to contribute' page](
http://openjdk.java.net/contribute/). There is also an official (but somewhat
outdated and skimpy on details) [Developer's Guide](
--- 1704,1720 ----
Please check that you adhere to the [Code Conventions for the Build System](
http://openjdk.java.net/groups/build/doc/code-conventions.html) before
submitting patches.
! ## Contributing to the JDK
! So, now you've built your JDK, and made your first patch, and want to
! contribute it back to the OpenJDK Community.
! First of all: Thank you! We gladly welcome your contribution.
! However, please bear in mind that the JDK is a massive project, and we must ask
you to follow our rules and guidelines to be able to accept your contribution.
The official place to start is the ['How to contribute' page](
http://openjdk.java.net/contribute/). There is also an official (but somewhat
outdated and skimpy on details) [Developer's Guide](
< prev index next >