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