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