doc/building.md
author ihse
Fri, 09 Mar 2018 19:12:07 +0100
changeset 49200 a19a6228cdb2
parent 49159 436f1e03fd04
child 49234 3375a8039fde
permissions -rw-r--r--
8199405: Bump lowest supported gcc to 4.8 Reviewed-by: erikj
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
     1
% Building OpenJDK
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
     2
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
     3
## TL;DR (Instructions for the Impatient)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
     4
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
     5
If you are eager to try out building OpenJDK, these simple steps works most of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
     6
the time. They assume that you have installed Mercurial (and Cygwin if running
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
     7
on Windows) and cloned the top-level OpenJDK repository that you want to build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
     8
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
     9
 1. [Get the complete source code](#getting-the-source-code): \
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
    10
    `hg clone http://hg.openjdk.java.net/jdk/jdk`
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    12
 2. [Run configure](#running-configure): \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    13
    `bash configure`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
    14
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    15
    If `configure` fails due to missing dependencies (to either the
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
    16
    [toolchain](#native-compiler-toolchain-requirements), [build tools](
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
    17
    #build-tools-requirements), [external libraries](
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    18
    #external-library-requirements) or the [boot JDK](#boot-jdk-requirements)),
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    19
    most of the time it prints a suggestion on how to resolve the situation on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    20
    your platform. Follow the instructions, and try running `bash configure`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    21
    again.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
    22
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    23
 3. [Run make](#running-make): \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    24
    `make images`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    25
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    26
 4. Verify your newly built JDK: \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    27
    `./build/*/images/jdk/bin/java -version`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    28
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    29
 5. [Run basic tests](##running-tests): \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    30
    `make run-test-tier1`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    31
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    32
If any of these steps failed, or if you want to know more about build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    33
requirements or build functionality, please continue reading this document.
44078
673240c54c2e 8176509: Use pandoc for converting build readme to html
ihse
parents: 41040
diff changeset
    34
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
    35
## Introduction
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
    36
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    37
OpenJDK is a complex software project. Building it requires a certain amount of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    38
technical expertise, a fair number of dependencies on external software, and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    39
reasonably powerful hardware.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
    40
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    41
If you just want to use OpenJDK and not build it yourself, this document is not
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    42
for you. See for instance [OpenJDK installation](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    43
http://openjdk.java.net/install) for some methods of installing a prebuilt
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
    44
OpenJDK.
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
    45
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    46
## Getting the Source Code
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    47
47217
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
    48
Make sure you are getting the correct version. As of JDK 10, the source is no
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
    49
longer split into separate repositories so you only need to clone one single
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
    50
repository. At the [OpenJDK Mercurial server](http://hg.openjdk.java.net/) you
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
    51
can see a list of all available forests. If you want to build an older version,
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
    52
e.g. JDK 8, it is recommended that you get the `jdk8u` forest, which contains
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
    53
incremental updates, instead of the `jdk8` forest, which was frozen at JDK 8 GA.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    54
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    55
If you are new to Mercurial, a good place to start is the [Mercurial Beginner's
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    56
Guide](http://www.mercurial-scm.org/guide). The rest of this document assumes a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    57
working knowledge of Mercurial.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    58
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    59
### Special Considerations
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    60
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    61
For a smooth building experience, it is recommended that you follow these rules
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    62
on where and how to check out the source code.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    63
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    64
  * Do not check out the source code in a path which contains spaces. Chances
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    65
    are the build will not work. This is most likely to be an issue on Windows
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    66
    systems.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    67
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    68
  * Do not check out the source code in a path which has a very long name or is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    69
    nested many levels deep. Chances are you will hit an OS limitation during
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    70
    the build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    71
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    72
  * Put the source code on a local disk, not a network share. If possible, use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    73
    an SSD. The build process is very disk intensive, and having slow disk
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    74
    access will significantly increase build times. If you need to use a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    75
    network share for the source code, see below for suggestions on how to keep
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    76
    the build artifacts on a local disk.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    77
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    78
  * On Windows, extra care must be taken to make sure the [Cygwin](#cygwin)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    79
    environment is consistent. It is recommended that you follow this
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    80
    procedure:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    81
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    82
      * Create the directory that is going to contain the top directory of the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    83
        OpenJDK clone by using the `mkdir` command in the Cygwin bash shell.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    84
        That is, do *not* create it using Windows Explorer. This will ensure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    85
        that it will have proper Cygwin attributes, and that it's children will
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    86
        inherit those attributes.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    87
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    88
      * Do not put the OpenJDK clone in a path under your Cygwin home
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    89
        directory. This is especially important if your user name contains
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    90
        spaces and/or mixed upper and lower case letters.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    91
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    92
      * Clone the OpenJDK repository using the Cygwin command line `hg` client
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    93
        as instructed in this document. That is, do *not* use another Mercurial
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    94
        client such as TortoiseHg.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    95
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    96
    Failure to follow this procedure might result in hard-to-debug build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    97
    problems.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    98
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    99
## Build Hardware Requirements
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   100
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   101
OpenJDK is a massive project, and require machines ranging from decent to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   102
powerful to be able to build in a reasonable amount of time, or to be able to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   103
complete a build at all.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   104
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   105
We *strongly* recommend usage of an SSD disk for the build, since disk speed is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   106
one of the limiting factors for build performance.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   107
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   108
### Building on x86
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   109
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   110
At a minimum, a machine with 2-4 cores is advisable, as well as 2-4 GB of RAM.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   111
(The more cores to use, the more memory you need.) At least 6 GB of free disk
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   112
space is required (8 GB minimum for building on Solaris).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   113
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   114
Even for 32-bit builds, it is recommended to use a 64-bit build machine, and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   115
instead create a 32-bit target using `--with-target-bits=32`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   116
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   117
### Building on sparc
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   118
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   119
At a minimum, a machine with 4 cores is advisable, as well as 4 GB of RAM. (The
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   120
more cores to use, the more memory you need.) At least 8 GB of free disk space
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   121
is required.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   122
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   123
### Building on arm/aarch64
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   124
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   125
This is not recommended. Instead, see the section on [Cross-compiling](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   126
#cross-compiling).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   127
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   128
## Operating System Requirements
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   129
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   130
The mainline OpenJDK project supports Linux, Solaris, macOS, AIX and Windows.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   131
Support for other operating system, e.g. BSD, exists in separate "port"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   132
projects.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   133
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   134
In general, OpenJDK can be built on a wide range of versions of these operating
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   135
systems, but the further you deviate from what is tested on a daily basis, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   136
more likely you are to run into problems.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   137
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   138
This table lists the OS versions used by Oracle when building JDK 9. Such
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   139
information is always subject to change, but this table is up to date at the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   140
time of writing.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   141
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   142
 Operating system   Vendor/version used
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   143
 -----------------  -------------------------------------------------------
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   144
 Linux              Oracle Enterprise Linux 6.4 / 7.1 (using kernel 3.8.13)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   145
 Solaris            Solaris 11.1 SRU 21.4.1 / 11.2 SRU 5.5
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   146
 macOS              Mac OS X 10.9 (Mavericks) / 10.10 (Yosemite)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   147
 Windows            Windows Server 2012 R2
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   148
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   149
The double version numbers for Linux, Solaris and macOS is due to the hybrid
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   150
model used at Oracle, where header files and external libraries from an older
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   151
version is used when building on a more modern version of the OS.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   152
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   153
The Build Group has a wiki page with [Supported Build Platforms](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   154
https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms). From
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   155
time to time, this is updated by the community to list successes or failures of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   156
building on different platforms.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   157
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   158
### Windows
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   159
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   160
Windows XP is not a supported platform, but all newer Windows should be able to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   161
build OpenJDK.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   162
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   163
On Windows, it is important that you pay attention to the instructions in the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   164
[Special Considerations](#special-considerations).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   165
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   166
Windows is the only non-POSIX OS supported by OpenJDK, and as such, requires
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   167
some extra care. A POSIX support layer is required to build on Windows. For
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   168
OpenJDK 9, the only supported such layer is Cygwin. (Msys is no longer
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   169
supported due to a too old bash; msys2 and the new Windows Subsystem for Linux
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   170
(WSL) would likely be possible to support in a future version but that would
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   171
require a community effort to implement.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   172
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   173
Internally in the build system, all paths are represented as Unix-style paths,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   174
e.g. `/cygdrive/c/hg/jdk9/Makefile` rather than `C:\hg\jdk9\Makefile`. This
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   175
rule also applies to input to the build system, e.g. in arguments to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   176
`configure`. So, use `--with-freetype=/cygdrive/c/freetype` rather than
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   177
`--with-freetype=c:\freetype`. For details on this conversion, see the section
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   178
on [Fixpath](#fixpath).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   179
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   180
#### Cygwin
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   181
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   182
A functioning [Cygwin](http://www.cygwin.com/) environment is thus required for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   183
building OpenJDK on Windows. If you have a 64-bit OS, we strongly recommend
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   184
using the 64-bit version of Cygwin.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   185
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   186
**Note:** Cygwin has a model of continuously updating all packages without any
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   187
easy way to install or revert to a specific version of a package. This means
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   188
that whenever you add or update a package in Cygwin, you might (inadvertently)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   189
update tools that are used by the OpenJDK build process, and that can cause
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   190
unexpected build problems.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   191
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   192
OpenJDK requires GNU Make 4.0 or greater on Windows. This is usually not a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   193
problem, since Cygwin currently only distributes GNU Make at a version above
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   194
4.0.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   195
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   196
Apart from the basic Cygwin installation, the following packages must also be
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   197
installed:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   198
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   199
  * `autoconf`
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   200
  * `make`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   201
  * `zip`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   202
  * `unzip`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   203
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   204
Often, you can install these packages using the following command line:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   205
```
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   206
<path to Cygwin setup>/setup-x86_64 -q -P autoconf -P make -P unzip -P zip
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   207
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   208
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   209
Unfortunately, Cygwin can be unreliable in certain circumstances. If you
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   210
experience build tool crashes or strange issues when building on Windows,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   211
please check the Cygwin FAQ on the ["BLODA" list](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   212
https://cygwin.com/faq/faq.html#faq.using.bloda) and the section on [fork()
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   213
failures](https://cygwin.com/faq/faq.html#faq.using.fixing-fork-failures).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   214
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   215
### Solaris
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   216
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   217
See `make/devkit/solaris11.1-package-list.txt` for a list of recommended
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   218
packages to install when building on Solaris. The versions specified in this
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   219
list is the versions used by the daily builds at Oracle, and is likely to work
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   220
properly.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   221
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   222
Older versions of Solaris shipped a broken version of `objcopy`. At least
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   223
version 2.21.1 is needed, which is provided by Solaris 11 Update 1. Objcopy is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   224
needed if you want to have external debug symbols. Please make sure you are
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   225
using at least version 2.21.1 of objcopy, or that you disable external debug
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   226
symbols.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   227
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   228
### macOS
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   229
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   230
Apple is using a quite aggressive scheme of pushing OS updates, and coupling
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   231
these updates with required updates of Xcode. Unfortunately, this makes it
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   232
difficult for a project like OpenJDK to keep pace with a continuously updated
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   233
machine running macOS. See the section on [Apple Xcode](#apple-xcode) on some
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   234
strategies to deal with this.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   235
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   236
It is recommended that you use at least Mac OS X 10.9 (Mavericks). At the time
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   237
of writing, OpenJDK has been successfully compiled on macOS versions up to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   238
10.12.5 (Sierra), using XCode 8.3.2 and `--disable-warnings-as-errors`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   239
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   240
The standard macOS environment contains the basic tooling needed to build, but
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   241
for external libraries a package manager is recommended. OpenJDK uses
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   242
[homebrew](https://brew.sh/) in the examples, but feel free to use whatever
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   243
manager you want (or none).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   244
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   245
### Linux
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   246
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   247
It is often not much problem to build OpenJDK on Linux. The only general advice
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   248
is to try to use the compilers, external libraries and header files as provided
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   249
by your distribution.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   250
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   251
The basic tooling is provided as part of the core operating system, but you
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   252
will most likely need to install developer packages.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   253
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   254
For apt-based distributions (Debian, Ubuntu, etc), try this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   255
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   256
sudo apt-get install build-essential
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   257
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   258
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   259
For rpm-based distributions (Fedora, Red Hat, etc), try this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   260
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   261
sudo yum groupinstall "Development Tools"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   262
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   263
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   264
### AIX
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   265
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   266
The regular builds by SAP is using AIX version 7.1, but AIX 5.3 is also
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   267
supported. See the [OpenJDK PowerPC Port Status Page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   268
http://cr.openjdk.java.net/~simonis/ppc-aix-port) for details.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   269
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   270
## Native Compiler (Toolchain) Requirements
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   271
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   272
Large portions of OpenJDK consists of native code, that needs to be compiled to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   273
be able to run on the target platform. In theory, toolchain and operating
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   274
system should be independent factors, but in practice there's more or less a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   275
one-to-one correlation between target operating system and toolchain.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   276
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   277
 Operating system   Supported toolchain
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   278
 ------------------ -------------------------
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   279
 Linux              gcc, clang
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   280
 macOS              Apple Xcode (using clang)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   281
 Solaris            Oracle Solaris Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   282
 AIX                IBM XL C/C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   283
 Windows            Microsoft Visual Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   284
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   285
Please see the individual sections on the toolchains for version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   286
recommendations. As a reference, these versions of the toolchains are used, at
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   287
the time of writing, by Oracle for the daily builds of OpenJDK. It should be
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   288
possible to compile OpenJDK with both older and newer versions, but the closer
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   289
you stay to this list, the more likely you are to compile successfully without
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   290
issues.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   291
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   292
 Operating system   Toolchain version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   293
 ------------------ -------------------------------------------------------
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   294
 Linux              gcc 4.9.2
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   295
 macOS              Apple Xcode 6.3 (using clang 6.1.0)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   296
 Solaris            Oracle Solaris Studio 12.4 (with compiler version 5.13)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   297
 Windows            Microsoft Visual Studio 2013 update 4
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   298
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   299
### gcc
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   300
47219
fd36993f7bf5 8187542: Remove superfluous *_TOPDIR variables
ihse
parents: 47217
diff changeset
   301
The minimum accepted version of gcc is 4.7. Older versions will generate a warning
45877
640f1904ebb8 8184338: switch minimum supported gcc version to 4.7
mbaesken
parents: 45763
diff changeset
   302
by `configure` and are unlikely to work.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   303
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   304
OpenJDK 9 includes patches that should allow gcc 6 to compile, but this should
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   305
be considered experimental.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   306
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   307
In general, any version between these two should be usable.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   308
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   309
### clang
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   310
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   311
The minimum accepted version of clang is 3.2. Older versions will not be
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   312
accepted by `configure`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   313
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   314
To use clang instead of gcc on Linux, use `--with-toolchain-type=clang`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   315
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   316
### Apple Xcode
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   317
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   318
The oldest supported version of Xcode is 5.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   319
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   320
You will need the Xcode command lines developers tools to be able to build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   321
OpenJDK. (Actually, *only* the command lines tools are needed, not the IDE.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   322
The simplest way to install these is to run:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   323
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   324
xcode-select --install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   325
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   326
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   327
It is advisable to keep an older version of Xcode for building OpenJDK when
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   328
updating Xcode. This [blog page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   329
http://iosdevelopertips.com/xcode/install-multiple-versions-of-xcode.html) has
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   330
good suggestions on managing multiple Xcode versions. To use a specific version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   331
of Xcode, use `xcode-select -s` before running `configure`, or use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   332
`--with-toolchain-path` to point to the version of Xcode to use, e.g.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   333
`configure --with-toolchain-path=/Applications/Xcode5.app/Contents/Developer/usr/bin`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   334
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   335
If you have recently (inadvertently) updated your OS and/or Xcode version, and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   336
OpenJDK can no longer be built, please see the section on [Problems with the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   337
Build Environment](#problems-with-the-build-environment), and [Getting
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   338
Help](#getting-help) to find out if there are any recent, non-merged patches
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   339
available for this update.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   340
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   341
### Oracle Solaris Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   342
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   343
The minimum accepted version of the Solaris Studio compilers is 5.13
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   344
(corresponding to Solaris Studio 12.4). Older versions will not be accepted by
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   345
configure.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   346
34595
09596fe63e2d 8145391: Updated jprt.properties, devtools, jib and readme with SS12u4
erikj
parents: 33030
diff changeset
   347
The Solaris Studio installation should contain at least these packages:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   348
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   349
 Package                                            Version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   350
 -------------------------------------------------- -------------
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   351
 developer/solarisstudio-124/backend                12.4-1.0.6.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   352
 developer/solarisstudio-124/c++                    12.4-1.0.10.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   353
 developer/solarisstudio-124/cc                     12.4-1.0.4.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   354
 developer/solarisstudio-124/library/c++-libs       12.4-1.0.10.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   355
 developer/solarisstudio-124/library/math-libs      12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   356
 developer/solarisstudio-124/library/studio-gccrt   12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   357
 developer/solarisstudio-124/studio-common          12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   358
 developer/solarisstudio-124/studio-ja              12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   359
 developer/solarisstudio-124/studio-legal           12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   360
 developer/solarisstudio-124/studio-zhCN            12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   361
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   362
Compiling with Solaris Studio can sometimes be finicky. This is the exact
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   363
version used by Oracle, which worked correctly at the time of writing:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   364
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   365
$ cc -V
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   366
cc: Sun C 5.13 SunOS_i386 2014/10/20
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   367
$ CC -V
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   368
CC: Sun C++ 5.13 SunOS_i386 151846-10 2015/10/30
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   369
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   370
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   371
### Microsoft Visual Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   372
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   373
The minimum accepted version of Visual Studio is 2010. Older versions will not
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   374
be accepted by `configure`. The maximum accepted version of Visual Studio is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   375
2013.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   376
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   377
If you have multiple versions of Visual Studio installed, `configure` will by
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   378
default pick the latest. You can request a specific version to be used by
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   379
setting `--with-toolchain-version`, e.g. `--with-toolchain-version=2010`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   380
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   381
If you get `LINK: fatal error LNK1123: failure during conversion to COFF: file
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   382
invalid` when building using Visual Studio 2010, you have encountered
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   383
[KB2757355](http://support.microsoft.com/kb/2757355), a bug triggered by a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   384
specific installation order. However, the solution suggested by the KB article
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   385
does not always resolve the problem. See [this stackoverflow discussion](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   386
https://stackoverflow.com/questions/10888391) for other suggestions.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   387
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   388
### IBM XL C/C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   389
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   390
The regular builds by SAP is using version 12.1, described as `IBM XL C/C++ for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   391
AIX, V12.1 (5765-J02, 5725-C72) Version: 12.01.0000.0017`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   392
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   393
See the [OpenJDK PowerPC Port Status Page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   394
http://cr.openjdk.java.net/~simonis/ppc-aix-port) for details.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   395
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   396
## Boot JDK Requirements
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   397
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   398
Paradoxically, building OpenJDK requires a pre-existing JDK. This is called the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   399
"boot JDK". The boot JDK does not have to be OpenJDK, though. If you are
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   400
porting OpenJDK to a new platform, chances are that there already exists
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   401
another JDK for that platform that is usable as boot JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   402
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   403
The rule of thumb is that the boot JDK for building JDK major version *N*
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   404
should be a JDK of major version *N-1*, so for building JDK 9 a JDK 8 would be
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   405
suitable as boot JDK. However, OpenJDK should be able to "build itself", so an
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   406
up-to-date build of the current OpenJDK source is an acceptable alternative. If
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   407
you are following the *N-1* rule, make sure you've got the latest update
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   408
version, since JDK 8 GA might not be able to build JDK 9 on all platforms.
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   409
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   410
Early in the release cycle, version *N-1* may not yet have been released. In
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   411
that case, the preferred boot JDK will be version *N-2* until version *N-1*
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   412
is available.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   413
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   414
If the Boot JDK is not automatically detected, or the wrong JDK is picked, use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   415
`--with-boot-jdk` to point to the JDK to use.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   416
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   417
### Getting JDK binaries
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   418
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   419
OpenJDK binaries for Linux, Windows and macOS can be downloaded from
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   420
[jdk.java.net](http://jdk.java.net). An alternative is to download the
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   421
[Oracle JDK](http://www.oracle.com/technetwork/java/javase/downloads). Another
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   422
is the [Adopt OpenJDK Project](https://adoptopenjdk.net/), which publishes
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   423
experimental prebuilt binaries for various platforms.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   424
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   425
On Linux you can also get OpenJDK from the Linux distribution. On apt-based
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   426
distros (like Debian and Ubuntu), `sudo apt-get install openjdk-<VERSION>-jdk`
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   427
is typically enough to install OpenJDK \<VERSION\>. On rpm-based distros (like
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   428
Fedora and Red Hat), try `sudo yum install java-<VERSION>-openjdk-devel`.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   429
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   430
## External Library Requirements
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   431
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   432
Different platforms require different external libraries. In general, libraries
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   433
are not optional - that is, they are either required or not used.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   434
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   435
If a required library is not detected by `configure`, you need to provide the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   436
path to it. There are two forms of the `configure` arguments to point to an
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   437
external library: `--with-<LIB>=<path>` or `--with-<LIB>-include=<path to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   438
include> --with-<LIB>-lib=<path to lib>`. The first variant is more concise,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   439
but require the include files an library files to reside in a default hierarchy
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   440
under this directory. In most cases, it works fine.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   441
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   442
As a fallback, the second version allows you to point to the include directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   443
and the lib directory separately.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   444
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   445
### FreeType
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   446
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   447
FreeType2 from [The FreeType Project](http://www.freetype.org/) is required on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   448
all platforms. At least version 2.3 is required.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   449
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   450
  * To install on an apt-based Linux, try running `sudo apt-get install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   451
    libcups2-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   452
  * To install on an rpm-based Linux, try running `sudo yum install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   453
    cups-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   454
  * To install on Solaris, try running `pkg install system/library/freetype-2`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   455
  * To install on macOS, try running `brew install freetype`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   456
  * To install on Windows, see [below](#building-freetype-on-windows).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   457
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   458
Use `--with-freetype=<path>` if `configure` does not properly locate your
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   459
FreeType files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   460
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   461
#### Building FreeType on Windows
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   462
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   463
On Windows, there is no readily available compiled version of FreeType. OpenJDK
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   464
can help you compile FreeType from source. Download the FreeType sources and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   465
unpack them into an arbitrary directory:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   466
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   467
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   468
wget http://download.savannah.gnu.org/releases/freetype/freetype-2.5.3.tar.gz
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   469
tar -xzf freetype-2.5.3.tar.gz
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   470
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   471
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   472
Then run `configure` with `--with-freetype-src=<freetype_src>`. This will
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   473
automatically build the freetype library into `<freetype_src>/lib64` for 64-bit
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   474
builds or into `<freetype_src>/lib32` for 32-bit builds. Afterwards you can
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   475
always use `--with-freetype-include=<freetype_src>/include` and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   476
`--with-freetype-lib=<freetype_src>/lib[32|64]` for other builds.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   477
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   478
Alternatively you can unpack the sources like this to use the default
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   479
directory:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   480
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   481
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   482
tar --one-top-level=$HOME/freetype --strip-components=1 -xzf freetype-2.5.3.tar.gz
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   483
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   484
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   485
### CUPS
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   486
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   487
CUPS, [Common UNIX Printing System](http://www.cups.org) header files are
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   488
required on all platforms, except Windows. Often these files are provided by
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   489
your operating system.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   490
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   491
  * To install on an apt-based Linux, try running `sudo apt-get install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   492
    libcups2-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   493
  * To install on an rpm-based Linux, try running `sudo yum install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   494
    cups-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   495
  * To install on Solaris, try running `pkg install print/cups`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   496
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   497
Use `--with-cups=<path>` if `configure` does not properly locate your CUPS
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   498
files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   499
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   500
### X11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   501
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   502
Certain [X11](http://www.x.org/) libraries and include files are required on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   503
Linux and Solaris.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   504
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   505
  * To install on an apt-based Linux, try running `sudo apt-get install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   506
    libx11-dev libxext-dev libxrender-dev libxtst-dev libxt-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   507
  * To install on an rpm-based Linux, try running `sudo yum install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   508
    libXtst-devel libXt-devel libXrender-devel libXi-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   509
  * To install on Solaris, try running `pkg install x11/header/x11-protocols
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   510
    x11/library/libice x11/library/libpthread-stubs x11/library/libsm
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   511
    x11/library/libx11 x11/library/libxau x11/library/libxcb
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   512
    x11/library/libxdmcp x11/library/libxevie x11/library/libxext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   513
    x11/library/libxrender x11/library/libxscrnsaver x11/library/libxtst
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   514
    x11/library/toolkit/libxt`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   515
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   516
Use `--with-x=<path>` if `configure` does not properly locate your X11 files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   517
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   518
### ALSA
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   519
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   520
ALSA, [Advanced Linux Sound Architecture](https://www.alsa-project.org/) is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   521
required on Linux. At least version 0.9.1 of ALSA is required.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   522
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   523
  * To install on an apt-based Linux, try running `sudo apt-get install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   524
    libasound2-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   525
  * To install on an rpm-based Linux, try running `sudo yum install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   526
    alsa-lib-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   527
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   528
Use `--with-alsa=<path>` if `configure` does not properly locate your ALSA
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   529
files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   530
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   531
### libffi
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   532
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   533
libffi, the [Portable Foreign Function Interface Library](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   534
http://sourceware.org/libffi) is required when building the Zero version of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   535
Hotspot.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   536
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   537
  * To install on an apt-based Linux, try running `sudo apt-get install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   538
    libffi-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   539
  * To install on an rpm-based Linux, try running `sudo yum install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   540
    libffi-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   541
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   542
Use `--with-libffi=<path>` if `configure` does not properly locate your libffi
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   543
files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   544
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   545
## Build Tools Requirements
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   546
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   547
### Autoconf
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   548
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   549
OpenJDK requires [Autoconf](http://www.gnu.org/software/autoconf) on all
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   550
platforms. At least version 2.69 is required.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   551
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   552
  * To install on an apt-based Linux, try running `sudo apt-get install
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   553
    autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   554
  * To install on an rpm-based Linux, try running `sudo yum install
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   555
    autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   556
  * To install on macOS, try running `brew install autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   557
  * To install on Windows, try running `<path to Cygwin setup>/setup-x86_64 -q
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   558
    -P autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   559
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   560
If `configure` has problems locating your installation of autoconf, you can
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   561
specify it using the `AUTOCONF` environment variable, like this:
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   562
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   563
```
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   564
AUTOCONF=<path to autoconf> configure ...
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   565
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   566
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   567
### GNU Make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   568
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   569
OpenJDK requires [GNU Make](http://www.gnu.org/software/make). No other flavors
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   570
of make are supported.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   571
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   572
At least version 3.81 of GNU Make must be used. For distributions supporting
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   573
GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   574
functionality to handle parallel building (supported by `--with-output-sync`)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   575
and speed and stability improvements.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   576
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   577
Note that `configure` locates and verifies a properly functioning version of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   578
`make` and stores the path to this `make` binary in the configuration. If you
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   579
start a build using `make` on the command line, you will be using the version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   580
of make found first in your `PATH`, and not necessarily the one stored in the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   581
configuration. This initial make will be used as "bootstrap make", and in a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   582
second stage, the make located by `configure` will be called. Normally, this
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   583
will present no issues, but if you have a very old `make`, or a non-GNU Make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   584
`make` in your path, this might cause issues.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   585
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   586
If you want to override the default make found by `configure`, use the `MAKE`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   587
configure variable, e.g. `configure MAKE=/opt/gnu/make`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   588
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   589
On Solaris, it is common to call the GNU version of make by using `gmake`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   590
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   591
### GNU Bash
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   592
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   593
OpenJDK requires [GNU Bash](http://www.gnu.org/software/bash). No other shells
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   594
are supported.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   595
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   596
At least version 3.2 of GNU Bash must be used.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   597
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   598
## Running Configure
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   599
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   600
To build OpenJDK, you need a "configuration", which consists of a directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   601
where to store the build output, coupled with information about the platform,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   602
the specific build machine, and choices that affect how OpenJDK is built.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   603
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   604
The configuration is created by the `configure` script. The basic invocation of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   605
the `configure` script looks like this:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   606
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   607
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   608
bash configure [options]
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   609
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   610
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   611
This will create an output directory containing the configuration and setup an
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   612
area for the build result. This directory typically looks like
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   613
`build/linux-x64-normal-server-release`, but the actual name depends on your
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   614
specific configuration. (It can also be set directly, see [Using Multiple
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   615
Configurations](#using-multiple-configurations)). This directory is referred to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   616
as `$BUILD` in this documentation.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   617
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   618
`configure` will try to figure out what system you are running on and where all
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   619
necessary build components are. If you have all prerequisites for building
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   620
installed, it should find everything. If it fails to detect any component
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   621
automatically, it will exit and inform you about the problem.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   622
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   623
Some command line examples:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   624
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   625
  * Create a 32-bit build for Windows with FreeType2 in `C:\freetype-i586`:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   626
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   627
    bash configure --with-freetype=/cygdrive/c/freetype-i586 --with-target-bits=32
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   628
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   629
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   630
  * Create a debug build with the `server` JVM and DTrace enabled:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   631
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   632
    bash configure --enable-debug --with-jvm-variants=server --enable-dtrace
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   633
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   634
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   635
### Common Configure Arguments
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   636
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   637
Here follows some of the most common and important `configure` argument.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   638
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   639
To get up-to-date information on *all* available `configure` argument, please
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   640
run:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   641
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   642
bash configure --help
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   643
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   644
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   645
(Note that this help text also include general autoconf options, like
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   646
`--dvidir`, that is not relevant to OpenJDK. To list only OpenJDK specific
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   647
features, use `bash configure --help=short` instead.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   648
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   649
#### Configure Arguments for Tailoring the Build
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   650
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   651
  * `--enable-debug` - Set the debug level to `fastdebug` (this is a shorthand
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   652
    for `--with-debug-level=fastdebug`)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   653
  * `--with-debug-level=<level>` - Set the debug level, which can be `release`,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   654
    `fastdebug`, `slowdebug` or `optimized`. Default is `release`. `optimized`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   655
    is variant of `release` with additional Hotspot debug code.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   656
  * `--with-native-debug-symbols=<method>` - Specify if and how native debug
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   657
    symbols should be built. Available methods are `none`, `internal`,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   658
    `external`, `zipped`. Default behavior depends on platform. See [Native
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   659
    Debug Symbols](#native-debug-symbols) for more details.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   660
  * `--with-version-string=<string>` - Specify the version string this build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   661
    will be identified with.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   662
  * `--with-version-<part>=<value>` - A group of options, where `<part>` can be
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   663
    any of `pre`, `opt`, `build`, `major`, `minor`, `security` or `patch`. Use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   664
    these options to modify just the corresponding part of the version string
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   665
    from the default, or the value provided by `--with-version-string`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   666
  * `--with-jvm-variants=<variant>[,<variant>...]` - Build the specified variant
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   667
    (or variants) of Hotspot. Valid variants are: `server`, `client`,
47687
fb290fd1f9d4 8171853: Remove Shark compiler
rkennke
parents: 47219
diff changeset
   668
    `minimal`, `core`, `zero`, `custom`. Note that not all
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   669
    variants are possible to combine in a single build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   670
  * `--with-jvm-features=<feature>[,<feature>...]` - Use the specified JVM
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   671
    features when building Hotspot. The list of features will be enabled on top
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   672
    of the default list. For the `custom` JVM variant, this default list is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   673
    empty. A complete list of available JVM features can be found using `bash
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   674
    configure --help`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   675
  * `--with-target-bits=<bits>` - Create a target binary suitable for running
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   676
    on a `<bits>` platform. Use this to create 32-bit output on a 64-bit build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   677
    platform, instead of doing a full cross-compile. (This is known as a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   678
    *reduced* build.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   679
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   680
#### Configure Arguments for Native Compilation
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   681
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   682
  * `--with-devkit=<path>` - Use this devkit for compilers, tools and resources
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   683
  * `--with-sysroot=<path>` - Use this directory as sysroot
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   684
  * `--with-extra-path=<path>[;<path>]` - Prepend these directories to the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   685
    default path when searching for all kinds of binaries
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   686
  * `--with-toolchain-path=<path>[;<path>]` - Prepend these directories when
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   687
    searching for toolchain binaries (compilers etc)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   688
  * `--with-extra-cflags=<flags>` - Append these flags when compiling JDK C
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   689
    files
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   690
  * `--with-extra-cxxflags=<flags>` - Append these flags when compiling JDK C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   691
    files
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   692
  * `--with-extra-ldflags=<flags>` - Append these flags when linking JDK
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   693
    libraries
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   694
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   695
#### Configure Arguments for External Dependencies
44078
673240c54c2e 8176509: Use pandoc for converting build readme to html
ihse
parents: 41040
diff changeset
   696
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   697
  * `--with-boot-jdk=<path>` - Set the path to the [Boot JDK](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   698
    #boot-jdk-requirements)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   699
  * `--with-freetype=<path>` - Set the path to [FreeType](#freetype)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   700
  * `--with-cups=<path>` - Set the path to [CUPS](#cups)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   701
  * `--with-x=<path>` - Set the path to [X11](#x11)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   702
  * `--with-alsa=<path>` - Set the path to [ALSA](#alsa)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   703
  * `--with-libffi=<path>` - Set the path to [libffi](#libffi)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   704
  * `--with-jtreg=<path>` - Set the path to JTReg. See [Running Tests](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   705
    #running-tests)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   706
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   707
Certain third-party libraries used by OpenJDK (libjpeg, giflib, libpng, lcms
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   708
and zlib) are included in the OpenJDK repository. The default behavior of the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   709
OpenJDK build is to use this version of these libraries, but they might be
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   710
replaced by an external version. To do so, specify `system` as the `<source>`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   711
option in these arguments. (The default is `bundled`).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   712
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   713
  * `--with-libjpeg=<source>` - Use the specified source for libjpeg
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   714
  * `--with-giflib=<source>` - Use the specified source for giflib
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   715
  * `--with-libpng=<source>` - Use the specified source for libpng
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   716
  * `--with-lcms=<source>` - Use the specified source for lcms
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   717
  * `--with-zlib=<source>` - Use the specified source for zlib
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   718
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   719
On Linux, it is possible to select either static or dynamic linking of the C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   720
runtime. The default is static linking, with dynamic linking as fallback if the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   721
static library is not found.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   722
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   723
  * `--with-stdc++lib=<method>` - Use the specified method (`static`, `dynamic`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   724
    or `default`) for linking the C++ runtime.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   725
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   726
### Configure Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   727
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   728
It is possible to control certain aspects of `configure` by overriding the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   729
value of `configure` variables, either on the command line or in the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   730
environment.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   731
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   732
Normally, this is **not recommended**. If used improperly, it can lead to a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   733
broken configuration. Unless you're well versed in the build system, this is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   734
hard to use properly. Therefore, `configure` will print a warning if this is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   735
detected.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   736
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   737
However, there are a few `configure` variables, known as *control variables*
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   738
that are supposed to be overriden on the command line. These are variables that
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   739
describe the location of tools needed by the build, like `MAKE` or `GREP`. If
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   740
any such variable is specified, `configure` will use that value instead of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   741
trying to autodetect the tool. For instance, `bash configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   742
MAKE=/opt/gnumake4.0/bin/make`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   743
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   744
If a configure argument exists, use that instead, e.g. use `--with-jtreg`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   745
instead of setting `JTREGEXE`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   746
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   747
Also note that, despite what autoconf claims, setting `CFLAGS` will not
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   748
accomplish anything. Instead use `--with-extra-cflags` (and similar for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   749
`cxxflags` and `ldflags`).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   750
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   751
## Running Make
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   752
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   753
When you have a proper configuration, all you need to do to build OpenJDK is to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   754
run `make`. (But see the warning at [GNU Make](#gnu-make) about running the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   755
correct version of make.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   756
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   757
When running `make` without any arguments, the default target is used, which is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   758
the same as running `make default` or `make jdk`. This will build a minimal (or
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   759
roughly minimal) set of compiled output (known as an "exploded image") needed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   760
for a developer to actually execute the newly built JDK. The idea is that in an
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   761
incremental development fashion, when doing a normal make, you should only
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   762
spend time recompiling what's changed (making it purely incremental) and only
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   763
do the work that's needed to actually run and test your code.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   764
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   765
The output of the exploded image resides in `$BUILD/jdk`. You can test the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   766
newly built JDK like this: `$BUILD/jdk/bin/java -version`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   767
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   768
### Common Make Targets
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   769
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   770
Apart from the default target, here are some common make targets:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   771
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   772
  * `hotspot` - Build all of hotspot (but only hotspot)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   773
  * `hotspot-<variant>` - Build just the specified jvm variant
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   774
  * `images` or `product-images` - Build the JRE and JDK images
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   775
  * `docs` or `docs-image` - Build the documentation image
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   776
  * `test-image` - Build the test image
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   777
  * `all` or `all-images` - Build all images (product, docs and test)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   778
  * `bootcycle-images` - Build images twice, second time with newly built JDK
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   779
    (good for testing)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   780
  * `clean` - Remove all files generated by make, but not those generated by
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   781
    configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   782
  * `dist-clean` - Remove all files, including configuration
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   783
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   784
Run `make help` to get an up-to-date list of important make targets and make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   785
control variables.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   786
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   787
It is possible to build just a single module, a single phase, or a single phase
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   788
of a single module, by creating make targets according to these followin
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   789
patterns. A phase can be either of `gensrc`, `gendata`, `copy`, `java`,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   790
`launchers`, `libs` or `rmic`. See [Using Fine-Grained Make Targets](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   791
#using-fine-grained-make-targets) for more details about this functionality.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   792
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   793
  * `<phase>` - Build the specified phase and everything it depends on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   794
  * `<module>` - Build the specified module and everything it depends on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   795
  * `<module>-<phase>` - Compile the specified phase for the specified module
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   796
    and everything it depends on
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   797
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   798
Similarly, it is possible to clean just a part of the build by creating make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   799
targets according to these patterns:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   800
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   801
  * `clean-<outputdir>` - Remove the subdir in the output dir with the name
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   802
  * `clean-<phase>` - Remove all build results related to a certain build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   803
    phase
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   804
  * `clean-<module>` - Remove all build results related to a certain module
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   805
  * `clean-<module>-<phase>` - Remove all build results related to a certain
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   806
    module and phase
44078
673240c54c2e 8176509: Use pandoc for converting build readme to html
ihse
parents: 41040
diff changeset
   807
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   808
### Make Control Variables
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   809
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   810
It is possible to control `make` behavior by overriding the value of `make`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   811
variables, either on the command line or in the environment.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   812
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   813
Normally, this is **not recommended**. If used improperly, it can lead to a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   814
broken build. Unless you're well versed in the build system, this is hard to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   815
use properly. Therefore, `make` will print a warning if this is detected.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   816
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   817
However, there are a few `make` variables, known as *control variables* that
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   818
are supposed to be overriden on the command line. These make up the "make time"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   819
configuration, as opposed to the "configure time" configuration.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   820
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   821
#### General Make Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   822
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   823
  * `JOBS` - Specify the number of jobs to build with. See [Build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   824
    Performance](#build-performance).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   825
  * `LOG` - Specify the logging level and functionality. See [Checking the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   826
    Build Log File](#checking-the-build-log-file)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   827
  * `CONF` and `CONF_NAME` - Selecting the configuration(s) to use. See [Using
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   828
    Multiple Configurations](#using-multiple-configurations)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   829
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   830
#### Test Make Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   831
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   832
These make control variables only make sense when running tests. Please see
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   833
[Testing OpenJDK](testing.html) for details.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   834
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   835
  * `TEST`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   836
  * `TEST_JOBS`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   837
  * `JTREG`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   838
  * `GTEST`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   839
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   840
#### Advanced Make Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   841
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   842
These advanced make control variables can be potentially unsafe. See [Hints and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   843
Suggestions for Advanced Users](#hints-and-suggestions-for-advanced-users) and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   844
[Understanding the Build System](#understanding-the-build-system) for details.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   845
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   846
  * `SPEC`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   847
  * `CONF_CHECK`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   848
  * `COMPARE_BUILD`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   849
  * `JDK_FILTER`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   850
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   851
## Running Tests
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   852
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   853
Most of the OpenJDK tests are using the [JTReg](http://openjdk.java.net/jtreg)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   854
test framework. Make sure that your configuration knows where to find your
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   855
installation of JTReg. If this is not picked up automatically, use the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   856
`--with-jtreg=<path to jtreg home>` option to point to the JTReg framework.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   857
Note that this option should point to the JTReg home, i.e. the top directory,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   858
containing `lib/jtreg.jar` etc.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   859
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   860
To execute the most basic tests (tier 1), use:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   861
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   862
make run-test-tier1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   863
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   864
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   865
For more details on how to run tests, please see the [Testing
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   866
OpenJDK](testing.html) document.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   867
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   868
## Cross-compiling
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   869
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   870
Cross-compiling means using one platform (the *build* platform) to generate
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   871
output that can ran on another platform (the *target* platform).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   872
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   873
The typical reason for cross-compiling is that the build is performed on a more
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   874
powerful desktop computer, but the resulting binaries will be able to run on a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   875
different, typically low-performing system. Most of the complications that
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   876
arise when building for embedded is due to this separation of *build* and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   877
*target* systems.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   878
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   879
This requires a more complex setup and build procedure. This section assumes
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   880
you are familiar with cross-compiling in general, and will only deal with the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   881
particularities of cross-compiling OpenJDK. If you are new to cross-compiling,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   882
please see the [external links at Wikipedia](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   883
https://en.wikipedia.org/wiki/Cross_compiler#External_links) for a good start
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   884
on reading materials.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   885
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   886
Cross-compiling OpenJDK requires you to be able to build both for the build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   887
platform and for the target platform. The reason for the former is that we need
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   888
to build and execute tools during the build process, both native tools and Java
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   889
tools.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   890
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   891
If all you want to do is to compile a 32-bit version, for the same OS, on a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   892
64-bit machine, consider using `--with-target-bits=32` instead of doing a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   893
full-blown cross-compilation. (While this surely is possible, it's a lot more
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   894
work and will take much longer to build.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   895
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   896
### Boot JDK and Build JDK
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   897
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   898
When cross-compiling, make sure you use a boot JDK that runs on the *build*
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   899
system, and not on the *target* system.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   900
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   901
To be able to build, we need a "Build JDK", which is a JDK built from the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   902
current sources (that is, the same as the end result of the entire build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   903
process), but able to run on the *build* system, and not the *target* system.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   904
(In contrast, the Boot JDK should be from an older release, e.g. JDK 8 when
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   905
building JDK 9.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   906
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   907
The build process will create a minimal Build JDK for you, as part of building.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   908
To speed up the build, you can use `--with-build-jdk` to `configure` to point
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   909
to a pre-built Build JDK. Please note that the build result is unpredictable,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   910
and can possibly break in subtle ways, if the Build JDK does not **exactly**
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   911
match the current sources.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   912
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   913
### Specifying the Target Platform
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   914
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   915
You *must* specify the target platform when cross-compiling. Doing so will also
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   916
automatically turn the build into a cross-compiling mode. The simplest way to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   917
do this is to use the `--openjdk-target` argument, e.g.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   918
`--openjdk-target=arm-linux-gnueabihf`. or `--openjdk-target=aarch64-oe-linux`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   919
This will automatically set the `--build`, `--host` and `--target` options for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   920
autoconf, which can otherwise be confusing. (In autoconf terminology, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   921
"target" is known as "host", and "target" is used for building a Canadian
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   922
cross-compiler.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   923
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   924
### Toolchain Considerations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   925
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   926
You will need two copies of your toolchain, one which generates output that can
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   927
run on the target system (the normal, or *target*, toolchain), and one that
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   928
generates output that can run on the build system (the *build* toolchain). Note
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   929
that cross-compiling is only supported for gcc at the time being. The gcc
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   930
standard is to prefix cross-compiling toolchains with the target denominator.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   931
If you follow this standard, `configure` is likely to pick up the toolchain
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   932
correctly.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   933
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   934
The *build* toolchain will be autodetected just the same way the normal
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   935
*build*/*target* toolchain will be autodetected when not cross-compiling. If
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   936
this is not what you want, or if the autodetection fails, you can specify a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   937
devkit containing the *build* toolchain using `--with-build-devkit` to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   938
`configure`, or by giving `BUILD_CC` and `BUILD_CXX` arguments.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   939
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   940
It is often helpful to locate the cross-compilation tools, headers and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   941
libraries in a separate directory, outside the normal path, and point out that
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   942
directory to `configure`. Do this by setting the sysroot (`--with-sysroot`) and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   943
appending the directory when searching for cross-compilations tools
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   944
(`--with-toolchain-path`). As a compact form, you can also use `--with-devkit`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   945
to point to a single directory, if it is correctly setup. (See `basics.m4` for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   946
details.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   947
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   948
If you are unsure what toolchain and versions to use, these have been proved
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   949
working at the time of writing:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   950
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   951
  * [aarch64](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   952
https://releases.linaro.org/archive/13.11/components/toolchain/binaries/gcc-linaro-aarch64-linux-gnu-4.8-2013.11_linux.tar.xz)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   953
  * [arm 32-bit hardware floating  point](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   954
https://launchpad.net/linaro-toolchain-unsupported/trunk/2012.09/+download/gcc-linaro-arm-linux-gnueabihf-raspbian-2012.09-20120921_linux.tar.bz2)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   955
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   956
### Native Libraries
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   957
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   958
You will need copies of external native libraries for the *target* system,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   959
present on the *build* machine while building.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   960
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   961
Take care not to replace the *build* system's version of these libraries by
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   962
mistake, since that can render the *build* machine unusable.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   963
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   964
Make sure that the libraries you point to (ALSA, X11, etc) are for the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   965
*target*, not the *build*, platform.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   966
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   967
#### ALSA
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   968
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   969
You will need alsa libraries suitable for your *target* system. For most cases,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   970
using Debian's pre-built libraries work fine.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   971
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   972
Note that alsa is needed even if you only want to build a headless JDK.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   973
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   974
  * Go to [Debian Package Search](https://www.debian.org/distrib/packages) and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   975
    search for the `libasound2` and `libasound2-dev` packages for your *target*
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   976
    system. Download them to /tmp.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   977
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   978
  * Install the libraries into the cross-compilation toolchain. For instance:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   979
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   980
cd /tools/gcc-linaro-arm-linux-gnueabihf-raspbian-2012.09-20120921_linux/arm-linux-gnueabihf/libc
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   981
dpkg-deb -x /tmp/libasound2_1.0.25-4_armhf.deb .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   982
dpkg-deb -x /tmp/libasound2-dev_1.0.25-4_armhf.deb .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   983
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   984
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   985
  * If alsa is not properly detected by `configure`, you can point it out by
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   986
    `--with-alsa`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   987
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   988
#### X11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   989
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   990
You will need X11 libraries suitable for your *target* system. For most cases,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   991
using Debian's pre-built libraries work fine.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   992
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   993
Note that X11 is needed even if you only want to build a headless JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   994
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   995
  * Go to [Debian Package Search](https://www.debian.org/distrib/packages),
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   996
    search for the following packages for your *target* system, and download them
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   997
    to /tmp/target-x11:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   998
      * libxi
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   999
      * libxi-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1000
      * x11proto-core-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1001
      * x11proto-input-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1002
      * x11proto-kb-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1003
      * x11proto-render-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1004
      * x11proto-xext-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1005
      * libice-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1006
      * libxrender
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1007
      * libxrender-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1008
      * libsm-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1009
      * libxt-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1010
      * libx11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1011
      * libx11-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1012
      * libxtst
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1013
      * libxtst-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1014
      * libxext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1015
      * libxext-dev
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1016
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1017
  * Install the libraries into the cross-compilation toolchain. For instance:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1018
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1019
    cd /tools/gcc-linaro-arm-linux-gnueabihf-raspbian-2012.09-20120921_linux/arm-linux-gnueabihf/libc/usr
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1020
    mkdir X11R6
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1021
    cd X11R6
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1022
    for deb in /tmp/target-x11/*.deb ; do dpkg-deb -x $deb . ; done
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1023
    mv usr/* .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1024
    cd lib
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1025
    cp arm-linux-gnueabihf/* .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1026
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1027
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1028
    You can ignore the following messages. These libraries are not needed to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1029
    successfully complete a full JDK build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1030
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1031
    cp: cannot stat `arm-linux-gnueabihf/libICE.so': No such file or directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1032
    cp: cannot stat `arm-linux-gnueabihf/libSM.so': No such file or directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1033
    cp: cannot stat `arm-linux-gnueabihf/libXt.so': No such file or directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1034
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1035
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1036
  * If the X11 libraries are not properly detected by `configure`, you can
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1037
    point them out by `--with-x`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1038
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1039
### Building for ARM/aarch64
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1040
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1041
A common cross-compilation target is the ARM CPU. When building for ARM, it is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1042
useful to set the ABI profile. A number of pre-defined ABI profiles are
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1043
available using `--with-abi-profile`: arm-vfp-sflt, arm-vfp-hflt, arm-sflt,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1044
armv5-vfp-sflt, armv6-vfp-hflt. Note that soft-float ABIs are no longer
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1045
properly supported on OpenJDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1046
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1047
OpenJDK contains two different ports for the aarch64 platform, one is the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1048
original aarch64 port from the [AArch64 Port Project](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1049
http://openjdk.java.net/projects/aarch64-port) and one is a 64-bit version of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1050
the Oracle contributed ARM port. When targeting aarch64, by the default the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1051
original aarch64 port is used. To select the Oracle ARM 64 port, use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1052
`--with-cpu-port=arm64`. Also set the corresponding value (`aarch64` or
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1053
`arm64`) to --with-abi-profile, to ensure a consistent build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1054
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1055
### Verifying the Build
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1056
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1057
The build will end up in a directory named like
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1058
`build/linux-arm-normal-server-release`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1059
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1060
Inside this build output directory, the `images/jdk` and `images/jre` will
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1061
contain the newly built JDK and JRE, respectively, for your *target* system.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1062
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1063
Copy these folders to your *target* system. Then you can run e.g.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1064
`images/jdk/bin/java -version`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1065
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1066
## Build Performance
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1067
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1068
Building OpenJDK requires a lot of horsepower. Some of the build tools can be
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1069
adjusted to utilize more or less of resources such as parallel threads and
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1070
memory. The `configure` script analyzes your system and selects reasonable
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1071
values for such options based on your hardware. If you encounter resource
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1072
problems, such as out of memory conditions, you can modify the detected values
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1073
with:
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1074
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1075
  * `--with-num-cores` -- number of cores in the build system, e.g.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1076
    `--with-num-cores=8`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1077
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1078
  * `--with-memory-size` -- memory (in MB) available in the build system, e.g.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1079
    `--with-memory-size=1024`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1080
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1081
You can also specify directly the number of build jobs to use with
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1082
`--with-jobs=N` to `configure`, or `JOBS=N` to `make`. Do not use the `-j` flag
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1083
to `make`. In most cases it will be ignored by the makefiles, but it can cause
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1084
problems for some make targets.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1085
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1086
It might also be necessary to specify the JVM arguments passed to the Boot JDK,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1087
using e.g. `--with-boot-jdk-jvmargs="-Xmx8G"`. Doing so will override the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1088
default JVM arguments passed to the Boot JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1089
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1090
At the end of a successful execution of `configure`, you will get a performance
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1091
summary, indicating how well the build will perform. Here you will also get
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1092
performance hints. If you want to build fast, pay attention to those!
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1093
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1094
If you want to tweak build performance, run with `make LOG=info` to get a build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1095
time summary at the end of the build process.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1096
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1097
### Disk Speed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1098
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1099
If you are using network shares, e.g. via NFS, for your source code, make sure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1100
the build directory is situated on local disk (e.g. by `ln -s
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1101
/localdisk/jdk-build $JDK-SHARE/build`). The performance penalty is extremely
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1102
high for building on a network share; close to unusable.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1103
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1104
Also, make sure that your build tools (including Boot JDK and toolchain) is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1105
located on a local disk and not a network share.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1106
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1107
As has been stressed elsewhere, do use SSD for source code and build directory,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1108
as well as (if possible) the build tools.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1109
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1110
### Virus Checking
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1111
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1112
The use of virus checking software, especially on Windows, can *significantly*
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1113
slow down building of OpenJDK. If possible, turn off such software, or exclude
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1114
the directory containing the OpenJDK source code from on-the-fly checking.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1115
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1116
### Ccache
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1117
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1118
The OpenJDK build supports building with ccache when using gcc or clang. Using
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1119
ccache can radically speed up compilation of native code if you often rebuild
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1120
the same sources. Your milage may vary however, so we recommend evaluating it
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1121
for yourself. To enable it, make sure it's on the path and configure with
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1122
`--enable-ccache`.
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1123
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1124
### Precompiled Headers
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1125
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1126
By default, the Hotspot build uses preccompiled headers (PCH) on the toolchains
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1127
were it is properly supported (clang, gcc, and Visual Studio). Normally, this
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1128
speeds up the build process, but in some circumstances, it can actually slow
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1129
things down.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1130
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1131
You can experiment by disabling precompiled headers using
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1132
`--disable-precompiled-headers`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1133
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1134
### Icecc / icecream
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1135
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1136
[icecc/icecream](http://github.com/icecc/icecream) is a simple way to setup a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1137
distributed compiler network. If you have multiple machines available for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1138
building OpenJDK, you can drastically cut individual build times by utilizing
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1139
it.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1140
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1141
To use, setup an icecc network, and install icecc on the build machine. Then
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1142
run `configure` using `--enable-icecc`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1143
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1144
### Using sjavac
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1145
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1146
To speed up Java compilation, especially incremental compilations, you can try
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1147
the experimental sjavac compiler by using `--enable-sjavac`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1148
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1149
### Building the Right Target
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1150
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1151
Selecting the proper target to build can have dramatic impact on build time.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1152
For normal usage, `jdk` or the default target is just fine. You only need to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1153
build `images` for shipping, or if your tests require it.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1154
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1155
See also [Using Fine-Grained Make Targets](#using-fine-grained-make-targets) on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1156
how to build an even smaller subset of the product.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1157
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1158
## Troubleshooting
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1159
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1160
If your build fails, it can sometimes be difficult to pinpoint the problem or
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1161
find a proper solution.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1162
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1163
### Locating the Source of the Error
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1164
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1165
When a build fails, it can be hard to pinpoint the actual cause of the error.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1166
In a typical build process, different parts of the product build in parallel,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1167
with the output interlaced.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1168
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1169
#### Build Failure Summary
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1170
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1171
To help you, the build system will print a failure summary at the end. It looks
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1172
like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1173
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1174
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1175
ERROR: Build failed for target 'hotspot' in configuration 'linux-x64' (exit code 2)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1176
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1177
=== Output from failing command(s) repeated here ===
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1178
* For target hotspot_variant-server_libjvm_objs_psMemoryPool.o:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1179
/localhome/hg/jdk9-sandbox/hotspot/src/share/vm/services/psMemoryPool.cpp:1:1: error: 'failhere' does not name a type
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1180
   ... (rest of output omitted)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1181
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1182
* All command lines available in /localhome/hg/jdk9-sandbox/build/linux-x64/make-support/failure-logs.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1183
=== End of repeated output ===
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1184
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1185
=== Make failed targets repeated here ===
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1186
lib/CompileJvm.gmk:207: recipe for target '/localhome/hg/jdk9-sandbox/build/linux-x64/hotspot/variant-server/libjvm/objs/psMemoryPool.o' failed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1187
make/Main.gmk:263: recipe for target 'hotspot-server-libs' failed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1188
=== End of repeated output ===
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1189
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1190
Hint: Try searching the build log for the name of the first failed target.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1191
Hint: If caused by a warning, try configure --disable-warnings-as-errors.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1192
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1193
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1194
Let's break it down! First, the selected configuration, and the top-level
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1195
target you entered on the command line that caused the failure is printed.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1196
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1197
Then, between the `Output from failing command(s) repeated here` and `End of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1198
repeated output` the first lines of output (stdout and stderr) from the actual
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1199
failing command is repeated. In most cases, this is the error message that
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1200
caused the build to fail. If multiple commands were failing (this can happen in
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1201
a parallel build), output from all failed commands will be printed here.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1202
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1203
The path to the `failure-logs` directory is printed. In this file you will find
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1204
a `<target>.log` file that contains the output from this command in its
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1205
entirety, and also a `<target>.cmd`, which contain the complete command line
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1206
used for running this command. You can re-run the failing command by executing
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1207
`. <path to failure-logs>/<target>.cmd` in your shell.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1208
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1209
Another way to trace the failure is to follow the chain of make targets, from
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1210
top-level targets to individual file targets. Between `Make failed targets
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1211
repeated here` and `End of repeated output` the output from make showing this
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1212
chain is repeated. The first failed recipe will typically contain the full path
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1213
to the file in question that failed to compile. Following lines will show a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1214
trace of make targets why we ended up trying to compile that file.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1215
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1216
Finally, some hints are given on how to locate the error in the complete log.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1217
In this example, we would try searching the log file for "`psMemoryPool.o`".
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1218
Another way to quickly locate make errors in the log is to search for "`]
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1219
Error`" or "`***`".
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1220
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1221
Note that the build failure summary will only help you if the issue was a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1222
compilation failure or similar. If the problem is more esoteric, or is due to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1223
errors in the build machinery, you will likely get empty output logs, and `No
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1224
indication of failed target found` instead of the make target chain.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1225
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1226
#### Checking the Build Log File
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1227
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1228
The output (stdout and stderr) from the latest build is always stored in
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1229
`$BUILD/build.log`. The previous build log is stored as `build.log.old`. This
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1230
means that it is not necessary to redirect the build output yourself if you
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1231
want to process it.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1232
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1233
You can increase the verbosity of the log file, by the `LOG` control variable
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1234
to `make`. If you want to see the command lines used in compilations, use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1235
`LOG=cmdlines`. To increase the general verbosity, use `LOG=info`, `LOG=debug`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1236
or `LOG=trace`. Both of these can be combined with `cmdlines`, e.g.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1237
`LOG=info,cmdlines`. The `debug` log level will show most shell commands
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1238
executed by make, and `trace` will show all. Beware that both these log levels
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1239
will produce a massive build log!
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1240
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1241
### Fixing Unexpected Build Failures
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1242
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1243
Most of the time, the build will fail due to incorrect changes in the source
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1244
code.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1245
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1246
Sometimes the build can fail with no apparent changes that have caused the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1247
failure. If this is the first time you are building OpenJDK on this particular
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1248
computer, and the build fails, the problem is likely with your build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1249
environment. But even if you have previously built OpenJDK with success, and it
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1250
now fails, your build environment might have changed (perhaps due to OS
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1251
upgrades or similar). But most likely, such failures are due to problems with
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1252
the incremental rebuild.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1253
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1254
#### Problems with the Build Environment
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1255
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1256
Make sure your configuration is correct. Re-run `configure`, and look for any
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1257
warnings. Warnings that appear in the middle of the `configure` output is also
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1258
repeated at the end, after the summary. The entire log is stored in
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1259
`$BUILD/configure.log`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1260
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1261
Verify that the summary at the end looks correct. Are you indeed using the Boot
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1262
JDK and native toolchain that you expect?
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1263
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1264
By default, OpenJDK has a strict approach where warnings from the compiler is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1265
considered errors which fail the build. For very new or very old compiler
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1266
versions, this can trigger new classes of warnings, which thus fails the build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1267
Run `configure` with `--disable-warnings-as-errors` to turn of this behavior.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1268
(The warnings will still show, but not make the build fail.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1269
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1270
#### Problems with Incremental Rebuilds
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1271
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1272
Incremental rebuilds mean that when you modify part of the product, only the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1273
affected parts get rebuilt. While this works great in most cases, and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1274
significantly speed up the development process, from time to time complex
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1275
interdependencies will result in an incorrect build result. This is the most
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1276
common cause for unexpected build problems, together with inconsistencies
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1277
between the different Mercurial repositories in the forest.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1278
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1279
Here are a suggested list of things to try if you are having unexpected build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1280
problems. Each step requires more time than the one before, so try them in
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1281
order. Most issues will be solved at step 1 or 2.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1282
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1283
 1. Make sure your forest is up-to-date
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1284
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1285
    Run `bash get_source.sh` to make sure you have the latest version of all
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1286
    repositories.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1287
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1288
 2. Clean build results
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1289
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1290
    The simplest way to fix incremental rebuild issues is to run `make clean`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1291
    This will remove all build results, but not the configuration or any build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1292
    system support artifacts. In most cases, this will solve build errors
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1293
    resulting from incremental build mismatches.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1294
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1295
 3. Completely clean the build directory.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1296
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1297
    If this does not work, the next step is to run `make dist-clean`, or
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1298
    removing the build output directory (`$BUILD`). This will clean all
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1299
    generated output, including your configuration. You will need to re-run
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1300
    `configure` after this step. A good idea is to run `make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1301
    print-configuration` before running `make dist-clean`, as this will print
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1302
    your current `configure` command line. Here's a way to do this:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1303
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1304
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1305
    make print-configuration > current-configuration
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1306
    make dist-clean
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1307
    bash configure $(cat current-configuration)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1308
    make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1309
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1310
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1311
 4. Re-clone the Mercurial forest
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1312
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1313
    Sometimes the Mercurial repositories themselves gets in a state that causes
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1314
    the product to be un-buildable. In such a case, the simplest solution is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1315
    often the "sledgehammer approach": delete the entire forest, and re-clone
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1316
    it. If you have local changes, save them first to a different location
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1317
    using `hg export`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1318
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1319
### Specific Build Issues
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1320
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1321
#### Clock Skew
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1322
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1323
If you get an error message like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1324
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1325
File 'xxx' has modification time in the future.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1326
Clock skew detected. Your build may be incomplete.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1327
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1328
then the clock on your build machine is out of sync with the timestamps on the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1329
source files. Other errors, apparently unrelated but in fact caused by the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1330
clock skew, can occur along with the clock skew warnings. These secondary
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1331
errors may tend to obscure the fact that the true root cause of the problem is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1332
an out-of-sync clock.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1333
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1334
If you see these warnings, reset the clock on the build machine, run `make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1335
clean` and restart the build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1336
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1337
#### Out of Memory Errors
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1338
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1339
On Solaris, you might get an error message like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1340
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1341
Trouble writing out table to disk
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1342
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1343
To solve this, increase the amount of swap space on your build machine.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1344
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1345
On Windows, you might get error messages like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1346
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1347
fatal error - couldn't allocate heap
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1348
cannot create ... Permission denied
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1349
spawn failed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1350
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1351
This can be a sign of a Cygwin problem. See the information about solving
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1352
problems in the [Cygwin](#cygwin) section. Rebooting the computer might help
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1353
temporarily.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1354
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1355
### Getting Help
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1356
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1357
If none of the suggestions in this document helps you, or if you find what you
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1358
believe is a bug in the build system, please contact the Build Group by sending
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1359
a mail to [build-dev@openjdk.java.net](mailto:build-dev@openjdk.java.net).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1360
Please include the relevant parts of the configure and/or build log.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1361
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1362
If you need general help or advice about developing for OpenJDK, you can also
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1363
contact the Adoption Group. See the section on [Contributing to OpenJDK](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1364
#contributing-to-openjdk) for more information.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1365
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1366
## Hints and Suggestions for Advanced Users
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1367
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1368
### Setting Up a Forest for Pushing Changes (defpath)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1369
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1370
To help you prepare a proper push path for a Mercurial repository, there exists
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1371
a useful tool known as [defpath](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1372
http://openjdk.java.net/projects/code-tools/defpath). It will help you setup a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1373
proper push path for pushing changes to OpenJDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1374
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1375
Install the extension by cloning
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1376
`http://hg.openjdk.java.net/code-tools/defpath` and updating your `.hgrc` file.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1377
Here's one way to do this:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1378
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1379
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1380
cd ~
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1381
mkdir hg-ext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1382
cd hg-ext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1383
hg clone http://hg.openjdk.java.net/code-tools/defpath
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1384
cat << EOT >> ~/.hgrc
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1385
[extensions]
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1386
defpath=~/hg-ext/defpath/defpath.py
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1387
EOT
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1388
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1389
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1390
You can now setup a proper push path using:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1391
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1392
hg defpath -d -u <your OpenJDK username>
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1393
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1394
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1395
If you also have the `trees` extension installed in Mercurial, you will
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1396
automatically get a `tdefpath` command, which is even more useful. By running
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1397
`hg tdefpath -du <username>` in the top repository of your forest, all repos
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1398
will get setup automatically. This is the recommended usage.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1399
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1400
### Bash Completion
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1401
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1402
The `configure` and `make` commands tries to play nice with bash command-line
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1403
completion (using `<tab>` or `<tab><tab>`). To use this functionality, make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1404
sure you enable completion in your `~/.bashrc` (see instructions for bash in
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1405
your operating system).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1406
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1407
Make completion will work out of the box, and will complete valid make targets.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1408
For instance, typing `make jdk-i<tab>` will complete to `make jdk-image`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1409
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1410
The `configure` script can get completion for options, but for this to work you
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1411
need to help `bash` on the way. The standard way of running the script, `bash
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1412
configure`, will not be understood by bash completion. You need `configure` to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1413
be the command to run. One way to achieve this is to add a simple helper script
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1414
to your path:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1415
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1416
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1417
cat << EOT > /tmp/configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1418
#!/bin/bash
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1419
if [ \$(pwd) = \$(cd \$(dirname \$0); pwd) ] ; then
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1420
  echo >&2 "Abort: Trying to call configure helper recursively"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1421
  exit 1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1422
fi
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1423
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1424
bash \$PWD/configure "\$@"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1425
EOT
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1426
chmod +x /tmp/configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1427
sudo mv /tmp/configure /usr/local/bin
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1428
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1429
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1430
Now `configure --en<tab>-dt<tab>` will result in `configure --enable-dtrace`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1431
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1432
### Using Multiple Configurations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1433
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1434
You can have multiple configurations for a single source forest. When you
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1435
create a new configuration, run `configure --with-conf-name=<name>` to create a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1436
configuration with the name `<name>`. Alternatively, you can create a directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1437
under `build` and run `configure` from there, e.g. `mkdir build/<name> && cd
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1438
build/<name> && bash ../../configure`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1439
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1440
Then you can build that configuration using `make CONF_NAME=<name>` or `make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1441
CONF=<pattern>`, where `<pattern>` is a substring matching one or several
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1442
configurations, e.g. `CONF=debug`. The special empty pattern (`CONF=`) will
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1443
match *all* available configuration, so `make CONF= hotspot` will build the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1444
`hotspot` target for all configurations. Alternatively, you can execute `make`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1445
in the configuration directory, e.g. `cd build/<name> && make`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1446
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1447
### Handling Reconfigurations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1448
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1449
If you update the forest and part of the configure script has changed, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1450
build system will force you to re-run `configure`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1451
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1452
Most of the time, you will be fine by running `configure` again with the same
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1453
arguments as the last time, which can easily be performed by `make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1454
reconfigure`. To simplify this, you can use the `CONF_CHECK` make control
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1455
variable, either as `make CONF_CHECK=auto`, or by setting an environment
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1456
variable. For instance, if you add `export CONF_CHECK=auto` to your `.bashrc`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1457
file, `make` will always run `reconfigure` automatically whenever the configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1458
script has changed.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1459
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1460
You can also use `CONF_CHECK=ignore` to skip the check for a needed configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1461
update. This might speed up the build, but comes at the risk of an incorrect
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1462
build result. This is only recommended if you know what you're doing.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1463
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1464
From time to time, you will also need to modify the command line to `configure`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1465
due to changes. Use `make print-configure` to show the command line used for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1466
your current configuration.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1467
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1468
### Using Fine-Grained Make Targets
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1469
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1470
The default behavior for make is to create consistent and correct output, at
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1471
the expense of build speed, if necessary.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1472
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1473
If you are prepared to take some risk of an incorrect build, and know enough of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1474
the system to understand how things build and interact, you can speed up the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1475
build process considerably by instructing make to only build a portion of the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1476
product.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1477
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1478
#### Building Individual Modules
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1479
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1480
The safe way to use fine-grained make targets is to use the module specific
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1481
make targets. All source code in JDK 9 is organized so it belongs to a module,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1482
e.g. `java.base` or `jdk.jdwp.agent`. You can build only a specific module, by
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1483
giving it as make target: `make jdk.jdwp.agent`. If the specified module
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1484
depends on other modules (e.g. `java.base`), those modules will be built first.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1485
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1486
You can also specify a set of modules, just as you can always specify a set of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1487
make targets: `make jdk.crypto.cryptoki jdk.crypto.ec jdk.crypto.mscapi
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1488
jdk.crypto.ucrypto`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1489
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1490
#### Building Individual Module Phases
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1491
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1492
The build process for each module is divided into separate phases. Not all
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1493
modules need all phases. Which are needed depends on what kind of source code
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1494
and other artifact the module consists of. The phases are:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1495
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1496
  * `gensrc` (Generate source code to compile)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1497
  * `gendata` (Generate non-source code artifacts)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1498
  * `copy` (Copy resource artifacts)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1499
  * `java` (Compile Java code)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1500
  * `launchers` (Compile native executables)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1501
  * `libs` (Compile native libraries)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1502
  * `rmic` (Run the `rmic` tool)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1503
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1504
You can build only a single phase for a module by using the notation
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1505
`$MODULE-$PHASE`. For instance, to build the `gensrc` phase for `java.base`,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1506
use `make java.base-gensrc`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1507
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1508
Note that some phases may depend on others, e.g. `java` depends on `gensrc` (if
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1509
present). Make will build all needed prerequisites before building the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1510
requested phase.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1511
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1512
#### Skipping the Dependency Check
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1513
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1514
When using an iterative development style with frequent quick rebuilds, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1515
dependency check made by make can take up a significant portion of the time
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1516
spent on the rebuild. In such cases, it can be useful to bypass the dependency
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1517
check in make.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1518
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1519
> **Note that if used incorrectly, this can lead to a broken build!**
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1520
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1521
To achieve this, append `-only` to the build target. For instance, `make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1522
jdk.jdwp.agent-java-only` will *only* build the `java` phase of the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1523
`jdk.jdwp.agent` module. If the required dependencies are not present, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1524
build can fail. On the other hand, the execution time measures in milliseconds.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1525
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1526
A useful pattern is to build the first time normally (e.g. `make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1527
jdk.jdwp.agent`) and then on subsequent builds, use the `-only` make target.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1528
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1529
#### Rebuilding Part of java.base (JDK\_FILTER)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1530
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1531
If you are modifying files in `java.base`, which is the by far largest module
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1532
in OpenJDK, then you need to rebuild all those files whenever a single file has
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1533
changed. (This inefficiency will hopefully be addressed in JDK 10.)
44078
673240c54c2e 8176509: Use pandoc for converting build readme to html
ihse
parents: 41040
diff changeset
  1534
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1535
As a hack, you can use the make control variable `JDK_FILTER` to specify a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1536
pattern that will be used to limit the set of files being recompiled. For
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1537
instance, `make java.base JDK_FILTER=javax/crypto` (or, to combine methods,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1538
`make java.base-java-only JDK_FILTER=javax/crypto`) will limit the compilation
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1539
to files in the `javax.crypto` package.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1540
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1541
### Learn About Mercurial
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1542
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1543
To become an efficient OpenJDK developer, it is recommended that you invest in
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1544
learning Mercurial properly. Here are some links that can get you started:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1545
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1546
  * [Mercurial for git users](http://www.mercurial-scm.org/wiki/GitConcepts)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1547
  * [The official Mercurial tutorial](http://www.mercurial-scm.org/wiki/Tutorial)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1548
  * [hg init](http://hginit.com/)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1549
  * [Mercurial: The Definitive Guide](http://hgbook.red-bean.com/read/)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1550
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1551
## Understanding the Build System
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1552
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1553
This section will give you a more technical description on the details of the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1554
build system.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1555
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1556
### Configurations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1557
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1558
The build system expects to find one or more configuration. These are
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1559
technically defined by the `spec.gmk` in a subdirectory to the `build`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1560
subdirectory. The `spec.gmk` file is generated by `configure`, and contains in
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1561
principle the configuration (directly or by files included by `spec.gmk`).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1562
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1563
You can, in fact, select a configuration to build by pointing to the `spec.gmk`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1564
file with the `SPEC` make control variable, e.g. `make SPEC=$BUILD/spec.gmk`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1565
While this is not the recommended way to call `make` as a user, it is what is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1566
used under the hood by the build system.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1567
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1568
### Build Output Structure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1569
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1570
The build output for a configuration will end up in `build/<configuration
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1571
name>`, which we refer to as `$BUILD` in this document. The `$BUILD` directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1572
contains the following important directories:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1573
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1574
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1575
buildtools/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1576
configure-support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1577
hotspot/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1578
images/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1579
jdk/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1580
make-support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1581
support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1582
test-results/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1583
test-support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1584
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1585
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1586
This is what they are used for:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1587
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1588
  * `images`: This is the directory were the output of the `*-image` make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1589
    targets end up. For instance, `make jdk-image` ends up in `images/jdk`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1590
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1591
  * `jdk`: This is the "exploded image". After `make jdk`, you will be able to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1592
    launch the newly built JDK by running `$BUILD/jdk/bin/java`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1593
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1594
  * `test-results`: This directory contains the results from running tests.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1595
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1596
  * `support`: This is an area for intermediate files needed during the build,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1597
    e.g. generated source code, object files and class files. Some noteworthy
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1598
    directories in `support` is `gensrc`, which contains the generated source
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1599
    code, and the `modules_*` directories, which contains the files in a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1600
    per-module hierarchy that will later be collapsed into the `jdk` directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1601
    of the exploded image.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1602
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1603
  * `buildtools`: This is an area for tools compiled for the build platform
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1604
    that are used during the rest of the build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1605
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1606
  * `hotspot`: This is an area for intermediate files needed when building
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1607
    hotspot.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1608
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1609
  * `configure-support`, `make-support` and `test-support`: These directories
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1610
    contain files that are needed by the build system for `configure`, `make`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1611
    and for running tests.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1612
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1613
### Fixpath
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1614
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1615
Windows path typically look like `C:\User\foo`, while Unix paths look like
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1616
`/home/foo`. Tools with roots from Unix often experience issues related to this
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1617
mismatch when running on Windows.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1618
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1619
In the OpenJDK build, we always use Unix paths internally, and only just before
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1620
calling a tool that does not understand Unix paths do we convert them to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1621
Windows paths.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1622
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1623
This conversion is done by the `fixpath` tool, which is a small wrapper that
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1624
modifies unix-style paths to Windows-style paths in command lines. Fixpath is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1625
compiled automatically by `configure`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1626
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1627
### Native Debug Symbols
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1628
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1629
Native libraries and executables can have debug symbol (and other debug
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1630
information) associated with them. How this works is very much platform
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1631
dependent, but a common problem is that debug symbol information takes a lot of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1632
disk space, but is rarely needed by the end user.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1633
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1634
The OpenJDK supports different methods on how to handle debug symbols. The
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1635
method used is selected by `--with-native-debug-symbols`, and available methods
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1636
are `none`, `internal`, `external`, `zipped`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1637
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1638
  * `none` means that no debug symbols will be generated during the build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1639
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1640
  * `internal` means that debug symbols will be generated during the build, and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1641
    they will be stored in the generated binary.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1642
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1643
  * `external` means that debug symbols will be generated during the build, and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1644
    after the compilation, they will be moved into a separate `.debuginfo` file.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1645
    (This was previously known as FDS, Full Debug Symbols).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1646
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1647
  * `zipped` is like `external`, but the .debuginfo file will also be zipped
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1648
    into a `.diz` file.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1649
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1650
When building for distribution, `zipped` is a good solution. Binaries built
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1651
with `internal` is suitable for use by developers, since they facilitate
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1652
debugging, but should be stripped before distributed to end users.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1653
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1654
### Autoconf Details
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1655
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1656
The `configure` script is based on the autoconf framework, but in some details
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1657
deviate from a normal autoconf `configure` script.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1658
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1659
The `configure` script in the top level directory of OpenJDK is just a thin
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1660
wrapper that calls `make/autoconf/configure`. This in turn will run `autoconf`
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1661
to create the runnable (generated) configure script, as
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1662
`.build/generated-configure.sh`. Apart from being responsible for the
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1663
generation of the runnable script, the `configure` script also provides
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1664
functionality that is not easily expressed in the normal Autoconf framework. As
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1665
part of this functionality, the generated script is called.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1666
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1667
The build system will detect if the Autoconf source files have changed, and
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1668
will trigger a regeneration of the generated script if needed. You can also
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1669
manually request such an update by `bash configure autogen`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1670
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1671
In previous versions of the OpenJDK, the generated script was checked in at
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1672
`make/autoconf/generated-configure.sh`. This is no longer the case.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1673
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1674
### Developing the Build System Itself
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1675
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1676
This section contains a few remarks about how to develop for the build system
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1677
itself. It is not relevant if you are only making changes in the product source
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1678
code.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1679
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1680
While technically using `make`, the make source files of the OpenJDK does not
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1681
resemble most other Makefiles. Instead of listing specific targets and actions
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1682
(perhaps using patterns), the basic modus operandi is to call a high-level
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1683
function (or properly, macro) from the API in `make/common`. For instance, to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1684
compile all classes in the `jdk.internal.foo` package in the `jdk.foo` module,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1685
a call like this would be made:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1686
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1687
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1688
$(eval $(call SetupJavaCompilation, BUILD_FOO_CLASSES, \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1689
    SETUP := GENERATE_OLDBYTECODE, \
47219
fd36993f7bf5 8187542: Remove superfluous *_TOPDIR variables
ihse
parents: 47217
diff changeset
  1690
    SRC := $(TOPDIR)/src/jkd.foo/share/classes, \
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1691
    INCLUDES := jdk/internal/foo, \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1692
    BIN := $(SUPPORT_OUTPUTDIR)/foo_classes, \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1693
))
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1694
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1695
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1696
By encapsulating and expressing the high-level knowledge of *what* should be
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1697
done, rather than *how* it should be done (as is normal in Makefiles), we can
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1698
build a much more powerful and flexible build system.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1699
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1700
Correct dependency tracking is paramount. Sloppy dependency tracking will lead
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1701
to improper parallelization, or worse, race conditions.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1702
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1703
To test for/debug race conditions, try running `make JOBS=1` and `make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1704
JOBS=100` and see if it makes any difference. (It shouldn't).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1705
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1706
To compare the output of two different builds and see if, and how, they differ,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1707
run `$BUILD1/compare.sh -o $BUILD2`, where `$BUILD1` and `$BUILD2` are the two
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1708
builds you want to compare.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1709
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1710
To automatically build two consecutive versions and compare them, use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1711
`COMPARE_BUILD`. The value of `COMPARE_BUILD` is a set of variable=value
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1712
assignments, like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1713
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1714
make COMPARE_BUILD=CONF=--enable-new-hotspot-feature:MAKE=hotspot
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1715
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1716
See `make/InitSupport.gmk` for details on how to use `COMPARE_BUILD`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1717
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1718
To analyze build performance, run with `LOG=trace` and check `$BUILD/build-trace-time.log`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1719
Use `JOBS=1` to avoid parallelism.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1720
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1721
Please check that you adhere to the [Code Conventions for the Build System](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1722
http://openjdk.java.net/groups/build/doc/code-conventions.html) before
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1723
submitting patches.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1724
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1725
## Contributing to OpenJDK
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1726
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1727
So, now you've build your OpenJDK, and made your first patch, and want to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1728
contribute it back to the OpenJDK community.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1729
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1730
First of all: Thank you! We gladly welcome your contribution to the OpenJDK.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1731
However, please bear in mind that OpenJDK is a massive project, and we must ask
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1732
you to follow our rules and guidelines to be able to accept your contribution.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1733
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1734
The official place to start is the ['How to contribute' page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1735
http://openjdk.java.net/contribute/). There is also an official (but somewhat
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1736
outdated and skimpy on details) [Developer's Guide](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1737
http://openjdk.java.net/guide/).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1738
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1739
If this seems overwhelming to you, the Adoption Group is there to help you! A
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1740
good place to start is their ['New Contributor' page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1741
https://wiki.openjdk.java.net/display/Adoption/New+Contributor), or start
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1742
reading the comprehensive [Getting Started Kit](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1743
https://adoptopenjdk.gitbooks.io/adoptopenjdk-getting-started-kit/en/). The
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1744
Adoption Group will also happily answer any questions you have about
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1745
contributing. Contact them by [mail](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1746
http://mail.openjdk.java.net/mailman/listinfo/adoption-discuss) or [IRC](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1747
http://openjdk.java.net/irc/).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1748
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1749
---
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1750
# Override styles from the base CSS file that are not ideal for this document.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1751
header-includes:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1752
 - '<style type="text/css">pre, code, tt { color: #1d6ae5; }</style>'
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1753
---