doc/building.md
author chegar
Thu, 17 Oct 2019 20:54:25 +0100
branchdatagramsocketimpl-branch
changeset 58679 9c3209ff7550
parent 58678 9cf78a70fa4f
parent 58559 06bd38a9bc5a
permissions -rw-r--r--
datagramsocketimpl-branch: merge with default
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
     1
% Building the JDK
45763
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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
     5
If you are eager to try out building the JDK, these simple steps works most of
45763
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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
     7
on Windows) and cloned the top-level JDK repository that you want to build.
45763
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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
    37
The JDK is a complex software project. Building it requires a certain amount of
45763
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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
    41
If you just want to use the JDK and not build it yourself, this document is not
45763
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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
    44
JDK.
33030
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
52610
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
    51
can see a list of all available repositories. If you want to build an older version,
47217
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
53110
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
    78
  * On Windows, if using [Cygwin](#cygwin), extra care must be taken to make sure
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
    79
    the environment is consistent. It is recommended that you follow this
45763
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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
    83
        JDK clone by using the `mkdir` command in the Cygwin bash shell.
45763
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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
    88
      * Do not put the JDK clone in a path under your Cygwin home
45763
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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
    92
      * Clone the JDK repository using the Cygwin command line `hg` client
45763
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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   101
The JDK is a massive project, and require machines ranging from decent to
45763
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
51644
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   123
### Building on aarch64
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   124
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   125
At a minimum, a machine with 8 cores is advisable, as well as 8 GB of RAM.
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   126
(The more cores to use, the more memory you need.) At least 6 GB of free disk
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   127
space is required.
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   128
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   129
If you do not have access to sufficiently powerful hardware, it is also
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   130
possible to use [cross-compiling](#cross-compiling).
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   131
0df09dadd445 8182733: aarch64 build documentation misleading
ihse
parents: 51515
diff changeset
   132
### Building on 32-bit arm
45763
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
This is not recommended. Instead, see the section on [Cross-compiling](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   135
#cross-compiling).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   136
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   137
## Operating System Requirements
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   138
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   139
The mainline JDK project supports Linux, Solaris, macOS, AIX and Windows.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   140
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
   141
projects.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   142
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   143
In general, the JDK can be built on a wide range of versions of these operating
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   144
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
   145
more likely you are to run into problems.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   146
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   147
This table lists the OS versions used by Oracle when building the JDK. Such
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   148
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
   149
time of writing.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   150
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   151
 Operating system   Vendor/version used
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   152
 -----------------  -------------------------------------------------------
54581
5c456dd47ff1 8222735: Update doc/building.md with current Oracle build platforms and compilers
erikj
parents: 54001
diff changeset
   153
 Linux              Oracle Enterprise Linux 6.4 / 7.6
5c456dd47ff1 8222735: Update doc/building.md with current Oracle build platforms and compilers
erikj
parents: 54001
diff changeset
   154
 Solaris            Solaris 11.3 SRU 20
5c456dd47ff1 8222735: Update doc/building.md with current Oracle build platforms and compilers
erikj
parents: 54001
diff changeset
   155
 macOS              Mac OS X 10.13 (High Sierra)
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   156
 Windows            Windows Server 2012 R2
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   157
54581
5c456dd47ff1 8222735: Update doc/building.md with current Oracle build platforms and compilers
erikj
parents: 54001
diff changeset
   158
The double version numbers for Linux and Solaris are due to the hybrid model
5c456dd47ff1 8222735: Update doc/building.md with current Oracle build platforms and compilers
erikj
parents: 54001
diff changeset
   159
used at Oracle, where header files and external libraries from an older version
5c456dd47ff1 8222735: Update doc/building.md with current Oracle build platforms and compilers
erikj
parents: 54001
diff changeset
   160
are used when building on a more modern version of the OS.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   161
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   162
The Build Group has a wiki page with [Supported Build Platforms](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   163
https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms). From
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   164
time to time, this is updated by contributors to list successes or failures of
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   165
building on different platforms.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   166
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   167
### Windows
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   168
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   169
Windows XP is not a supported platform, but all newer Windows should be able to
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   170
build the JDK.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   171
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   172
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
   173
[Special Considerations](#special-considerations).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   174
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   175
Windows is the only non-POSIX OS supported by the JDK, and as such, requires
50586
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
   176
some extra care. A POSIX support layer is required to build on Windows.
53110
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   177
Currently, the only supported such layers are Cygwin and Windows Subsystem for
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   178
Linux (WSL). (Msys is no longer supported due to a too old bash; msys2 would
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   179
likely be possible to support in a future version but that would require effort
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   180
to implement.)
45763
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
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
   183
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
   184
rule also applies to input to the build system, e.g. in arguments to
49234
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   185
`configure`. So, use `--with-msvcr-dll=/cygdrive/c/msvcr100.dll` rather than
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   186
`--with-msvcr-dll=c:\msvcr100.dll`. For details on this conversion, see the section
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   187
on [Fixpath](#fixpath).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   188
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   189
#### Cygwin
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   190
53110
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   191
A functioning [Cygwin](http://www.cygwin.com/) environment is required for
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   192
building the JDK on Windows. If you have a 64-bit OS, we strongly recommend
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   193
using the 64-bit version of Cygwin.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   194
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   195
**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
   196
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
   197
that whenever you add or update a package in Cygwin, you might (inadvertently)
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   198
update tools that are used by the JDK build process, and that can cause
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   199
unexpected build problems.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   200
53110
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   201
The JDK requires GNU Make 4.0 or greater in Cygwin. This is usually not a
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   202
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
   203
4.0.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   204
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   205
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
   206
installed:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   207
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   208
  * `autoconf`
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   209
  * `make`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   210
  * `zip`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   211
  * `unzip`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   212
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   213
Often, you can install these packages using the following command line:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   214
```
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   215
<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
   216
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   217
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   218
Unfortunately, Cygwin can be unreliable in certain circumstances. If you
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   219
experience build tool crashes or strange issues when building on Windows,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   220
please check the Cygwin FAQ on the ["BLODA" list](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   221
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
   222
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
   223
53110
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   224
#### Windows Subsystem for Linux (WSL)
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   225
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   226
Windows 10 1809 or newer is supported due to a dependency on the wslpath utility
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   227
and support for environment variable sharing through WSLENV. Version 1803 can
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   228
work but intermittent build failures have been observed.
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   229
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   230
It's possible to build both Windows and Linux binaries from WSL. To build
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   231
Windows binaries, you must use a Windows boot JDK (located in a
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   232
Windows-accessible directory). To build Linux binaries, you must use a Linux
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   233
boot JDK. The default behavior is to build for Windows. To build for Linux, pass
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   234
`--build=x86_64-unknown-linux-gnu --host=x86_64-unknown-linux-gnu` to
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   235
`configure`.
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   236
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   237
If building Windows binaries, the source code must be located in a Windows-
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   238
accessible directory. This is because Windows executables (such as Visual Studio
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   239
and the boot JDK) must be able to access the source code. Also, the drive where
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   240
the source is stored must be mounted as case-insensitive by changing either
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   241
/etc/fstab or /etc/wsl.conf in WSL. Individual directories may be corrected
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   242
using the fsutil tool in case the source was cloned before changing the mount
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   243
options.
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   244
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   245
Note that while it's possible to build on WSL, testing is still not fully
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   246
supported.
50677f43ac3d 8215445: Enable building for Windows in WSL
erikj
parents: 52941
diff changeset
   247
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   248
### Solaris
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   249
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   250
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
   251
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
   252
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
   253
properly.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   254
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   255
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
   256
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
   257
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
   258
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
   259
symbols.
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
### macOS
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
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
   264
these updates with required updates of Xcode. Unfortunately, this makes it
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   265
difficult for a project such as the JDK to keep pace with a continuously updated
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   266
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
   267
strategies to deal with this.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   268
51237
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   269
It is recommended that you use at least Mac OS X 10.13 (High Sierra). At the time
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   270
of writing, the JDK has been successfully compiled on macOS 10.12 (Sierra).
45763
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
The standard macOS environment contains the basic tooling needed to build, but
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   273
for external libraries a package manager is recommended. The JDK uses
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   274
[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
   275
manager you want (or none).
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
### Linux
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   278
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   279
It is often not much problem to build the JDK on Linux. The only general advice
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   280
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
   281
by your distribution.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   282
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   283
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
   284
will most likely need to install developer packages.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   285
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   286
For apt-based distributions (Debian, Ubuntu, etc), try this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   287
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   288
sudo apt-get install build-essential
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   289
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   290
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   291
For rpm-based distributions (Fedora, Red Hat, etc), try this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   292
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   293
sudo yum groupinstall "Development Tools"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   294
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   295
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   296
### AIX
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   297
54001
b4e59fc5edd1 8220164: Fix build instructions for AIX
simonis
parents: 53110
diff changeset
   298
Please consult the AIX section of the [Supported Build Platforms](
b4e59fc5edd1 8220164: Fix build instructions for AIX
simonis
parents: 53110
diff changeset
   299
https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms) OpenJDK
b4e59fc5edd1 8220164: Fix build instructions for AIX
simonis
parents: 53110
diff changeset
   300
Build Wiki page for details about which versions of AIX are supported.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   301
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   302
## Native Compiler (Toolchain) Requirements
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   303
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   304
Large portions of the JDK consists of native code, that needs to be compiled to
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   305
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
   306
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
   307
one-to-one correlation between target operating system and toolchain.
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
 Operating system   Supported toolchain
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
 Linux              gcc, clang
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   312
 macOS              Apple Xcode (using clang)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   313
 Solaris            Oracle Solaris Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   314
 AIX                IBM XL C/C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   315
 Windows            Microsoft Visual Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   316
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   317
Please see the individual sections on the toolchains for version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   318
recommendations. As a reference, these versions of the toolchains are used, at
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   319
the time of writing, by Oracle for the daily builds of the JDK. It should be
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   320
possible to compile the JDK with both older and newer versions, but the closer
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   321
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
   322
issues.
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
 Operating system   Toolchain version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   325
 ------------------ -------------------------------------------------------
58558
67daaa6c8d2b 8232133: Change to GCC 8.3 for building on Linux at Oracle
erikj
parents: 55447
diff changeset
   326
 Linux              gcc 8.3.0
54581
5c456dd47ff1 8222735: Update doc/building.md with current Oracle build platforms and compilers
erikj
parents: 54001
diff changeset
   327
 macOS              Apple Xcode 10.1 (using clang 10.0.0)
5c456dd47ff1 8222735: Update doc/building.md with current Oracle build platforms and compilers
erikj
parents: 54001
diff changeset
   328
 Solaris            Oracle Solaris Studio 12.6 (with compiler version 5.15)
58559
06bd38a9bc5a 8232134: Change to Visual Studio 2017 15.9.16 for building on Windows at Oracle
erikj
parents: 58558
diff changeset
   329
 Windows            Microsoft Visual Studio 2017 update 15.9.16
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   330
54999
98ed47cd114a 8224087: Compile C code for at least C99 Standard compliance
dholmes
parents: 54918
diff changeset
   331
All compilers are expected to be able to compile to the C99 language standard,
98ed47cd114a 8224087: Compile C code for at least C99 Standard compliance
dholmes
parents: 54918
diff changeset
   332
as some C99 features are used in the source code. Microsoft Visual Studio
98ed47cd114a 8224087: Compile C code for at least C99 Standard compliance
dholmes
parents: 54918
diff changeset
   333
doesn't fully support C99 so in practice shared code is limited to using C99
98ed47cd114a 8224087: Compile C code for at least C99 Standard compliance
dholmes
parents: 54918
diff changeset
   334
features that it does support.
98ed47cd114a 8224087: Compile C code for at least C99 Standard compliance
dholmes
parents: 54918
diff changeset
   335
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   336
### gcc
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   337
50586
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
   338
The minimum accepted version of gcc is 4.8. Older versions will generate a warning
45877
640f1904ebb8 8184338: switch minimum supported gcc version to 4.7
mbaesken
parents: 45763
diff changeset
   339
by `configure` and are unlikely to work.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   340
58558
67daaa6c8d2b 8232133: Change to GCC 8.3 for building on Linux at Oracle
erikj
parents: 55447
diff changeset
   341
The JDK is currently known to be able to compile with at least version 8.3 of
50586
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
   342
gcc.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   343
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   344
In general, any version between these two should be usable.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   345
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   346
### clang
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   347
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   348
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
   349
accepted by `configure`.
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
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
   352
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   353
### Apple Xcode
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   354
51237
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   355
The oldest supported version of Xcode is 8.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   356
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   357
You will need the Xcode command lines developers tools to be able to build
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   358
the JDK. (Actually, *only* the command lines tools are needed, not the IDE.)
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   359
The simplest way to install these is to run:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   360
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   361
xcode-select --install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   362
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   363
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   364
It is advisable to keep an older version of Xcode for building the JDK when
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   365
updating Xcode. This [blog page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   366
http://iosdevelopertips.com/xcode/install-multiple-versions-of-xcode.html) has
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   367
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
   368
of Xcode, use `xcode-select -s` before running `configure`, or use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   369
`--with-toolchain-path` to point to the version of Xcode to use, e.g.
51237
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   370
`configure --with-toolchain-path=/Applications/Xcode8.app/Contents/Developer/usr/bin`
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   371
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   372
If you have recently (inadvertently) updated your OS and/or Xcode version, and
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   373
the JDK can no longer be built, please see the section on [Problems with the
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   374
Build Environment](#problems-with-the-build-environment), and [Getting
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   375
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
   376
available for this update.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   377
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   378
### Oracle Solaris Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   379
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   380
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
   381
(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
   382
configure.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   383
34595
09596fe63e2d 8145391: Updated jprt.properties, devtools, jib and readme with SS12u4
erikj
parents: 33030
diff changeset
   384
The Solaris Studio installation should contain at least these packages:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   385
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   386
 Package                                            Version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   387
 -------------------------------------------------- -------------
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   388
 developer/solarisstudio-124/backend                12.4-1.0.6.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   389
 developer/solarisstudio-124/c++                    12.4-1.0.10.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   390
 developer/solarisstudio-124/cc                     12.4-1.0.4.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   391
 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
   392
 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
   393
 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
   394
 developer/solarisstudio-124/studio-common          12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   395
 developer/solarisstudio-124/studio-ja              12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   396
 developer/solarisstudio-124/studio-legal           12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   397
 developer/solarisstudio-124/studio-zhCN            12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   398
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   399
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
   400
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
   401
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   402
$ cc -V
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   403
cc: Sun C 5.13 SunOS_i386 2014/10/20
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   404
$ CC -V
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   405
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
   406
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   407
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   408
### Microsoft Visual Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   409
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   410
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
   411
be accepted by `configure`. The maximum accepted version of Visual Studio is
54635
14615b8ac24c 8221988: add possibility to build with Visual Studio 2019
avoitylov
parents: 54581
diff changeset
   412
2019. Versions older than 2017 are unlikely to continue working for long.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   413
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   414
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
   415
default pick the latest. You can request a specific version to be used by
51237
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   416
setting `--with-toolchain-version`, e.g. `--with-toolchain-version=2015`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   417
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   418
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
   419
invalid` when building using Visual Studio 2010, you have encountered
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   420
[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
   421
specific installation order. However, the solution suggested by the KB article
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   422
does not always resolve the problem. See [this stackoverflow discussion](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   423
https://stackoverflow.com/questions/10888391) for other suggestions.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   424
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   425
### IBM XL C/C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   426
54001
b4e59fc5edd1 8220164: Fix build instructions for AIX
simonis
parents: 53110
diff changeset
   427
Please consult the AIX section of the [Supported Build Platforms](
b4e59fc5edd1 8220164: Fix build instructions for AIX
simonis
parents: 53110
diff changeset
   428
https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms) OpenJDK
b4e59fc5edd1 8220164: Fix build instructions for AIX
simonis
parents: 53110
diff changeset
   429
Build Wiki page for details about which versions of XLC are supported.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   430
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
## Boot JDK Requirements
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   433
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   434
Paradoxically, building the JDK requires a pre-existing JDK. This is called the
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   435
"boot JDK". The boot JDK does not, however, have to be a JDK built directly from
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   436
the source code available in the OpenJDK Community.  If you are porting the JDK
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   437
to a new platform, chances are that there already exists another JDK for that
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   438
platform that is usable as boot JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   439
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   440
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
   441
should be a JDK of major version *N-1*, so for building JDK 9 a JDK 8 would be
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   442
suitable as boot JDK. However, the JDK should be able to "build itself", so an
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   443
up-to-date build of the current JDK source is an acceptable alternative. If
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   444
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
   445
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
   446
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   447
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
   448
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
   449
is available.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   450
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   451
If the boot JDK is not automatically detected, or the wrong JDK is picked, use
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   452
`--with-boot-jdk` to point to the JDK to use.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   453
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   454
### Getting JDK binaries
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   455
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   456
JDK binaries for Linux, Windows and macOS can be downloaded from
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   457
[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
   458
[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
   459
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
   460
experimental prebuilt binaries for various platforms.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   461
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   462
On Linux you can also get a JDK from the Linux distribution. On apt-based
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   463
distros (like Debian and Ubuntu), `sudo apt-get install openjdk-<VERSION>-jdk`
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   464
is typically enough to install a JDK \<VERSION\>. On rpm-based distros (like
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   465
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
   466
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   467
## External Library Requirements
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   468
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   469
Different platforms require different external libraries. In general, libraries
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   470
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
   471
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   472
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
   473
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
   474
external library: `--with-<LIB>=<path>` or `--with-<LIB>-include=<path to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   475
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
   476
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
   477
under this directory. In most cases, it works fine.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   478
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   479
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
   480
and the lib directory separately.
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
### FreeType
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   483
49234
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   484
FreeType2 from [The FreeType Project](http://www.freetype.org/) is not required
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   485
on any platform. The exception is on Unix-based platforms when configuring such
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   486
that the build artifacts will reference a system installed library,
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   487
rather than bundling the JDK’s own copy.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   488
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   489
  * To install on an apt-based Linux, try running `sudo apt-get install
49234
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   490
    libfreetype6-dev`.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   491
  * To install on an rpm-based Linux, try running `sudo yum install
49234
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   492
    freetype-devel`.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   493
  * To install on Solaris, try running `pkg install system/library/freetype-2`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   494
49234
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   495
Use `--with-freetype-include=<path>` and `--with-freetype-lib=<path>`
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   496
if `configure` does not automatically locate the platform FreeType files.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   497
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   498
### CUPS
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
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
   501
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
   502
your operating system.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   503
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   504
  * 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
   505
    libcups2-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   506
  * 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
   507
    cups-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   508
  * To install on Solaris, try running `pkg install print/cups`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   509
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   510
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
   511
files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   512
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   513
### X11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   514
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   515
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
   516
Linux and Solaris.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   517
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   518
  * To install on an apt-based Linux, try running `sudo apt-get install
52921
f83b21839314 8215129: Update build documentation with Xrandr
ihse
parents: 52734
diff changeset
   519
    libx11-dev libxext-dev libxrender-dev libxrandr-dev libxtst-dev libxt-dev`.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   520
  * To install on an rpm-based Linux, try running `sudo yum install
52921
f83b21839314 8215129: Update build documentation with Xrandr
ihse
parents: 52734
diff changeset
   521
    libXtst-devel libXt-devel libXrender-devel libXrandr-devel libXi-devel`.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   522
  * 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
   523
    x11/library/libice x11/library/libpthread-stubs x11/library/libsm
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   524
    x11/library/libx11 x11/library/libxau x11/library/libxcb
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   525
    x11/library/libxdmcp x11/library/libxevie x11/library/libxext
52921
f83b21839314 8215129: Update build documentation with Xrandr
ihse
parents: 52734
diff changeset
   526
    x11/library/libxrender x11/library/libxrandr x11/library/libxscrnsaver
f83b21839314 8215129: Update build documentation with Xrandr
ihse
parents: 52734
diff changeset
   527
    x11/library/libxtst x11/library/toolkit/libxt`.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   528
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   529
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
   530
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   531
### ALSA
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
ALSA, [Advanced Linux Sound Architecture](https://www.alsa-project.org/) is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   534
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
   535
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   536
  * 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
   537
    libasound2-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   538
  * 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
   539
    alsa-lib-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   540
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   541
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
   542
files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   543
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   544
### libffi
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   545
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   546
libffi, the [Portable Foreign Function Interface Library](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   547
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
   548
Hotspot.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   549
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   550
  * 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
   551
    libffi-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   552
  * 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
   553
    libffi-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   554
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   555
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
   556
files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   557
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   558
## Build Tools Requirements
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
### Autoconf
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   561
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   562
The JDK requires [Autoconf](http://www.gnu.org/software/autoconf) on all
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   563
platforms. At least version 2.69 is required.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   564
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   565
  * 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
   566
    autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   567
  * 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
   568
    autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   569
  * To install on macOS, try running `brew install autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   570
  * 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
   571
    -P autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   572
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   573
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
   574
specify it using the `AUTOCONF` environment variable, like this:
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   575
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   576
```
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   577
AUTOCONF=<path to autoconf> configure ...
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   578
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   579
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   580
### GNU Make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   581
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   582
The JDK requires [GNU Make](http://www.gnu.org/software/make). No other flavors
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   583
of make are supported.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   584
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   585
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
   586
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
   587
functionality to handle parallel building (supported by `--with-output-sync`)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   588
and speed and stability improvements.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   589
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   590
Note that `configure` locates and verifies a properly functioning version of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   591
`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
   592
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
   593
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
   594
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
   595
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
   596
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
   597
`make` in your path, this might cause issues.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   598
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   599
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
   600
configure variable, e.g. `configure MAKE=/opt/gnu/make`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   601
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   602
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
   603
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   604
### GNU Bash
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   605
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   606
The JDK requires [GNU Bash](http://www.gnu.org/software/bash). No other shells
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   607
are supported.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   608
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   609
At least version 3.2 of GNU Bash must be used.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   610
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   611
## Running Configure
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   612
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   613
To build the JDK, you need a "configuration", which consists of a directory
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   614
where to store the build output, coupled with information about the platform,
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   615
the specific build machine, and choices that affect how the JDK is built.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   616
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   617
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
   618
the `configure` script looks like this:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   619
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   620
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   621
bash configure [options]
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   622
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   623
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   624
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
   625
area for the build result. This directory typically looks like
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   626
`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
   627
specific configuration. (It can also be set directly, see [Using Multiple
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   628
Configurations](#using-multiple-configurations)). This directory is referred to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   629
as `$BUILD` in this documentation.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   630
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   631
`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
   632
necessary build components are. If you have all prerequisites for building
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   633
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
   634
automatically, it will exit and inform you about the problem.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   635
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   636
Some command line examples:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   637
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   638
  * 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
   639
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   640
    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
   641
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   642
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   643
  * Create a debug build with the `server` JVM and DTrace enabled:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   644
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   645
    bash configure --enable-debug --with-jvm-variants=server --enable-dtrace
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   646
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   647
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   648
### Common Configure Arguments
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   649
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   650
Here follows some of the most common and important `configure` argument.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   651
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   652
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
   653
run:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   654
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   655
bash configure --help
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   656
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   657
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   658
(Note that this help text also include general autoconf options, like
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   659
`--dvidir`, that is not relevant to the JDK. To list only JDK-specific
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   660
features, use `bash configure --help=short` instead.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   661
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   662
#### Configure Arguments for Tailoring the Build
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   663
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   664
  * `--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
   665
    for `--with-debug-level=fastdebug`)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   666
  * `--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
   667
    `fastdebug`, `slowdebug` or `optimized`. Default is `release`. `optimized`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   668
    is variant of `release` with additional Hotspot debug code.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   669
  * `--with-native-debug-symbols=<method>` - Specify if and how native debug
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   670
    symbols should be built. Available methods are `none`, `internal`,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   671
    `external`, `zipped`. Default behavior depends on platform. See [Native
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   672
    Debug Symbols](#native-debug-symbols) for more details.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   673
  * `--with-version-string=<string>` - Specify the version string this build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   674
    will be identified with.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   675
  * `--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
   676
    any of `pre`, `opt`, `build`, `major`, `minor`, `security` or `patch`. Use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   677
    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
   678
    from the default, or the value provided by `--with-version-string`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   679
  * `--with-jvm-variants=<variant>[,<variant>...]` - Build the specified variant
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   680
    (or variants) of Hotspot. Valid variants are: `server`, `client`,
47687
fb290fd1f9d4 8171853: Remove Shark compiler
rkennke
parents: 47219
diff changeset
   681
    `minimal`, `core`, `zero`, `custom`. Note that not all
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   682
    variants are possible to combine in a single build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   683
  * `--with-jvm-features=<feature>[,<feature>...]` - Use the specified JVM
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   684
    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
   685
    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
   686
    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
   687
    configure --help`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   688
  * `--with-target-bits=<bits>` - Create a target binary suitable for running
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   689
    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
   690
    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
   691
    *reduced* build.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   692
52734
d537553ed639 8214332: Add a flag for overriding default JNI library search path
dholmes
parents: 52665
diff changeset
   693
On Linux, BSD and AIX, it is possible to override where Java by default
d537553ed639 8214332: Add a flag for overriding default JNI library search path
dholmes
parents: 52665
diff changeset
   694
searches for runtime/JNI libraries. This can be useful in situations where
d537553ed639 8214332: Add a flag for overriding default JNI library search path
dholmes
parents: 52665
diff changeset
   695
there is a special shared directory for system JNI libraries. This setting
d537553ed639 8214332: Add a flag for overriding default JNI library search path
dholmes
parents: 52665
diff changeset
   696
can in turn be overriden at runtime by setting the `java.library.path` property.
d537553ed639 8214332: Add a flag for overriding default JNI library search path
dholmes
parents: 52665
diff changeset
   697
d537553ed639 8214332: Add a flag for overriding default JNI library search path
dholmes
parents: 52665
diff changeset
   698
  * `--with-jni-libpath=<path>` - Use the specified path as a default
d537553ed639 8214332: Add a flag for overriding default JNI library search path
dholmes
parents: 52665
diff changeset
   699
  when searching for runtime libraries.
d537553ed639 8214332: Add a flag for overriding default JNI library search path
dholmes
parents: 52665
diff changeset
   700
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   701
#### Configure Arguments for Native Compilation
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   702
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   703
  * `--with-devkit=<path>` - Use this devkit for compilers, tools and resources
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   704
  * `--with-sysroot=<path>` - Use this directory as sysroot
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   705
  * `--with-extra-path=<path>[;<path>]` - Prepend these directories to the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   706
    default path when searching for all kinds of binaries
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   707
  * `--with-toolchain-path=<path>[;<path>]` - Prepend these directories when
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   708
    searching for toolchain binaries (compilers etc)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   709
  * `--with-extra-cflags=<flags>` - Append these flags when compiling JDK C
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   710
    files
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   711
  * `--with-extra-cxxflags=<flags>` - Append these flags when compiling JDK C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   712
    files
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   713
  * `--with-extra-ldflags=<flags>` - Append these flags when linking JDK
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   714
    libraries
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   715
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   716
#### Configure Arguments for External Dependencies
44078
673240c54c2e 8176509: Use pandoc for converting build readme to html
ihse
parents: 41040
diff changeset
   717
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   718
  * `--with-boot-jdk=<path>` - Set the path to the [Boot JDK](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   719
    #boot-jdk-requirements)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   720
  * `--with-freetype=<path>` - Set the path to [FreeType](#freetype)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   721
  * `--with-cups=<path>` - Set the path to [CUPS](#cups)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   722
  * `--with-x=<path>` - Set the path to [X11](#x11)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   723
  * `--with-alsa=<path>` - Set the path to [ALSA](#alsa)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   724
  * `--with-libffi=<path>` - Set the path to [libffi](#libffi)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   725
  * `--with-jtreg=<path>` - Set the path to JTReg. See [Running Tests](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   726
    #running-tests)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   727
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   728
Certain third-party libraries used by the JDK (libjpeg, giflib, libpng, lcms
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   729
and zlib) are included in the JDK repository. The default behavior of the
54918
b88bcaa94c10 8223944: fix zlib related building docu and comments
mbaesken
parents: 54635
diff changeset
   730
JDK build is to use the included ("bundled") versions of libjpeg, giflib,
b88bcaa94c10 8223944: fix zlib related building docu and comments
mbaesken
parents: 54635
diff changeset
   731
libpng and lcms.
b88bcaa94c10 8223944: fix zlib related building docu and comments
mbaesken
parents: 54635
diff changeset
   732
For zlib, the system lib (if present) is used except on Windows and AIX.
b88bcaa94c10 8223944: fix zlib related building docu and comments
mbaesken
parents: 54635
diff changeset
   733
However the bundled libraries may be replaced by an external version.
b88bcaa94c10 8223944: fix zlib related building docu and comments
mbaesken
parents: 54635
diff changeset
   734
To do so, specify `system` as the `<source>` option in these arguments.
b88bcaa94c10 8223944: fix zlib related building docu and comments
mbaesken
parents: 54635
diff changeset
   735
(The default is `bundled`).
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
  * `--with-libjpeg=<source>` - Use the specified source for libjpeg
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   738
  * `--with-giflib=<source>` - Use the specified source for giflib
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   739
  * `--with-libpng=<source>` - Use the specified source for libpng
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   740
  * `--with-lcms=<source>` - Use the specified source for lcms
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   741
  * `--with-zlib=<source>` - Use the specified source for zlib
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   742
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   743
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
   744
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
   745
static library is not found.
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
  * `--with-stdc++lib=<method>` - Use the specified method (`static`, `dynamic`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   748
    or `default`) for linking the C++ runtime.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   749
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   750
### Configure Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   751
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   752
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
   753
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
   754
environment.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   755
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   756
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
   757
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
   758
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
   759
detected.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   760
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   761
However, there are a few `configure` variables, known as *control variables*
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   762
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
   763
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
   764
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
   765
trying to autodetect the tool. For instance, `bash configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   766
MAKE=/opt/gnumake4.0/bin/make`.
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
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
   769
instead of setting `JTREGEXE`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   770
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   771
Also note that, despite what autoconf claims, setting `CFLAGS` will not
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   772
accomplish anything. Instead use `--with-extra-cflags` (and similar for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   773
`cxxflags` and `ldflags`).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   774
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   775
## Running Make
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   776
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   777
When you have a proper configuration, all you need to do to build the JDK is to
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   778
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
   779
correct version of make.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   780
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   781
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
   782
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
   783
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
   784
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
   785
incremental development fashion, when doing a normal make, you should only
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   786
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
   787
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
   788
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   789
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
   790
newly built JDK like this: `$BUILD/jdk/bin/java -version`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   791
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   792
### Common Make Targets
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   793
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   794
Apart from the default target, here are some common make targets:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   795
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   796
  * `hotspot` - Build all of hotspot (but only hotspot)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   797
  * `hotspot-<variant>` - Build just the specified jvm variant
50490
cbae0e359538 8200132: Remove jre images and bundles
erikj
parents: 50267
diff changeset
   798
  * `images` or `product-images` - Build the JDK image
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   799
  * `docs` or `docs-image` - Build the documentation image
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   800
  * `test-image` - Build the test image
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   801
  * `all` or `all-images` - Build all images (product, docs and test)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   802
  * `bootcycle-images` - Build images twice, second time with newly built JDK
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   803
    (good for testing)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   804
  * `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
   805
    configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   806
  * `dist-clean` - Remove all files, including configuration
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   807
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   808
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
   809
control variables.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   810
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   811
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
   812
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
   813
patterns. A phase can be either of `gensrc`, `gendata`, `copy`, `java`,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   814
`launchers`, `libs` or `rmic`. See [Using Fine-Grained Make Targets](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   815
#using-fine-grained-make-targets) for more details about this functionality.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   816
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   817
  * `<phase>` - Build the specified phase and everything it depends on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   818
  * `<module>` - Build the specified module and everything it depends on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   819
  * `<module>-<phase>` - Compile the specified phase for the specified module
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   820
    and everything it depends on
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   821
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   822
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
   823
targets according to these patterns:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   824
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   825
  * `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
   826
  * `clean-<phase>` - Remove all build results related to a certain build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   827
    phase
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   828
  * `clean-<module>` - Remove all build results related to a certain module
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   829
  * `clean-<module>-<phase>` - Remove all build results related to a certain
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   830
    module and phase
44078
673240c54c2e 8176509: Use pandoc for converting build readme to html
ihse
parents: 41040
diff changeset
   831
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   832
### Make Control Variables
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   833
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   834
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
   835
variables, either on the command line or in the environment.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   836
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   837
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
   838
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
   839
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
   840
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   841
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
   842
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
   843
configuration, as opposed to the "configure time" configuration.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   844
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   845
#### General Make Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   846
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   847
  * `JOBS` - Specify the number of jobs to build with. See [Build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   848
    Performance](#build-performance).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   849
  * `LOG` - Specify the logging level and functionality. See [Checking the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   850
    Build Log File](#checking-the-build-log-file)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   851
  * `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
   852
    Multiple Configurations](#using-multiple-configurations)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   853
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   854
#### Test Make Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   855
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   856
These make control variables only make sense when running tests. Please see
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   857
[Testing the JDK](testing.html) for details.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   858
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   859
  * `TEST`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   860
  * `TEST_JOBS`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   861
  * `JTREG`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   862
  * `GTEST`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   863
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   864
#### Advanced Make Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   865
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   866
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
   867
Suggestions for Advanced Users](#hints-and-suggestions-for-advanced-users) and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   868
[Understanding the Build System](#understanding-the-build-system) for details.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   869
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   870
  * `SPEC`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   871
  * `CONF_CHECK`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   872
  * `COMPARE_BUILD`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   873
  * `JDK_FILTER`
55447
95794e32352e 8226325: Support building of filtered spec bundles
dlsmith
parents: 54999
diff changeset
   874
  * `SPEC_FILTER`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   875
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   876
## Running Tests
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   877
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   878
Most of the JDK tests are using the [JTReg](http://openjdk.java.net/jtreg)
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   879
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
   880
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
   881
`--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
   882
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
   883
containing `lib/jtreg.jar` etc.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   884
50267
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49234
diff changeset
   885
The [Adoption Group](https://wiki.openjdk.java.net/display/Adoption) provides
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49234
diff changeset
   886
recent builds of jtreg [here](
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49234
diff changeset
   887
https://adopt-openjdk.ci.cloudbees.com/job/jtreg/lastSuccessfulBuild/artifact).
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49234
diff changeset
   888
Download the latest `.tar.gz` file, unpack it, and point `--with-jtreg` to the
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49234
diff changeset
   889
`jtreg` directory that you just unpacked.
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49234
diff changeset
   890
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   891
To execute the most basic tests (tier 1), use:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   892
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   893
make run-test-tier1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   894
```
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
For more details on how to run tests, please see the [Testing
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   897
the JDK](testing.html) document.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   898
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   899
## Cross-compiling
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   900
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   901
Cross-compiling means using one platform (the *build* platform) to generate
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   902
output that can ran on another platform (the *target* platform).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   903
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   904
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
   905
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
   906
different, typically low-performing system. Most of the complications that
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   907
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
   908
*target* systems.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   909
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   910
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
   911
you are familiar with cross-compiling in general, and will only deal with the
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   912
particularities of cross-compiling the JDK. If you are new to cross-compiling,
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   913
please see the [external links at Wikipedia](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   914
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
   915
on reading materials.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   916
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   917
Cross-compiling the JDK requires you to be able to build both for the build
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   918
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
   919
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
   920
tools.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   921
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   922
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
   923
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
   924
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
   925
work and will take much longer to build.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   926
52665
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   927
### Cross compiling the easy way with OpenJDK devkits
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   928
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   929
The OpenJDK build system provides out-of-the box support for creating and using
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   930
so called devkits. A `devkit` is basically a collection of a cross-compiling
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   931
toolchain and a sysroot environment which can easily be used together with the
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   932
`--with-devkit` configure option to cross compile the OpenJDK. On Linux/x86_64,
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   933
the following command:
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   934
```
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   935
bash configure --with-devkit=<devkit-path> --openjdk-target=ppc64-linux-gnu && make
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   936
```
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   937
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   938
will configure and build OpenJDK for Linux/ppc64 assuming that `<devkit-path>`
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   939
points to a Linux/x86_64 to Linux/ppc64 devkit.
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   940
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   941
Devkits can be created from the `make/devkit` directory by executing:
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   942
```
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   943
make [ TARGETS="<TARGET_TRIPLET>+" ] [ BASE_OS=<OS> ] [ BASE_OS_VERSION=<VER> ]
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   944
```
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   945
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   946
where `TARGETS` contains one or more `TARGET_TRIPLET`s of the form
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   947
described in [section 3.4 of the GNU Autobook](
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   948
https://sourceware.org/autobook/autobook/autobook_17.html). If no
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   949
targets are given, a native toolchain for the current platform will be
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   950
created. Currently, at least the following targets are known to work:
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   951
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   952
 Supported devkit targets
52941
a430555c3d4e 8215131: Pandoc 2.3/build documentation fixes
ihse
parents: 52921
diff changeset
   953
 -------------------------
52665
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   954
 x86_64-linux-gnu
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   955
 aarch64-linux-gnu
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   956
 arm-linux-gnueabihf
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   957
 ppc64-linux-gnu
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   958
 ppc64le-linux-gnu
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   959
 s390x-linux-gnu
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   960
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   961
`BASE_OS` must be one of "OEL6" for Oracle Enterprise Linux 6 or
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   962
"Fedora" (if not specified "OEL6" will be the default). If the base OS
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   963
is "Fedora" the corresponding Fedora release can be specified with the
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   964
help of the `BASE_OS_VERSION` option (with "27" as default version).
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   965
If the build is successful, the new devkits can be found in the
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   966
`build/devkit/result` subdirectory:
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   967
```
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   968
cd make/devkit
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   969
make TARGETS="ppc64le-linux-gnu aarch64-linux-gnu" BASE_OS=Fedora BASE_OS_VERSION=21
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   970
ls -1 ../../build/devkit/result/
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   971
x86_64-linux-gnu-to-aarch64-linux-gnu
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   972
x86_64-linux-gnu-to-ppc64le-linux-gnu
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   973
```
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   974
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   975
Notice that devkits are not only useful for targeting different build
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   976
platforms. Because they contain the full build dependencies for a
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   977
system (i.e. compiler and root file system), they can easily be used
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   978
to build well-known, reliable and reproducible build environments. You
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   979
can for example create and use a devkit with GCC 7.3 and a Fedora 12
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   980
sysroot environment (with glibc 2.11) on Ubuntu 14.04 (which doesn't
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   981
have GCC 7.3 by default) to produce OpenJDK binaries which will run on
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   982
all Linux systems with runtime libraries newer than the ones from
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   983
Fedora 12 (e.g. Ubuntu 16.04, SLES 11 or RHEL 6).
61dcd7cd48c3 8213698: Improve devkit creation and add support for linux/ppc64/ppc64le/s390x
simonis
parents: 52610
diff changeset
   984
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   985
### Boot JDK and Build JDK
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   986
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   987
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
   988
system, and not on the *target* system.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   989
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   990
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
   991
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
   992
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
   993
(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
   994
building JDK 9.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   995
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   996
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
   997
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
   998
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
   999
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
  1000
match the current sources.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1001
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1002
### Specifying the Target Platform
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1003
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1004
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
  1005
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
  1006
do this is to use the `--openjdk-target` argument, e.g.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1007
`--openjdk-target=arm-linux-gnueabihf`. or `--openjdk-target=aarch64-oe-linux`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1008
This will automatically set the `--build`, `--host` and `--target` options for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1009
autoconf, which can otherwise be confusing. (In autoconf terminology, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1010
"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
  1011
cross-compiler.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1012
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1013
### Toolchain Considerations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1014
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1015
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
  1016
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
  1017
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
  1018
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
  1019
standard is to prefix cross-compiling toolchains with the target denominator.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1020
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
  1021
correctly.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1022
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1023
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
  1024
*build*/*target* toolchain will be autodetected when not cross-compiling. If
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1025
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
  1026
devkit containing the *build* toolchain using `--with-build-devkit` to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1027
`configure`, or by giving `BUILD_CC` and `BUILD_CXX` arguments.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1028
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1029
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
  1030
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
  1031
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
  1032
appending the directory when searching for cross-compilations tools
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1033
(`--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
  1034
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
  1035
details.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1036
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1037
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
  1038
working at the time of writing:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1039
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1040
  * [aarch64](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1041
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
  1042
  * [arm 32-bit hardware floating  point](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1043
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
  1044
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1045
### Native Libraries
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1046
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1047
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
  1048
present on the *build* machine while building.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1049
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1050
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
  1051
mistake, since that can render the *build* machine unusable.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1052
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1053
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
  1054
*target*, not the *build*, platform.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1055
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1056
#### ALSA
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1057
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1058
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
  1059
using Debian's pre-built libraries work fine.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1060
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1061
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
  1062
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1063
  * 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
  1064
    search for the `libasound2` and `libasound2-dev` packages for your *target*
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1065
    system. Download them to /tmp.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1066
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1067
  * Install the libraries into the cross-compilation toolchain. For instance:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1068
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1069
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
  1070
dpkg-deb -x /tmp/libasound2_1.0.25-4_armhf.deb .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1071
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
  1072
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1073
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1074
  * 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
  1075
    `--with-alsa`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1076
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1077
#### X11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1078
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1079
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
  1080
using Debian's pre-built libraries work fine.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1081
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1082
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
  1083
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1084
  * Go to [Debian Package Search](https://www.debian.org/distrib/packages),
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1085
    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
  1086
    to /tmp/target-x11:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1087
      * libxi
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1088
      * libxi-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1089
      * x11proto-core-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1090
      * x11proto-input-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1091
      * x11proto-kb-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1092
      * x11proto-render-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1093
      * x11proto-xext-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1094
      * libice-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1095
      * libxrender
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1096
      * libxrender-dev
52921
f83b21839314 8215129: Update build documentation with Xrandr
ihse
parents: 52734
diff changeset
  1097
      * libxrandr-dev
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1098
      * libsm-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1099
      * libxt-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1100
      * libx11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1101
      * libx11-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1102
      * libxtst
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1103
      * libxtst-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1104
      * libxext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1105
      * libxext-dev
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1106
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1107
  * Install the libraries into the cross-compilation toolchain. For instance:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1108
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1109
    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
  1110
    mkdir X11R6
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1111
    cd X11R6
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1112
    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
  1113
    mv usr/* .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1114
    cd lib
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1115
    cp arm-linux-gnueabihf/* .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1116
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1117
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1118
    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
  1119
    successfully complete a full JDK build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1120
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1121
    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
  1122
    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
  1123
    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
  1124
    ```
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
  * 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
  1127
    point them out by `--with-x`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1128
51515
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1129
### Creating And Using Sysroots With qemu-deboostrap
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1130
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1131
Fortunately, you can create sysroots for foreign architectures with tools
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1132
provided by your OS. On Debian/Ubuntu systems, one could use `qemu-deboostrap` to
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1133
create the *target* system chroot, which would have the native libraries and headers
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1134
specific to that *target* system. After that, we can use the cross-compiler on the *build*
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1135
system, pointing into chroot to get the build dependencies right. This allows building
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1136
for foreign architectures with native compilation speed.
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1137
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1138
For example, cross-compiling to AArch64 from x86_64 could be done like this:
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1139
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1140
  * Install cross-compiler on the *build* system:
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1141
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1142
apt install g++-aarch64-linux-gnu gcc-aarch64-linux-gnu
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1143
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1144
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1145
  * Create chroot on the *build* system, configuring it for *target* system:
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1146
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1147
sudo qemu-debootstrap --arch=arm64 --verbose \
52921
f83b21839314 8215129: Update build documentation with Xrandr
ihse
parents: 52734
diff changeset
  1148
       --include=fakeroot,build-essential,libx11-dev,libxext-dev,libxrender-dev,libxrandr-dev,libxtst-dev,libxt-dev,libcups2-dev,libfontconfig1-dev,libasound2-dev,libfreetype6-dev,libpng12-dev \
51515
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1149
       --resolve-deps jessie /chroots/arm64 http://httpredir.debian.org/debian/
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1150
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1151
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1152
  * Configure and build with newly created chroot as sysroot/toolchain-path:
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1153
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1154
CC=aarch64-linux-gnu-gcc CXX=aarch64-linux-gnu-g++ sh ./configure --openjdk-target=aarch64-linux-gnu --with-sysroot=/chroots/arm64/ --with-toolchain-path=/chroots/arm64/
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1155
make images
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1156
ls build/linux-aarch64-normal-server-release/
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1157
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1158
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1159
The build does not create new files in that chroot, so it can be reused for multiple builds
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1160
without additional cleanup.
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1161
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1162
Architectures that are known to successfully cross-compile like this are:
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1163
52941
a430555c3d4e 8215131: Pandoc 2.3/build documentation fixes
ihse
parents: 52921
diff changeset
  1164
  Target        `CC`                      `CXX`                       `--arch=...`  `--openjdk-target=...`
a430555c3d4e 8215131: Pandoc 2.3/build documentation fixes
ihse
parents: 52921
diff changeset
  1165
  ------------  ------------------------- --------------------------- ------------- -----------------------
a430555c3d4e 8215131: Pandoc 2.3/build documentation fixes
ihse
parents: 52921
diff changeset
  1166
  x86           default                   default                     i386          i386-linux-gnu
a430555c3d4e 8215131: Pandoc 2.3/build documentation fixes
ihse
parents: 52921
diff changeset
  1167
  armhf         gcc-arm-linux-gnueabihf   g++-arm-linux-gnueabihf     armhf         arm-linux-gnueabihf
a430555c3d4e 8215131: Pandoc 2.3/build documentation fixes
ihse
parents: 52921
diff changeset
  1168
  aarch64       gcc-aarch64-linux-gnu     g++-aarch64-linux-gnu       arm64         aarch64-linux-gnu
a430555c3d4e 8215131: Pandoc 2.3/build documentation fixes
ihse
parents: 52921
diff changeset
  1169
  ppc64el       gcc-powerpc64le-linux-gnu g++-powerpc64le-linux-gnu   ppc64el       powerpc64le-linux-gnu
a430555c3d4e 8215131: Pandoc 2.3/build documentation fixes
ihse
parents: 52921
diff changeset
  1170
  s390x         gcc-s390x-linux-gnu       g++-s390x-linux-gnu         s390x         s390x-linux-gnu
51515
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1171
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1172
Additional architectures might be supported by Debian/Ubuntu Ports.
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1173
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1174
### Building for ARM/aarch64
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1175
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1176
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
  1177
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
  1178
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
  1179
armv5-vfp-sflt, armv6-vfp-hflt. Note that soft-float ABIs are no longer
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1180
properly supported by the JDK.
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
### Verifying the Build
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1183
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1184
The build will end up in a directory named like
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1185
`build/linux-arm-normal-server-release`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1186
50490
cbae0e359538 8200132: Remove jre images and bundles
erikj
parents: 50267
diff changeset
  1187
Inside this build output directory, the `images/jdk` will contain the newly
cbae0e359538 8200132: Remove jre images and bundles
erikj
parents: 50267
diff changeset
  1188
built JDK, for your *target* system.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1189
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1190
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
  1191
`images/jdk/bin/java -version`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1192
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1193
## Build Performance
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1194
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1195
Building the JDK requires a lot of horsepower. Some of the build tools can be
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1196
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
  1197
memory. The `configure` script analyzes your system and selects reasonable
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1198
values for such options based on your hardware. If you encounter resource
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1199
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
  1200
with:
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1201
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1202
  * `--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
  1203
    `--with-num-cores=8`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1204
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1205
  * `--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
  1206
    `--with-memory-size=1024`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1207
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1208
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
  1209
`--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
  1210
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
  1211
problems for some make targets.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1212
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1213
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
  1214
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
  1215
default JVM arguments passed to the Boot JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1216
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1217
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
  1218
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
  1219
performance hints. If you want to build fast, pay attention to those!
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
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
  1222
time summary at the end of the build process.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1223
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1224
### Disk Speed
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
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
  1227
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
  1228
/localdisk/jdk-build $JDK-SHARE/build`). The performance penalty is extremely
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1229
high for building on a network share; close to unusable.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1230
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1231
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
  1232
located on a local disk and not a network share.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1233
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1234
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
  1235
as well as (if possible) the build tools.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1236
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1237
### Virus Checking
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1238
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1239
The use of virus checking software, especially on Windows, can *significantly*
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1240
slow down building of the JDK. If possible, turn off such software, or exclude
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1241
the directory containing the JDK source code from on-the-fly checking.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1242
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1243
### Ccache
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1244
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1245
The JDK build supports building with ccache when using gcc or clang. Using
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1246
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
  1247
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
  1248
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
  1249
`--enable-ccache`.
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1250
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1251
### Precompiled Headers
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1252
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1253
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
  1254
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
  1255
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
  1256
things down.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1257
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1258
You can experiment by disabling precompiled headers using
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1259
`--disable-precompiled-headers`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1260
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1261
### Icecc / icecream
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1262
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1263
[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
  1264
distributed compiler network. If you have multiple machines available for
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1265
building the JDK, you can drastically cut individual build times by utilizing
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1266
it.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1267
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1268
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
  1269
run `configure` using `--enable-icecc`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1270
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1271
### Using sjavac
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1272
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1273
To speed up Java compilation, especially incremental compilations, you can try
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1274
the experimental sjavac compiler by using `--enable-sjavac`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1275
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1276
### Building the Right Target
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1277
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1278
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
  1279
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
  1280
build `images` for shipping, or if your tests require it.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1281
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1282
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
  1283
how to build an even smaller subset of the product.
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
## Troubleshooting
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1286
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1287
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
  1288
find a proper solution.
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
### Locating the Source of the Error
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1291
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1292
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
  1293
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
  1294
with the output interlaced.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1295
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1296
#### Build Failure Summary
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1297
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1298
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
  1299
like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1300
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1301
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1302
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
  1303
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1304
=== Output from failing command(s) repeated here ===
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1305
* For target hotspot_variant-server_libjvm_objs_psMemoryPool.o:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1306
/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
  1307
   ... (rest of output omitted)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1308
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1309
* 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
  1310
=== End of repeated output ===
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1311
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1312
=== Make failed targets repeated here ===
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1313
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
  1314
make/Main.gmk:263: recipe for target 'hotspot-server-libs' failed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1315
=== End of repeated output ===
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1316
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1317
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
  1318
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
  1319
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1320
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1321
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
  1322
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
  1323
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1324
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
  1325
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
  1326
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
  1327
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
  1328
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
  1329
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1330
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
  1331
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
  1332
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
  1333
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
  1334
`. <path to failure-logs>/<target>.cmd` in your shell.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1335
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1336
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
  1337
top-level targets to individual file targets. Between `Make failed targets
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1338
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
  1339
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
  1340
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
  1341
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
  1342
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1343
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
  1344
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
  1345
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
  1346
Error`" or "`***`".
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1347
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1348
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
  1349
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
  1350
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
  1351
indication of failed target found` instead of the make target chain.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1352
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1353
#### Checking the Build Log File
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1354
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1355
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
  1356
`$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
  1357
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
  1358
want to process it.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1359
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1360
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
  1361
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
  1362
`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
  1363
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
  1364
`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
  1365
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
  1366
will produce a massive build log!
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
### Fixing Unexpected Build Failures
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1369
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1370
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
  1371
code.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1372
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1373
Sometimes the build can fail with no apparent changes that have caused the
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1374
failure. If this is the first time you are building the JDK on this particular
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1375
computer, and the build fails, the problem is likely with your build
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1376
environment. But even if you have previously built the JDK with success, and it
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1377
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
  1378
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
  1379
the incremental rebuild.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1380
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1381
#### Problems with the Build Environment
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1382
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1383
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
  1384
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
  1385
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
  1386
`$BUILD/configure.log`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1387
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1388
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
  1389
JDK and native toolchain that you expect?
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1390
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1391
By default, the JDK has a strict approach where warnings from the compiler is
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1392
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
  1393
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
  1394
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
  1395
(The warnings will still show, but not make the build fail.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1396
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1397
#### Problems with Incremental Rebuilds
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1398
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1399
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
  1400
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
  1401
significantly speed up the development process, from time to time complex
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1402
interdependencies will result in an incorrect build result. This is the most
52610
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1403
common cause for unexpected build problems.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1404
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1405
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
  1406
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
  1407
order. Most issues will be solved at step 1 or 2.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1408
52610
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1409
 1. Make sure your repository is up-to-date
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1410
52610
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1411
    Run `hg pull -u` to make sure you have the latest changes.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1412
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1413
 2. Clean build results
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1414
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1415
    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
  1416
    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
  1417
    system support artifacts. In most cases, this will solve build errors
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1418
    resulting from incremental build mismatches.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1419
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1420
 3. Completely clean the build directory.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1421
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1422
    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
  1423
    removing the build output directory (`$BUILD`). This will clean all
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1424
    generated output, including your configuration. You will need to re-run
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1425
    `configure` after this step. A good idea is to run `make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1426
    print-configuration` before running `make dist-clean`, as this will print
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1427
    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
  1428
45763
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
    make print-configuration > current-configuration
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1431
    make dist-clean
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1432
    bash configure $(cat current-configuration)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1433
    make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1434
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1435
52610
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1436
 4. Re-clone the Mercurial repository
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1437
52610
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1438
    Sometimes the Mercurial repository gets in a state that causes the product
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1439
    to be un-buildable. In such a case, the simplest solution is often the
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1440
    "sledgehammer approach": delete the entire repository, and re-clone it.
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1441
    If you have local changes, save them first to a different location using
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1442
    `hg export`.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1443
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1444
### Specific Build Issues
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1445
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1446
#### Clock Skew
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1447
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1448
If you get an error message like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1449
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1450
File 'xxx' has modification time in the future.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1451
Clock skew detected. Your build may be incomplete.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1452
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1453
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
  1454
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
  1455
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
  1456
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
  1457
an out-of-sync clock.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1458
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1459
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
  1460
clean` and restart the build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1461
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1462
#### Out of Memory Errors
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
On Solaris, you might get an error message like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1465
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1466
Trouble writing out table to disk
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
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
  1469
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1470
On Windows, you might get error messages like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1471
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1472
fatal error - couldn't allocate heap
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1473
cannot create ... Permission denied
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1474
spawn failed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1475
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1476
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
  1477
problems in the [Cygwin](#cygwin) section. Rebooting the computer might help
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1478
temporarily.
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
### Getting Help
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1481
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1482
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
  1483
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
  1484
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
  1485
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
  1486
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1487
If you need general help or advice about developing for the JDK, you can also
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1488
contact the Adoption Group. See the section on [Contributing to OpenJDK](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1489
#contributing-to-openjdk) for more information.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1490
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1491
## Hints and Suggestions for Advanced Users
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1492
52610
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1493
### Setting Up a Repository for Pushing Changes (defpath)
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1494
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1495
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
  1496
a useful tool known as [defpath](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1497
http://openjdk.java.net/projects/code-tools/defpath). It will help you setup a
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1498
proper push path for pushing changes to the JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1499
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1500
Install the extension by cloning
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1501
`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
  1502
Here's one way to do this:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1503
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1504
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1505
cd ~
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1506
mkdir hg-ext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1507
cd hg-ext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1508
hg clone http://hg.openjdk.java.net/code-tools/defpath
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1509
cat << EOT >> ~/.hgrc
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1510
[extensions]
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1511
defpath=~/hg-ext/defpath/defpath.py
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1512
EOT
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1513
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1514
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1515
You can now setup a proper push path using:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1516
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1517
hg defpath -d -u <your OpenJDK username>
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1518
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1519
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1520
### Bash Completion
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1521
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1522
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
  1523
completion (using `<tab>` or `<tab><tab>`). To use this functionality, make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1524
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
  1525
your operating system).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1526
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1527
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
  1528
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
  1529
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1530
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
  1531
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
  1532
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
  1533
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
  1534
to your path:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1535
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1536
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1537
cat << EOT > /tmp/configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1538
#!/bin/bash
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1539
if [ \$(pwd) = \$(cd \$(dirname \$0); pwd) ] ; then
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1540
  echo >&2 "Abort: Trying to call configure helper recursively"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1541
  exit 1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1542
fi
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1543
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1544
bash \$PWD/configure "\$@"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1545
EOT
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1546
chmod +x /tmp/configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1547
sudo mv /tmp/configure /usr/local/bin
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1548
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1549
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1550
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
  1551
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1552
### Using Multiple Configurations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1553
52610
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1554
You can have multiple configurations for a single source repository. When you
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1555
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
  1556
configuration with the name `<name>`. Alternatively, you can create a directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1557
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
  1558
build/<name> && bash ../../configure`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1559
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1560
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
  1561
CONF=<pattern>`, where `<pattern>` is a substring matching one or several
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1562
configurations, e.g. `CONF=debug`. The special empty pattern (`CONF=`) will
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1563
match *all* available configuration, so `make CONF= hotspot` will build the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1564
`hotspot` target for all configurations. Alternatively, you can execute `make`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1565
in the configuration directory, e.g. `cd build/<name> && make`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1566
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1567
### Handling Reconfigurations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1568
52610
7ac273f045e3 8214062: JDK-8167368 Leftover: get_source.sh in build documentation
erikj
parents: 52351
diff changeset
  1569
If you update the repository and part of the configure script has changed, the
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1570
build system will force you to re-run `configure`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1571
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1572
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
  1573
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
  1574
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
  1575
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
  1576
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
  1577
file, `make` will always run `reconfigure` automatically whenever the configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1578
script has changed.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1579
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1580
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
  1581
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
  1582
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
  1583
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1584
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
  1585
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
  1586
your current configuration.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1587
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1588
### Using Fine-Grained Make Targets
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1589
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1590
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
  1591
the expense of build speed, if necessary.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1592
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1593
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
  1594
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
  1595
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
  1596
product.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1597
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1598
#### Building Individual Modules
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1599
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1600
The safe way to use fine-grained make targets is to use the module specific
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1601
make targets. All source code in the JDK is organized so it belongs to a
50586
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
  1602
module, e.g. `java.base` or `jdk.jdwp.agent`. You can build only a specific
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
  1603
module, by giving it as make target: `make jdk.jdwp.agent`. If the specified
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
  1604
module depends on other modules (e.g. `java.base`), those modules will be built
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
  1605
first.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1606
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1607
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
  1608
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
  1609
jdk.crypto.ucrypto`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1610
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1611
#### Building Individual Module Phases
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1612
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1613
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
  1614
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
  1615
and other artifact the module consists of. The phases are:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1616
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1617
  * `gensrc` (Generate source code to compile)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1618
  * `gendata` (Generate non-source code artifacts)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1619
  * `copy` (Copy resource artifacts)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1620
  * `java` (Compile Java code)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1621
  * `launchers` (Compile native executables)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1622
  * `libs` (Compile native libraries)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1623
  * `rmic` (Run the `rmic` tool)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1624
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1625
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
  1626
`$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
  1627
use `make java.base-gensrc`.
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
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
  1630
present). Make will build all needed prerequisites before building the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1631
requested phase.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1632
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1633
#### Skipping the Dependency Check
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1634
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1635
When using an iterative development style with frequent quick rebuilds, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1636
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
  1637
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
  1638
check in make.
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
> **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
  1641
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1642
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
  1643
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
  1644
`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
  1645
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
  1646
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1647
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
  1648
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
  1649
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1650
#### Rebuilding Part of java.base (JDK\_FILTER)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1651
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1652
If you are modifying files in `java.base`, which is the by far largest module
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1653
in the JDK, then you need to rebuild all those files whenever a single file has
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1654
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
  1655
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1656
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
  1657
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
  1658
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
  1659
`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
  1660
to files in the `javax.crypto` package.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1661
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1662
### Learn About Mercurial
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1663
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1664
To become an efficient JDK developer, it is recommended that you invest in
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1665
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
  1666
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1667
  * [Mercurial for git users](http://www.mercurial-scm.org/wiki/GitConcepts)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1668
  * [The official Mercurial tutorial](http://www.mercurial-scm.org/wiki/Tutorial)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1669
  * [hg init](http://hginit.com/)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1670
  * [Mercurial: The Definitive Guide](http://hgbook.red-bean.com/read/)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1671
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1672
## Understanding the Build System
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1673
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1674
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
  1675
build system.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1676
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1677
### Configurations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1678
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1679
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
  1680
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
  1681
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
  1682
principle the configuration (directly or by files included by `spec.gmk`).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1683
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1684
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
  1685
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
  1686
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
  1687
used under the hood by the build system.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1688
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1689
### Build Output Structure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1690
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1691
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
  1692
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
  1693
contains the following important directories:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1694
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1695
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1696
buildtools/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1697
configure-support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1698
hotspot/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1699
images/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1700
jdk/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1701
make-support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1702
support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1703
test-results/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1704
test-support/
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
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1707
This is what they are used for:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1708
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1709
  * `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
  1710
    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
  1711
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1712
  * `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
  1713
    launch the newly built JDK by running `$BUILD/jdk/bin/java`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1714
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1715
  * `test-results`: This directory contains the results from running tests.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1716
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1717
  * `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
  1718
    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
  1719
    directories in `support` is `gensrc`, which contains the generated source
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1720
    code, and the `modules_*` directories, which contains the files in a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1721
    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
  1722
    of the exploded image.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1723
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1724
  * `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
  1725
    that are used during the rest of the build.
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
  * `hotspot`: This is an area for intermediate files needed when building
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1728
    hotspot.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1729
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1730
  * `configure-support`, `make-support` and `test-support`: These directories
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1731
    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
  1732
    and for running tests.
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
### Fixpath
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1735
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1736
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
  1737
`/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
  1738
mismatch when running on Windows.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1739
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1740
In the JDK build, we always use Unix paths internally, and only just before
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1741
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
  1742
Windows paths.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1743
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1744
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
  1745
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
  1746
compiled automatically by `configure`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1747
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1748
### Native Debug Symbols
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1749
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1750
Native libraries and executables can have debug symbol (and other debug
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1751
information) associated with them. How this works is very much platform
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1752
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
  1753
disk space, but is rarely needed by the end user.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1754
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1755
The JDK supports different methods on how to handle debug symbols. The
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1756
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
  1757
are `none`, `internal`, `external`, `zipped`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1758
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1759
  * `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
  1760
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1761
  * `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
  1762
    they will be stored in the generated binary.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1763
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1764
  * `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
  1765
    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
  1766
    (This was previously known as FDS, Full Debug Symbols).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1767
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1768
  * `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
  1769
    into a `.diz` file.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1770
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1771
When building for distribution, `zipped` is a good solution. Binaries built
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1772
with `internal` is suitable for use by developers, since they facilitate
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1773
debugging, but should be stripped before distributed to end users.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1774
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1775
### Autoconf Details
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1776
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1777
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
  1778
deviate from a normal autoconf `configure` script.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1779
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1780
The `configure` script in the top level directory of the JDK is just a thin
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1781
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
  1782
to create the runnable (generated) configure script, as
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1783
`.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
  1784
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
  1785
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
  1786
part of this functionality, the generated script is called.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1787
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1788
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
  1789
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
  1790
manually request such an update by `bash configure autogen`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1791
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1792
In previous versions of the JDK, the generated script was checked in at
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1793
`make/autoconf/generated-configure.sh`. This is no longer the case.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1794
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1795
### Developing the Build System Itself
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1796
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1797
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
  1798
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
  1799
code.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1800
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1801
While technically using `make`, the make source files of the JDK does not
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1802
resemble most other Makefiles. Instead of listing specific targets and actions
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1803
(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
  1804
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
  1805
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
  1806
a call like this would be made:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1807
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1808
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1809
$(eval $(call SetupJavaCompilation, BUILD_FOO_CLASSES, \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1810
    SETUP := GENERATE_OLDBYTECODE, \
47219
fd36993f7bf5 8187542: Remove superfluous *_TOPDIR variables
ihse
parents: 47217
diff changeset
  1811
    SRC := $(TOPDIR)/src/jkd.foo/share/classes, \
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1812
    INCLUDES := jdk/internal/foo, \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1813
    BIN := $(SUPPORT_OUTPUTDIR)/foo_classes, \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1814
))
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1815
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1816
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1817
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
  1818
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
  1819
build a much more powerful and flexible build system.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1820
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1821
Correct dependency tracking is paramount. Sloppy dependency tracking will lead
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1822
to improper parallelization, or worse, race conditions.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1823
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1824
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
  1825
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
  1826
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1827
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
  1828
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
  1829
builds you want to compare.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1830
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1831
To automatically build two consecutive versions and compare them, use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1832
`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
  1833
assignments, like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1834
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1835
make COMPARE_BUILD=CONF=--enable-new-hotspot-feature:MAKE=hotspot
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1836
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1837
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
  1838
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1839
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
  1840
Use `JOBS=1` to avoid parallelism.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1841
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1842
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
  1843
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
  1844
submitting patches.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1845
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1846
## Contributing to the JDK
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1847
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1848
So, now you've built your JDK, and made your first patch, and want to
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1849
contribute it back to the OpenJDK Community.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1850
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1851
First of all: Thank you! We gladly welcome your contribution.
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1852
However, please bear in mind that the JDK is a massive project, and we must ask
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1853
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
  1854
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1855
The official place to start is the ['How to contribute' page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1856
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
  1857
outdated and skimpy on details) [Developer's Guide](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1858
http://openjdk.java.net/guide/).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1859
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1860
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
  1861
good place to start is their ['New Contributor' page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1862
https://wiki.openjdk.java.net/display/Adoption/New+Contributor), or start
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1863
reading the comprehensive [Getting Started Kit](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1864
https://adoptopenjdk.gitbooks.io/adoptopenjdk-getting-started-kit/en/). The
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1865
Adoption Group will also happily answer any questions you have about
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1866
contributing. Contact them by [mail](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1867
http://mail.openjdk.java.net/mailman/listinfo/adoption-discuss) or [IRC](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1868
http://openjdk.java.net/irc/).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1869
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1870
---
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1871
# 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
  1872
header-includes:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1873
 - '<style type="text/css">pre, code, tt { color: #1d6ae5; }</style>'
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1874
---