doc/building.md
author psadhukhan
Fri, 09 Nov 2018 09:29:43 +0530
changeset 52543 3853631e6a07
parent 52351 0ecb4e520110
child 52610 7ac273f045e3
permissions -rw-r--r--
8213181: Updation of ProblemList.txt for removal of passing swing test Reviewed-by: serb
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
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
    51
can see a list of all available forests. If you want to build an older version,
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
    52
e.g. JDK 8, it is recommended that you get the `jdk8u` forest, which contains
72e3ae9a25eb 8187444: Forest Consolidation: Make build work
erikj
parents: 47216
diff changeset
    53
incremental updates, instead of the `jdk8` forest, which was frozen at JDK 8 GA.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    54
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    55
If you are new to Mercurial, a good place to start is the [Mercurial Beginner's
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    56
Guide](http://www.mercurial-scm.org/guide). The rest of this document assumes a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    57
working knowledge of Mercurial.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    58
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    59
### Special Considerations
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    60
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    61
For a smooth building experience, it is recommended that you follow these rules
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    62
on where and how to check out the source code.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    63
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    64
  * Do not check out the source code in a path which contains spaces. Chances
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    65
    are the build will not work. This is most likely to be an issue on Windows
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    66
    systems.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    67
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    68
  * Do not check out the source code in a path which has a very long name or is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    69
    nested many levels deep. Chances are you will hit an OS limitation during
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    70
    the build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    71
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    72
  * Put the source code on a local disk, not a network share. If possible, use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    73
    an SSD. The build process is very disk intensive, and having slow disk
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    74
    access will significantly increase build times. If you need to use a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    75
    network share for the source code, see below for suggestions on how to keep
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    76
    the build artifacts on a local disk.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    77
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    78
  * On Windows, extra care must be taken to make sure the [Cygwin](#cygwin)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    79
    environment is consistent. It is recommended that you follow this
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    80
    procedure:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    81
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
    82
      * Create the directory that is going to contain the top directory of the
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
 -----------------  -------------------------------------------------------
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   153
 Linux              Oracle Enterprise Linux 6.4 / 7.1 (using kernel 3.8.13)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   154
 Solaris            Solaris 11.1 SRU 21.4.1 / 11.2 SRU 5.5
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   155
 macOS              Mac OS X 10.9 (Mavericks) / 10.10 (Yosemite)
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
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   158
The double version numbers for Linux, Solaris and macOS is due to the hybrid
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   159
model used at Oracle, where header files and external libraries from an older
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   160
version 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.
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
   177
Currently, the only supported such layer is Cygwin. (Msys is no longer
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   178
supported due to a too old bash; msys2 and the new Windows Subsystem for Linux
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   179
(WSL) would likely be possible to support in a future version but that would
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   180
require effort 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
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   191
A functioning [Cygwin](http://www.cygwin.com/) environment is thus 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
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   201
The JDK requires GNU Make 4.0 or greater on Windows. 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
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   224
### Solaris
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   225
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   226
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
   227
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
   228
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
   229
properly.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   230
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   231
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
   232
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
   233
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
   234
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
   235
symbols.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   236
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   237
### macOS
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   238
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   239
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
   240
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
   241
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
   242
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
   243
strategies to deal with this.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   244
51237
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   245
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
   246
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
   247
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   248
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
   249
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
   250
[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
   251
manager you want (or none).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   252
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   253
### Linux
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   254
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   255
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
   256
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
   257
by your distribution.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   258
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   259
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
   260
will most likely need to install developer packages.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   261
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   262
For apt-based distributions (Debian, Ubuntu, etc), try this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   263
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   264
sudo apt-get install build-essential
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   265
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   266
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   267
For rpm-based distributions (Fedora, Red Hat, etc), try this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   268
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   269
sudo yum groupinstall "Development Tools"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   270
```
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
### AIX
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   273
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   274
The regular builds by SAP is using AIX version 7.1, but AIX 5.3 is also
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   275
supported. See the [OpenJDK PowerPC Port Status Page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   276
http://cr.openjdk.java.net/~simonis/ppc-aix-port) for details.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   277
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   278
## Native Compiler (Toolchain) Requirements
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   279
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   280
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
   281
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
   282
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
   283
one-to-one correlation between target operating system and toolchain.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   284
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   285
 Operating system   Supported toolchain
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   286
 ------------------ -------------------------
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   287
 Linux              gcc, clang
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   288
 macOS              Apple Xcode (using clang)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   289
 Solaris            Oracle Solaris Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   290
 AIX                IBM XL C/C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   291
 Windows            Microsoft Visual Studio
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
Please see the individual sections on the toolchains for version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   294
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
   295
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
   296
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
   297
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
   298
issues.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   299
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   300
 Operating system   Toolchain version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   301
 ------------------ -------------------------------------------------------
50586
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
   302
 Linux              gcc 7.3.0
51237
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   303
 macOS              Apple Xcode 9.4 (using clang 9.1.0)
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   304
 Solaris            Oracle Solaris Studio 12.4 (with compiler version 5.13)
51237
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   305
 Windows            Microsoft Visual Studio 2017 update 15.5.5
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   306
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   307
### gcc
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   308
50586
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
   309
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
   310
by `configure` and are unlikely to work.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   311
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   312
The JDK is currently known to be able to compile with at least version 7.4 of
50586
4bba6dea2e73 8200867: Remove references to "jdk 9" in build system
ihse
parents: 50490
diff changeset
   313
gcc.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   314
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   315
In general, any version between these two should be usable.
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
### clang
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   318
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   319
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
   320
accepted by `configure`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   321
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   322
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
   323
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   324
### Apple Xcode
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   325
51237
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   326
The oldest supported version of Xcode is 8.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   327
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   328
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
   329
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
   330
The simplest way to install these is to run:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   331
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   332
xcode-select --install
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   333
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   334
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   335
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
   336
updating Xcode. This [blog page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   337
http://iosdevelopertips.com/xcode/install-multiple-versions-of-xcode.html) has
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   338
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
   339
of Xcode, use `xcode-select -s` before running `configure`, or use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   340
`--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
   341
`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
   342
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   343
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
   344
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
   345
Build Environment](#problems-with-the-build-environment), and [Getting
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   346
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
   347
available for this update.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   348
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   349
### Oracle Solaris Studio
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
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
   352
(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
   353
configure.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   354
34595
09596fe63e2d 8145391: Updated jprt.properties, devtools, jib and readme with SS12u4
erikj
parents: 33030
diff changeset
   355
The Solaris Studio installation should contain at least these packages:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   356
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   357
 Package                                            Version
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   358
 -------------------------------------------------- -------------
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   359
 developer/solarisstudio-124/backend                12.4-1.0.6.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   360
 developer/solarisstudio-124/c++                    12.4-1.0.10.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   361
 developer/solarisstudio-124/cc                     12.4-1.0.4.0
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   362
 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
   363
 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
   364
 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
   365
 developer/solarisstudio-124/studio-common          12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   366
 developer/solarisstudio-124/studio-ja              12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   367
 developer/solarisstudio-124/studio-legal           12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   368
 developer/solarisstudio-124/studio-zhCN            12.4-1.0.0.1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   369
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   370
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
   371
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
   372
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   373
$ cc -V
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   374
cc: Sun C 5.13 SunOS_i386 2014/10/20
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   375
$ CC -V
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   376
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
   377
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   378
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   379
### Microsoft Visual Studio
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   380
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   381
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
   382
be accepted by `configure`. The maximum accepted version of Visual Studio is
51237
ea900a7dc7d7 8208096: Update build documentation to reflect compiler upgrades at Oracle
erikj
parents: 50885
diff changeset
   383
2017. 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
   384
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   385
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
   386
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
   387
setting `--with-toolchain-version`, e.g. `--with-toolchain-version=2015`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   388
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   389
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
   390
invalid` when building using Visual Studio 2010, you have encountered
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   391
[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
   392
specific installation order. However, the solution suggested by the KB article
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   393
does not always resolve the problem. See [this stackoverflow discussion](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   394
https://stackoverflow.com/questions/10888391) for other suggestions.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   395
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   396
### IBM XL C/C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   397
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   398
The regular builds by SAP is using version 12.1, described as `IBM XL C/C++ for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   399
AIX, V12.1 (5765-J02, 5725-C72) Version: 12.01.0000.0017`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   400
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   401
See the [OpenJDK PowerPC Port Status Page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   402
http://cr.openjdk.java.net/~simonis/ppc-aix-port) for details.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   403
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   404
## Boot JDK Requirements
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   405
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   406
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
   407
"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
   408
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
   409
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
   410
platform that is usable as boot JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   411
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   412
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
   413
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
   414
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
   415
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
   416
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
   417
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
   418
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   419
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
   420
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
   421
is available.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   422
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   423
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
   424
`--with-boot-jdk` to point to the JDK to use.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   425
49159
436f1e03fd04 8199266: Update boot and build jdk requirements in configure
erikj
parents: 48743
diff changeset
   426
### Getting JDK binaries
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   427
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   428
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
   429
[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
   430
[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
   431
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
   432
experimental prebuilt binaries for various platforms.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   433
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   434
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
   435
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
   436
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
   437
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
   438
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   439
## External Library Requirements
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   440
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   441
Different platforms require different external libraries. In general, libraries
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   442
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
   443
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   444
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
   445
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
   446
external library: `--with-<LIB>=<path>` or `--with-<LIB>-include=<path to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   447
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
   448
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
   449
under this directory. In most cases, it works fine.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   450
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   451
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
   452
and the lib directory separately.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   453
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   454
### FreeType
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   455
49234
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   456
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
   457
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
   458
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
   459
rather than bundling the JDK’s own copy.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   460
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   461
  * 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
   462
    libfreetype6-dev`.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   463
  * 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
   464
    freetype-devel`.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   465
  * 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
   466
49234
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   467
Use `--with-freetype-include=<path>` and `--with-freetype-lib=<path>`
3375a8039fde 8193017: Import freetype sources into OpenJDK source tree
prr
parents: 49159
diff changeset
   468
if `configure` does not automatically locate the platform FreeType files.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   469
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   470
### CUPS
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
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
   473
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
   474
your operating system.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   475
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   476
  * 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
   477
    libcups2-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   478
  * 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
   479
    cups-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   480
  * To install on Solaris, try running `pkg install print/cups`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   481
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   482
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
   483
files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   484
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   485
### X11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   486
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   487
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
   488
Linux and Solaris.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   489
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   490
  * 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
   491
    libx11-dev libxext-dev libxrender-dev libxtst-dev libxt-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   492
  * 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
   493
    libXtst-devel libXt-devel libXrender-devel libXi-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   494
  * 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
   495
    x11/library/libice x11/library/libpthread-stubs x11/library/libsm
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   496
    x11/library/libx11 x11/library/libxau x11/library/libxcb
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   497
    x11/library/libxdmcp x11/library/libxevie x11/library/libxext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   498
    x11/library/libxrender x11/library/libxscrnsaver x11/library/libxtst
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   499
    x11/library/toolkit/libxt`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   500
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   501
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
   502
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   503
### ALSA
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   504
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   505
ALSA, [Advanced Linux Sound Architecture](https://www.alsa-project.org/) is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   506
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
   507
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   508
  * 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
   509
    libasound2-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   510
  * 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
   511
    alsa-lib-devel`.
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
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
   514
files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   515
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   516
### libffi
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   517
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   518
libffi, the [Portable Foreign Function Interface Library](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   519
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
   520
Hotspot.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   521
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   522
  * 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
   523
    libffi-dev`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   524
  * 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
   525
    libffi-devel`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   526
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   527
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
   528
files.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   529
48743
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   530
## Build Tools Requirements
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   531
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   532
### Autoconf
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   533
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   534
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
   535
platforms. At least version 2.69 is required.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   536
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   537
  * 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
   538
    autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   539
  * 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
   540
    autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   541
  * To install on macOS, try running `brew install autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   542
  * 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
   543
    -P autoconf`.
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   544
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   545
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
   546
specify it using the `AUTOCONF` environment variable, like this:
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   547
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   548
```
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   549
AUTOCONF=<path to autoconf> configure ...
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
   550
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   551
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   552
### GNU Make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   553
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   554
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
   555
of make are supported.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   556
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   557
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
   558
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
   559
functionality to handle parallel building (supported by `--with-output-sync`)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   560
and speed and stability improvements.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   561
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   562
Note that `configure` locates and verifies a properly functioning version of
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   563
`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
   564
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
   565
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
   566
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
   567
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
   568
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
   569
`make` in your path, this might cause issues.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   570
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   571
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
   572
configure variable, e.g. `configure MAKE=/opt/gnu/make`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   573
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   574
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
   575
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   576
### GNU Bash
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   577
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   578
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
   579
are supported.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   580
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   581
At least version 3.2 of GNU Bash must be used.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   582
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   583
## Running Configure
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   584
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   585
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
   586
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
   587
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
   588
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   589
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
   590
the `configure` script looks like this:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   591
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   592
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   593
bash configure [options]
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   594
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   595
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   596
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
   597
area for the build result. This directory typically looks like
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   598
`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
   599
specific configuration. (It can also be set directly, see [Using Multiple
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   600
Configurations](#using-multiple-configurations)). This directory is referred to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   601
as `$BUILD` in this documentation.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   602
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   603
`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
   604
necessary build components are. If you have all prerequisites for building
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   605
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
   606
automatically, it will exit and inform you about the problem.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   607
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   608
Some command line examples:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   609
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   610
  * 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
   611
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   612
    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
   613
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   614
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   615
  * Create a debug build with the `server` JVM and DTrace enabled:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   616
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   617
    bash configure --enable-debug --with-jvm-variants=server --enable-dtrace
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   618
    ```
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
### Common Configure Arguments
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   621
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   622
Here follows some of the most common and important `configure` argument.
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
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
   625
run:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   626
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   627
bash configure --help
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   628
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   629
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   630
(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
   631
`--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
   632
features, use `bash configure --help=short` instead.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   633
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   634
#### Configure Arguments for Tailoring the Build
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
  * `--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
   637
    for `--with-debug-level=fastdebug`)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   638
  * `--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
   639
    `fastdebug`, `slowdebug` or `optimized`. Default is `release`. `optimized`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   640
    is variant of `release` with additional Hotspot debug code.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   641
  * `--with-native-debug-symbols=<method>` - Specify if and how native debug
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   642
    symbols should be built. Available methods are `none`, `internal`,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   643
    `external`, `zipped`. Default behavior depends on platform. See [Native
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   644
    Debug Symbols](#native-debug-symbols) for more details.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   645
  * `--with-version-string=<string>` - Specify the version string this build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   646
    will be identified with.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   647
  * `--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
   648
    any of `pre`, `opt`, `build`, `major`, `minor`, `security` or `patch`. Use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   649
    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
   650
    from the default, or the value provided by `--with-version-string`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   651
  * `--with-jvm-variants=<variant>[,<variant>...]` - Build the specified variant
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   652
    (or variants) of Hotspot. Valid variants are: `server`, `client`,
47687
fb290fd1f9d4 8171853: Remove Shark compiler
rkennke
parents: 47219
diff changeset
   653
    `minimal`, `core`, `zero`, `custom`. Note that not all
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   654
    variants are possible to combine in a single build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   655
  * `--with-jvm-features=<feature>[,<feature>...]` - Use the specified JVM
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   656
    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
   657
    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
   658
    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
   659
    configure --help`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   660
  * `--with-target-bits=<bits>` - Create a target binary suitable for running
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   661
    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
   662
    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
   663
    *reduced* build.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   664
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   665
#### Configure Arguments for Native Compilation
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   666
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   667
  * `--with-devkit=<path>` - Use this devkit for compilers, tools and resources
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   668
  * `--with-sysroot=<path>` - Use this directory as sysroot
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   669
  * `--with-extra-path=<path>[;<path>]` - Prepend these directories to the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   670
    default path when searching for all kinds of binaries
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   671
  * `--with-toolchain-path=<path>[;<path>]` - Prepend these directories when
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   672
    searching for toolchain binaries (compilers etc)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   673
  * `--with-extra-cflags=<flags>` - Append these flags when compiling JDK C
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   674
    files
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   675
  * `--with-extra-cxxflags=<flags>` - Append these flags when compiling JDK C++
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   676
    files
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   677
  * `--with-extra-ldflags=<flags>` - Append these flags when linking JDK
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   678
    libraries
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   679
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   680
#### Configure Arguments for External Dependencies
44078
673240c54c2e 8176509: Use pandoc for converting build readme to html
ihse
parents: 41040
diff changeset
   681
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   682
  * `--with-boot-jdk=<path>` - Set the path to the [Boot JDK](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   683
    #boot-jdk-requirements)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   684
  * `--with-freetype=<path>` - Set the path to [FreeType](#freetype)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   685
  * `--with-cups=<path>` - Set the path to [CUPS](#cups)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   686
  * `--with-x=<path>` - Set the path to [X11](#x11)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   687
  * `--with-alsa=<path>` - Set the path to [ALSA](#alsa)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   688
  * `--with-libffi=<path>` - Set the path to [libffi](#libffi)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   689
  * `--with-jtreg=<path>` - Set the path to JTReg. See [Running Tests](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   690
    #running-tests)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   691
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   692
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
   693
and zlib) are included in the JDK repository. The default behavior of the
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   694
JDK build is to use this version of these libraries, but they might be
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   695
replaced by an external version. To do so, specify `system` as the `<source>`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   696
option in these arguments. (The default is `bundled`).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   697
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   698
  * `--with-libjpeg=<source>` - Use the specified source for libjpeg
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   699
  * `--with-giflib=<source>` - Use the specified source for giflib
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   700
  * `--with-libpng=<source>` - Use the specified source for libpng
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   701
  * `--with-lcms=<source>` - Use the specified source for lcms
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   702
  * `--with-zlib=<source>` - Use the specified source for zlib
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   703
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   704
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
   705
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
   706
static library is not found.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   707
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   708
  * `--with-stdc++lib=<method>` - Use the specified method (`static`, `dynamic`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   709
    or `default`) for linking the C++ runtime.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   710
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   711
### Configure Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   712
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   713
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
   714
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
   715
environment.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   716
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   717
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
   718
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
   719
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
   720
detected.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   721
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   722
However, there are a few `configure` variables, known as *control variables*
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   723
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
   724
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
   725
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
   726
trying to autodetect the tool. For instance, `bash configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   727
MAKE=/opt/gnumake4.0/bin/make`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   728
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   729
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
   730
instead of setting `JTREGEXE`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   731
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   732
Also note that, despite what autoconf claims, setting `CFLAGS` will not
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   733
accomplish anything. Instead use `--with-extra-cflags` (and similar for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   734
`cxxflags` and `ldflags`).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   735
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   736
## Running Make
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   737
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   738
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
   739
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
   740
correct version of make.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   741
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   742
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
   743
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
   744
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
   745
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
   746
incremental development fashion, when doing a normal make, you should only
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   747
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
   748
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
   749
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   750
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
   751
newly built JDK like this: `$BUILD/jdk/bin/java -version`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   752
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   753
### Common Make Targets
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   754
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   755
Apart from the default target, here are some common make targets:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   756
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   757
  * `hotspot` - Build all of hotspot (but only hotspot)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   758
  * `hotspot-<variant>` - Build just the specified jvm variant
50490
cbae0e359538 8200132: Remove jre images and bundles
erikj
parents: 50267
diff changeset
   759
  * `images` or `product-images` - Build the JDK image
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   760
  * `docs` or `docs-image` - Build the documentation image
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   761
  * `test-image` - Build the test image
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   762
  * `all` or `all-images` - Build all images (product, docs and test)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   763
  * `bootcycle-images` - Build images twice, second time with newly built JDK
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   764
    (good for testing)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   765
  * `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
   766
    configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   767
  * `dist-clean` - Remove all files, including configuration
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   768
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   769
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
   770
control variables.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   771
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   772
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
   773
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
   774
patterns. A phase can be either of `gensrc`, `gendata`, `copy`, `java`,
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   775
`launchers`, `libs` or `rmic`. See [Using Fine-Grained Make Targets](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   776
#using-fine-grained-make-targets) for more details about this functionality.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   777
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   778
  * `<phase>` - Build the specified phase and everything it depends on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   779
  * `<module>` - Build the specified module and everything it depends on
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   780
  * `<module>-<phase>` - Compile the specified phase for the specified module
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   781
    and everything it depends on
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   782
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   783
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
   784
targets according to these patterns:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   785
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   786
  * `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
   787
  * `clean-<phase>` - Remove all build results related to a certain build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   788
    phase
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   789
  * `clean-<module>` - Remove all build results related to a certain module
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   790
  * `clean-<module>-<phase>` - Remove all build results related to a certain
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   791
    module and phase
44078
673240c54c2e 8176509: Use pandoc for converting build readme to html
ihse
parents: 41040
diff changeset
   792
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   793
### Make Control Variables
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   794
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   795
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
   796
variables, either on the command line or in the environment.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   797
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   798
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
   799
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
   800
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
   801
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   802
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
   803
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
   804
configuration, as opposed to the "configure time" configuration.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   805
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   806
#### General Make Control Variables
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
  * `JOBS` - Specify the number of jobs to build with. See [Build
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   809
    Performance](#build-performance).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   810
  * `LOG` - Specify the logging level and functionality. See [Checking the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   811
    Build Log File](#checking-the-build-log-file)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   812
  * `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
   813
    Multiple Configurations](#using-multiple-configurations)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   814
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   815
#### Test Make Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   816
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   817
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
   818
[Testing the JDK](testing.html) for details.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   819
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   820
  * `TEST`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   821
  * `TEST_JOBS`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   822
  * `JTREG`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   823
  * `GTEST`
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
#### Advanced Make Control Variables
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   826
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   827
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
   828
Suggestions for Advanced Users](#hints-and-suggestions-for-advanced-users) and
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   829
[Understanding the Build System](#understanding-the-build-system) for details.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   830
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   831
  * `SPEC`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   832
  * `CONF_CHECK`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   833
  * `COMPARE_BUILD`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   834
  * `JDK_FILTER`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   835
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   836
## Running Tests
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   837
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   838
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
   839
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
   840
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
   841
`--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
   842
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
   843
containing `lib/jtreg.jar` etc.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   844
50267
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49234
diff changeset
   845
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
   846
recent builds of jtreg [here](
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49234
diff changeset
   847
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
   848
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
   849
`jtreg` directory that you just unpacked.
1582de22e3a1 8198323: testing.md not updated for repository layout change
ihse
parents: 49234
diff changeset
   850
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   851
To execute the most basic tests (tier 1), use:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   852
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   853
make run-test-tier1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   854
```
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
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
   857
the JDK](testing.html) document.
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
## Cross-compiling
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   860
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   861
Cross-compiling means using one platform (the *build* platform) to generate
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   862
output that can ran on another platform (the *target* platform).
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
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
   865
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
   866
different, typically low-performing system. Most of the complications that
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   867
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
   868
*target* systems.
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
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
   871
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
   872
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
   873
please see the [external links at Wikipedia](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   874
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
   875
on reading materials.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   876
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
   877
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
   878
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
   879
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
   880
tools.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   881
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   882
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
   883
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
   884
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
   885
work and will take much longer to build.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   886
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   887
### Boot JDK and Build JDK
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   888
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   889
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
   890
system, and not on the *target* system.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   891
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   892
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
   893
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
   894
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
   895
(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
   896
building JDK 9.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   897
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   898
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
   899
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
   900
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
   901
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
   902
match the current sources.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   903
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   904
### Specifying the Target Platform
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   905
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   906
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
   907
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
   908
do this is to use the `--openjdk-target` argument, e.g.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   909
`--openjdk-target=arm-linux-gnueabihf`. or `--openjdk-target=aarch64-oe-linux`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   910
This will automatically set the `--build`, `--host` and `--target` options for
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   911
autoconf, which can otherwise be confusing. (In autoconf terminology, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   912
"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
   913
cross-compiler.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   914
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   915
### Toolchain Considerations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   916
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   917
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
   918
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
   919
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
   920
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
   921
standard is to prefix cross-compiling toolchains with the target denominator.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   922
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
   923
correctly.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   924
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   925
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
   926
*build*/*target* toolchain will be autodetected when not cross-compiling. If
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   927
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
   928
devkit containing the *build* toolchain using `--with-build-devkit` to
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   929
`configure`, or by giving `BUILD_CC` and `BUILD_CXX` arguments.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   930
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   931
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
   932
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
   933
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
   934
appending the directory when searching for cross-compilations tools
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   935
(`--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
   936
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
   937
details.)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   938
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   939
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
   940
working at the time of writing:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   941
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   942
  * [aarch64](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   943
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
   944
  * [arm 32-bit hardware floating  point](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   945
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
   946
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   947
### Native Libraries
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   948
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   949
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
   950
present on the *build* machine while building.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   951
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   952
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
   953
mistake, since that can render the *build* machine unusable.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   954
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   955
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
   956
*target*, not the *build*, platform.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   957
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   958
#### ALSA
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   959
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   960
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
   961
using Debian's pre-built libraries work fine.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   962
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   963
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
   964
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   965
  * 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
   966
    search for the `libasound2` and `libasound2-dev` packages for your *target*
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   967
    system. Download them to /tmp.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   968
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   969
  * Install the libraries into the cross-compilation toolchain. For instance:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   970
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   971
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
   972
dpkg-deb -x /tmp/libasound2_1.0.25-4_armhf.deb .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   973
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
   974
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
   975
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   976
  * 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
   977
    `--with-alsa`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   978
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   979
#### X11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   980
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   981
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
   982
using Debian's pre-built libraries work fine.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   983
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   984
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
   985
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   986
  * Go to [Debian Package Search](https://www.debian.org/distrib/packages),
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   987
    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
   988
    to /tmp/target-x11:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   989
      * libxi
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   990
      * libxi-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   991
      * x11proto-core-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   992
      * x11proto-input-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   993
      * x11proto-kb-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   994
      * x11proto-render-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   995
      * x11proto-xext-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   996
      * libice-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   997
      * libxrender
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   998
      * libxrender-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
   999
      * libsm-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1000
      * libxt-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1001
      * libx11
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1002
      * libx11-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1003
      * libxtst
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1004
      * libxtst-dev
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1005
      * libxext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1006
      * libxext-dev
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1007
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1008
  * Install the libraries into the cross-compilation toolchain. For instance:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1009
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1010
    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
  1011
    mkdir X11R6
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1012
    cd X11R6
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1013
    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
  1014
    mv usr/* .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1015
    cd lib
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1016
    cp arm-linux-gnueabihf/* .
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1017
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1018
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1019
    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
  1020
    successfully complete a full JDK build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1021
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1022
    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
  1023
    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
  1024
    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
  1025
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1026
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1027
  * 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
  1028
    point them out by `--with-x`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1029
51515
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1030
### Creating And Using Sysroots With qemu-deboostrap
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1031
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1032
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
  1033
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
  1034
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
  1035
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
  1036
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
  1037
for foreign architectures with native compilation speed.
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1038
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1039
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
  1040
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1041
  * Install cross-compiler on the *build* system:
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1042
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1043
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
  1044
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1045
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1046
  * 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
  1047
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1048
sudo qemu-debootstrap --arch=arm64 --verbose \
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1049
       --include=fakeroot,build-essential,libx11-dev,libxext-dev,libxrender-dev,libxtst-dev,libxt-dev,libcups2-dev,libfontconfig1-dev,libasound2-dev,libfreetype6-dev,libpng12-dev \
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1050
       --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
  1051
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1052
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1053
  * 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
  1054
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1055
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
  1056
make images
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1057
ls build/linux-aarch64-normal-server-release/
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1058
```
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1059
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1060
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
  1061
without additional cleanup.
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1062
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1063
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
  1064
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1065
  Target        `CC`                      `CXX`                       `--arch=...` `--openjdk-target=...`
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1066
  ------------  ------------------------- --------------------------- ------------ ----------------------
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1067
  x86           default                   default                     i386         i386-linux-gnu
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1068
  armhf         gcc-arm-linux-gnueabihf   g++-arm-linux-gnueabihf     armhf        arm-linux-gnueabihf
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1069
  aarch64       gcc-aarch64-linux-gnu     g++-aarch64-linux-gnu       arm64        aarch64-linux-gnu
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1070
  ppc64el       gcc-powerpc64le-linux-gnu g++-powerpc64le-linux-gnu   ppc64el      powerpc64le-linux-gnu
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1071
  s390x         gcc-s390x-linux-gnu       g++-s390x-linux-gnu         s390x        s390x-linux-gnu
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1072
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1073
Additional architectures might be supported by Debian/Ubuntu Ports.
fa378e035b81 8208665: Amend cross-compilation docs with qemu-debootstrap recipe
shade
parents: 51237
diff changeset
  1074
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1075
### Building for ARM/aarch64
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
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
  1078
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
  1079
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
  1080
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
  1081
properly supported by the JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1082
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1083
### Verifying the Build
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1084
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1085
The build will end up in a directory named like
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1086
`build/linux-arm-normal-server-release`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1087
50490
cbae0e359538 8200132: Remove jre images and bundles
erikj
parents: 50267
diff changeset
  1088
Inside this build output directory, the `images/jdk` will contain the newly
cbae0e359538 8200132: Remove jre images and bundles
erikj
parents: 50267
diff changeset
  1089
built JDK, for your *target* system.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1090
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1091
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
  1092
`images/jdk/bin/java -version`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1093
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1094
## Build Performance
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1095
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1096
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
  1097
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
  1098
memory. The `configure` script analyzes your system and selects reasonable
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1099
values for such options based on your hardware. If you encounter resource
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1100
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
  1101
with:
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1102
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1103
  * `--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
  1104
    `--with-num-cores=8`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1105
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1106
  * `--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
  1107
    `--with-memory-size=1024`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1108
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1109
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
  1110
`--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
  1111
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
  1112
problems for some make targets.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1113
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1114
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
  1115
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
  1116
default JVM arguments passed to the Boot JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1117
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1118
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
  1119
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
  1120
performance hints. If you want to build fast, pay attention to those!
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1121
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1122
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
  1123
time summary at the end of the build process.
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
### Disk Speed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1126
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1127
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
  1128
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
  1129
/localdisk/jdk-build $JDK-SHARE/build`). The performance penalty is extremely
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1130
high for building on a network share; close to unusable.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1131
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1132
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
  1133
located on a local disk and not a network share.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1134
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1135
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
  1136
as well as (if possible) the build tools.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1137
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1138
### Virus Checking
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1139
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1140
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
  1141
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
  1142
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
  1143
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1144
### Ccache
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1145
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1146
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
  1147
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
  1148
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
  1149
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
  1150
`--enable-ccache`.
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1151
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1152
### Precompiled Headers
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1153
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1154
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
  1155
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
  1156
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
  1157
things down.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1158
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1159
You can experiment by disabling precompiled headers using
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1160
`--disable-precompiled-headers`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1161
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1162
### Icecc / icecream
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1163
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1164
[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
  1165
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
  1166
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
  1167
it.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1168
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1169
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
  1170
run `configure` using `--enable-icecc`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1171
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1172
### Using sjavac
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1173
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1174
To speed up Java compilation, especially incremental compilations, you can try
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1175
the experimental sjavac compiler by using `--enable-sjavac`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1176
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1177
### Building the Right Target
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1178
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1179
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
  1180
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
  1181
build `images` for shipping, or if your tests require it.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1182
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1183
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
  1184
how to build an even smaller subset of the product.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1185
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1186
## Troubleshooting
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1187
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1188
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
  1189
find a proper solution.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1190
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1191
### Locating the Source of the Error
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1192
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1193
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
  1194
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
  1195
with the output interlaced.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1196
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1197
#### Build Failure Summary
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1198
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1199
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
  1200
like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1201
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1202
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1203
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
  1204
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1205
=== Output from failing command(s) repeated here ===
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1206
* For target hotspot_variant-server_libjvm_objs_psMemoryPool.o:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1207
/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
  1208
   ... (rest of output omitted)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1209
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1210
* 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
  1211
=== End of repeated output ===
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
=== Make failed targets repeated here ===
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1214
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
  1215
make/Main.gmk:263: recipe for target 'hotspot-server-libs' failed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1216
=== End of repeated output ===
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1217
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1218
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
  1219
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
  1220
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1221
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1222
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
  1223
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
  1224
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1225
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
  1226
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
  1227
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
  1228
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
  1229
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
  1230
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1231
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
  1232
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
  1233
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
  1234
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
  1235
`. <path to failure-logs>/<target>.cmd` in your shell.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1236
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1237
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
  1238
top-level targets to individual file targets. Between `Make failed targets
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1239
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
  1240
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
  1241
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
  1242
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
  1243
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1244
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
  1245
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
  1246
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
  1247
Error`" or "`***`".
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1248
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1249
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
  1250
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
  1251
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
  1252
indication of failed target found` instead of the make target chain.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1253
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1254
#### Checking the Build Log File
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1255
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1256
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
  1257
`$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
  1258
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
  1259
want to process it.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1260
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1261
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
  1262
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
  1263
`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
  1264
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
  1265
`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
  1266
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
  1267
will produce a massive build log!
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1268
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1269
### Fixing Unexpected Build Failures
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1270
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1271
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
  1272
code.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1273
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1274
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
  1275
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
  1276
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
  1277
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
  1278
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
  1279
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
  1280
the incremental rebuild.
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
#### Problems with the Build Environment
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1283
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1284
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
  1285
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
  1286
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
  1287
`$BUILD/configure.log`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1288
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1289
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
  1290
JDK and native toolchain that you expect?
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1291
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1292
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
  1293
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
  1294
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
  1295
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
  1296
(The warnings will still show, but not make the build fail.)
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1297
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1298
#### Problems with Incremental Rebuilds
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1299
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1300
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
  1301
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
  1302
significantly speed up the development process, from time to time complex
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1303
interdependencies will result in an incorrect build result. This is the most
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1304
common cause for unexpected build problems, together with inconsistencies
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1305
between the different Mercurial repositories in the forest.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1306
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1307
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
  1308
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
  1309
order. Most issues will be solved at step 1 or 2.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1310
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1311
 1. Make sure your forest is up-to-date
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1312
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1313
    Run `bash get_source.sh` to make sure you have the latest version of all
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1314
    repositories.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1315
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1316
 2. Clean build results
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1317
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1318
    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
  1319
    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
  1320
    system support artifacts. In most cases, this will solve build errors
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1321
    resulting from incremental build mismatches.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1322
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1323
 3. Completely clean the build directory.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1324
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1325
    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
  1326
    removing the build output directory (`$BUILD`). This will clean all
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1327
    generated output, including your configuration. You will need to re-run
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1328
    `configure` after this step. A good idea is to run `make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1329
    print-configuration` before running `make dist-clean`, as this will print
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1330
    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
  1331
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1332
    ```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1333
    make print-configuration > current-configuration
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1334
    make dist-clean
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1335
    bash configure $(cat current-configuration)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1336
    make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1337
    ```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1338
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1339
 4. Re-clone the Mercurial forest
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1340
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1341
    Sometimes the Mercurial repositories themselves gets in a state that causes
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1342
    the product to be un-buildable. In such a case, the simplest solution is
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1343
    often the "sledgehammer approach": delete the entire forest, and re-clone
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1344
    it. If you have local changes, save them first to a different location
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1345
    using `hg export`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1346
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1347
### Specific Build Issues
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1348
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1349
#### Clock Skew
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1350
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1351
If you get an error message like this:
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
File 'xxx' has modification time in the future.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1354
Clock skew detected. Your build may be incomplete.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1355
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1356
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
  1357
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
  1358
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
  1359
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
  1360
an out-of-sync clock.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1361
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1362
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
  1363
clean` and restart the build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1364
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1365
#### Out of Memory Errors
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1366
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1367
On Solaris, you might get an error message like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1368
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1369
Trouble writing out table to disk
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1370
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1371
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
  1372
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1373
On Windows, you might get error messages like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1374
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1375
fatal error - couldn't allocate heap
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1376
cannot create ... Permission denied
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1377
spawn failed
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1378
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1379
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
  1380
problems in the [Cygwin](#cygwin) section. Rebooting the computer might help
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1381
temporarily.
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
### Getting Help
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1384
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1385
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
  1386
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
  1387
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
  1388
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
  1389
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1390
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
  1391
contact the Adoption Group. See the section on [Contributing to OpenJDK](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1392
#contributing-to-openjdk) for more information.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1393
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1394
## Hints and Suggestions for Advanced Users
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1395
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1396
### Setting Up a Forest for Pushing Changes (defpath)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1397
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1398
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
  1399
a useful tool known as [defpath](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1400
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
  1401
proper push path for pushing changes to the JDK.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1402
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1403
Install the extension by cloning
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1404
`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
  1405
Here's one way to do this:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1406
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1407
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1408
cd ~
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1409
mkdir hg-ext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1410
cd hg-ext
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1411
hg clone http://hg.openjdk.java.net/code-tools/defpath
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1412
cat << EOT >> ~/.hgrc
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1413
[extensions]
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1414
defpath=~/hg-ext/defpath/defpath.py
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1415
EOT
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1416
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1417
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1418
You can now setup a proper push path using:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1419
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1420
hg defpath -d -u <your OpenJDK username>
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1421
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1422
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1423
If you also have the `trees` extension installed in Mercurial, you will
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1424
automatically get a `tdefpath` command, which is even more useful. By running
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1425
`hg tdefpath -du <username>` in the top repository of your forest, all repos
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1426
will get setup automatically. This is the recommended usage.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1427
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1428
### Bash Completion
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
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
  1431
completion (using `<tab>` or `<tab><tab>`). To use this functionality, make
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1432
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
  1433
your operating system).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1434
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1435
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
  1436
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
  1437
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1438
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
  1439
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
  1440
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
  1441
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
  1442
to your path:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1443
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1444
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1445
cat << EOT > /tmp/configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1446
#!/bin/bash
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1447
if [ \$(pwd) = \$(cd \$(dirname \$0); pwd) ] ; then
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1448
  echo >&2 "Abort: Trying to call configure helper recursively"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1449
  exit 1
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1450
fi
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1451
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1452
bash \$PWD/configure "\$@"
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1453
EOT
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1454
chmod +x /tmp/configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1455
sudo mv /tmp/configure /usr/local/bin
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1456
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1457
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1458
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
  1459
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1460
### Using Multiple Configurations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1461
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1462
You can have multiple configurations for a single source forest. When you
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1463
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
  1464
configuration with the name `<name>`. Alternatively, you can create a directory
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1465
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
  1466
build/<name> && bash ../../configure`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1467
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1468
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
  1469
CONF=<pattern>`, where `<pattern>` is a substring matching one or several
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1470
configurations, e.g. `CONF=debug`. The special empty pattern (`CONF=`) will
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1471
match *all* available configuration, so `make CONF= hotspot` will build the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1472
`hotspot` target for all configurations. Alternatively, you can execute `make`
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1473
in the configuration directory, e.g. `cd build/<name> && make`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1474
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1475
### Handling Reconfigurations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1476
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1477
If you update the forest and part of the configure script has changed, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1478
build system will force you to re-run `configure`.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1479
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1480
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
  1481
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
  1482
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
  1483
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
  1484
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
  1485
file, `make` will always run `reconfigure` automatically whenever the configure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1486
script has changed.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1487
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1488
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
  1489
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
  1490
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
  1491
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1492
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
  1493
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
  1494
your current configuration.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1495
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1496
### Using Fine-Grained Make Targets
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1497
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1498
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
  1499
the expense of build speed, if necessary.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1500
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1501
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
  1502
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
  1503
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
  1504
product.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1505
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1506
#### Building Individual Modules
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1507
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1508
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
  1509
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
  1510
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
  1511
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
  1512
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
  1513
first.
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 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
  1516
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
  1517
jdk.crypto.ucrypto`
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1518
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1519
#### Building Individual Module Phases
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1520
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1521
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
  1522
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
  1523
and other artifact the module consists of. The phases are:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1524
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1525
  * `gensrc` (Generate source code to compile)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1526
  * `gendata` (Generate non-source code artifacts)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1527
  * `copy` (Copy resource artifacts)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1528
  * `java` (Compile Java code)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1529
  * `launchers` (Compile native executables)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1530
  * `libs` (Compile native libraries)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1531
  * `rmic` (Run the `rmic` tool)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1532
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1533
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
  1534
`$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
  1535
use `make java.base-gensrc`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1536
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1537
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
  1538
present). Make will build all needed prerequisites before building the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1539
requested phase.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1540
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1541
#### Skipping the Dependency Check
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1542
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1543
When using an iterative development style with frequent quick rebuilds, the
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1544
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
  1545
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
  1546
check in make.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1547
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1548
> **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
  1549
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1550
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
  1551
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
  1552
`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
  1553
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
  1554
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1555
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
  1556
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
  1557
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1558
#### Rebuilding Part of java.base (JDK\_FILTER)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1559
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1560
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
  1561
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
  1562
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
  1563
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1564
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
  1565
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
  1566
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
  1567
`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
  1568
to files in the `javax.crypto` package.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1569
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1570
### Learn About Mercurial
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1571
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1572
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
  1573
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
  1574
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1575
  * [Mercurial for git users](http://www.mercurial-scm.org/wiki/GitConcepts)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1576
  * [The official Mercurial tutorial](http://www.mercurial-scm.org/wiki/Tutorial)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1577
  * [hg init](http://hginit.com/)
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1578
  * [Mercurial: The Definitive Guide](http://hgbook.red-bean.com/read/)
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
## Understanding the Build System
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1581
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1582
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
  1583
build system.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1584
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1585
### Configurations
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1586
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1587
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
  1588
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
  1589
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
  1590
principle the configuration (directly or by files included by `spec.gmk`).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1591
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1592
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
  1593
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
  1594
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
  1595
used under the hood by the build system.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1596
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1597
### Build Output Structure
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1598
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1599
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
  1600
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
  1601
contains the following important directories:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1602
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1603
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1604
buildtools/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1605
configure-support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1606
hotspot/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1607
images/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1608
jdk/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1609
make-support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1610
support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1611
test-results/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1612
test-support/
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1613
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1614
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1615
This is what they are used for:
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
  * `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
  1618
    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
  1619
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1620
  * `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
  1621
    launch the newly built JDK by running `$BUILD/jdk/bin/java`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1622
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1623
  * `test-results`: This directory contains the results from running tests.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1624
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1625
  * `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
  1626
    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
  1627
    directories in `support` is `gensrc`, which contains the generated source
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1628
    code, and the `modules_*` directories, which contains the files in a
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1629
    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
  1630
    of the exploded image.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1631
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1632
  * `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
  1633
    that are used during the rest of the build.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1634
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1635
  * `hotspot`: This is an area for intermediate files needed when building
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1636
    hotspot.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1637
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1638
  * `configure-support`, `make-support` and `test-support`: These directories
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1639
    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
  1640
    and for running tests.
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
### Fixpath
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1643
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1644
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
  1645
`/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
  1646
mismatch when running on Windows.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1647
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1648
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
  1649
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
  1650
Windows paths.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1651
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1652
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
  1653
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
  1654
compiled automatically by `configure`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1655
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1656
### Native Debug Symbols
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1657
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1658
Native libraries and executables can have debug symbol (and other debug
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1659
information) associated with them. How this works is very much platform
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1660
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
  1661
disk space, but is rarely needed by the end user.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1662
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1663
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
  1664
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
  1665
are `none`, `internal`, `external`, `zipped`.
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
  * `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
  1668
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1669
  * `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
  1670
    they will be stored in the generated binary.
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
  * `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
  1673
    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
  1674
    (This was previously known as FDS, Full Debug Symbols).
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1675
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1676
  * `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
  1677
    into a `.diz` file.
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
When building for distribution, `zipped` is a good solution. Binaries built
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1680
with `internal` is suitable for use by developers, since they facilitate
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1681
debugging, but should be stripped before distributed to end users.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1682
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1683
### Autoconf Details
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1684
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1685
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
  1686
deviate from a normal autoconf `configure` script.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1687
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1688
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
  1689
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
  1690
to create the runnable (generated) configure script, as
ba52fa7bbf14 8195689: Remove generated-configure.sh and instead use autoconf
ihse
parents: 47928
diff changeset
  1691
`.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
  1692
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
  1693
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
  1694
part of this functionality, the generated script is called.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1695
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1696
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
  1697
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
  1698
manually request such an update by `bash configure autogen`.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1699
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1700
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
  1701
`make/autoconf/generated-configure.sh`. This is no longer the case.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1702
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1703
### Developing the Build System Itself
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1704
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1705
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
  1706
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
  1707
code.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1708
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1709
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
  1710
resemble most other Makefiles. Instead of listing specific targets and actions
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1711
(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
  1712
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
  1713
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
  1714
a call like this would be made:
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1715
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1716
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1717
$(eval $(call SetupJavaCompilation, BUILD_FOO_CLASSES, \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1718
    SETUP := GENERATE_OLDBYTECODE, \
47219
fd36993f7bf5 8187542: Remove superfluous *_TOPDIR variables
ihse
parents: 47217
diff changeset
  1719
    SRC := $(TOPDIR)/src/jkd.foo/share/classes, \
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1720
    INCLUDES := jdk/internal/foo, \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1721
    BIN := $(SUPPORT_OUTPUTDIR)/foo_classes, \
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1722
))
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1723
```
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1724
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1725
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
  1726
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
  1727
build a much more powerful and flexible build system.
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1728
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1729
Correct dependency tracking is paramount. Sloppy dependency tracking will lead
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1730
to improper parallelization, or worse, race conditions.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1731
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1732
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
  1733
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
  1734
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1735
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
  1736
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
  1737
builds you want to compare.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1738
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1739
To automatically build two consecutive versions and compare them, use
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1740
`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
  1741
assignments, like this:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1742
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1743
make COMPARE_BUILD=CONF=--enable-new-hotspot-feature:MAKE=hotspot
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1744
```
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1745
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
  1746
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1747
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
  1748
Use `JOBS=1` to avoid parallelism.
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
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
  1751
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
  1752
submitting patches.
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1753
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1754
## Contributing to the JDK
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1755
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1756
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
  1757
contribute it back to the OpenJDK Community.
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1758
50885
7c728fa9d1af 8205956: Fix usage of "OpenJDK" in build and test instructions
mr
parents: 50586
diff changeset
  1759
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
  1760
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
  1761
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
  1762
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1763
The official place to start is the ['How to contribute' page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1764
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
  1765
outdated and skimpy on details) [Developer's Guide](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1766
http://openjdk.java.net/guide/).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1767
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1768
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
  1769
good place to start is their ['New Contributor' page](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1770
https://wiki.openjdk.java.net/display/Adoption/New+Contributor), or start
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1771
reading the comprehensive [Getting Started Kit](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1772
https://adoptopenjdk.gitbooks.io/adoptopenjdk-getting-started-kit/en/). The
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1773
Adoption Group will also happily answer any questions you have about
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1774
contributing. Contact them by [mail](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1775
http://mail.openjdk.java.net/mailman/listinfo/adoption-discuss) or [IRC](
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1776
http://openjdk.java.net/irc/).
33030
de12d9a875ed 8139668: Generate README-build.html from markdown
ihse
parents:
diff changeset
  1777
45763
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1778
---
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1779
# 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
  1780
header-includes:
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1781
 - '<style type="text/css">pre, code, tt { color: #1d6ae5; }</style>'
2a2e56f4c03b 8179892: Update build documentation for JDK 9
ihse
parents: 44078
diff changeset
  1782
---