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