--- a/doc/building.md Thu Jun 28 19:44:58 2018 +0530
+++ b/doc/building.md Thu Jun 28 07:30:38 2018 -0700
@@ -1,10 +1,10 @@
-% Building OpenJDK
+% Building the JDK
## TL;DR (Instructions for the Impatient)
-If you are eager to try out building OpenJDK, these simple steps works most of
+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 OpenJDK repository that you want to build.
+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`
@@ -34,14 +34,14 @@
## Introduction
-OpenJDK is a complex software project. Building it requires a certain amount of
+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 OpenJDK and not build it yourself, this document is not
+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
-OpenJDK.
+JDK.
## Getting the Source Code
@@ -80,16 +80,16 @@
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.
+ 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 OpenJDK clone in a path under your Cygwin home
+ * 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 OpenJDK repository using the Cygwin command line `hg` client
+ * 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.
@@ -98,7 +98,7 @@
## Build Hardware Requirements
-OpenJDK is a massive project, and require machines ranging from decent to
+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.
@@ -127,15 +127,15 @@
## Operating System Requirements
-The mainline OpenJDK project supports Linux, Solaris, macOS, AIX and Windows.
+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, OpenJDK can be built on a wide range of versions of these operating
+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 OpenJDK. Such
+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.
@@ -148,27 +148,27 @@
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.
+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 the community to list successes or failures of
+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 OpenJDK.
+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 OpenJDK, and as such, requires
+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 a community effort to implement.)
+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
@@ -180,16 +180,16 @@
#### 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
+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 OpenJDK build process, and that can cause
+update tools that are used by the JDK build process, and that can cause
unexpected build problems.
-OpenJDK requires GNU Make 4.0 or greater on Windows. This is usually not a
+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.
@@ -229,22 +229,22 @@
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
+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, OpenJDK has been successfully compiled on macOS versions up to
+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. OpenJDK uses
+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 OpenJDK on Linux. The only general advice
+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.
@@ -269,7 +269,7 @@
## Native Compiler (Toolchain) Requirements
-Large portions of OpenJDK consists of native code, that needs to be compiled to
+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.
@@ -284,8 +284,8 @@
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
+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.
@@ -301,7 +301,7 @@
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
+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.
@@ -318,13 +318,13 @@
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 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 OpenJDK when
+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
@@ -333,7 +333,7 @@
`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
+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.
@@ -395,15 +395,16 @@
## 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.
+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, OpenJDK should be able to "build itself", so an
-up-to-date build of the current OpenJDK source is an acceptable alternative. If
+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.
@@ -411,20 +412,20 @@
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
+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 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
+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 OpenJDK \<VERSION\>. On rpm-based distros (like
+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
@@ -447,7 +448,7 @@
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.
+rather than bundling the JDK’s own copy.
* To install on an apt-based Linux, try running `sudo apt-get install
libfreetype6-dev`.
@@ -522,7 +523,7 @@
### Autoconf
-OpenJDK requires [Autoconf](http://www.gnu.org/software/autoconf) on all
+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
@@ -542,7 +543,7 @@
### GNU Make
-OpenJDK requires [GNU Make](http://www.gnu.org/software/make). No other flavors
+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
@@ -566,16 +567,16 @@
### GNU Bash
-OpenJDK requires [GNU Bash](http://www.gnu.org/software/bash). No other shells
+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 OpenJDK, you need a "configuration", which consists of a directory
+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 OpenJDK is built.
+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:
@@ -619,7 +620,7 @@
```
(Note that this help text also include general autoconf options, like
-`--dvidir`, that is not relevant to OpenJDK. To list only OpenJDK specific
+`--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
@@ -680,9 +681,9 @@
* `--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
+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`).
@@ -726,7 +727,7 @@
## Running Make
-When you have a proper configuration, all you need to do to build OpenJDK is to
+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.)
@@ -806,7 +807,7 @@
#### Test Make Control Variables
These make control variables only make sense when running tests. Please see
-[Testing OpenJDK](testing.html) for details.
+[Testing the JDK](testing.html) for details.
* `TEST`
* `TEST_JOBS`
@@ -826,7 +827,7 @@
## Running Tests
-Most of the OpenJDK tests are using the [JTReg](http://openjdk.java.net/jtreg)
+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.
@@ -845,7 +846,7 @@
```
For more details on how to run tests, please see the [Testing
-OpenJDK](testing.html) document.
+the JDK](testing.html) document.
## Cross-compiling
@@ -860,12 +861,12 @@
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,
+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 OpenJDK requires you to be able to build both for the build
+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.
@@ -1024,9 +1025,9 @@
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.
+properly supported by the JDK.
-OpenJDK contains two different ports for the aarch64 platform, one is the
+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
@@ -1047,7 +1048,7 @@
## Build Performance
-Building OpenJDK requires a lot of horsepower. Some of the build tools can be
+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
@@ -1092,12 +1093,12 @@
### 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.
+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 OpenJDK build supports building with ccache when using gcc or clang. Using
+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
@@ -1117,7 +1118,7 @@
[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
+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
@@ -1226,9 +1227,9 @@
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
+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 OpenJDK with success, and it
+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.
@@ -1243,7 +1244,7 @@
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
+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.
@@ -1341,7 +1342,7 @@
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
+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.
@@ -1352,7 +1353,7 @@
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.
+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.
@@ -1460,7 +1461,7 @@
#### 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
+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
@@ -1512,7 +1513,7 @@
#### 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
+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
@@ -1523,7 +1524,7 @@
### Learn About Mercurial
-To become an efficient OpenJDK developer, it is recommended that you invest in
+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)
@@ -1599,7 +1600,7 @@
`/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
+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.
@@ -1614,7 +1615,7 @@
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
+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`.
@@ -1639,7 +1640,7 @@
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
+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
@@ -1651,7 +1652,7 @@
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
+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
@@ -1660,7 +1661,7 @@
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
+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
@@ -1705,13 +1706,13 @@
http://openjdk.java.net/groups/build/doc/code-conventions.html) before
submitting patches.
-## Contributing to OpenJDK
+## Contributing to the JDK
-So, now you've build your OpenJDK, and made your first patch, and want to
-contribute it back to the OpenJDK community.
+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 to the OpenJDK.
-However, please bear in mind that OpenJDK is a massive project, and we must ask
+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](