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