92 * Clone the JDK repository using the Cygwin command line `hg` client
93 as instructed in this document. That is, do *not* use another Mercurial
94 client such as TortoiseHg.
95
96 Failure to follow this procedure might result in hard-to-debug build
97 problems.
98
99 ## Build Hardware Requirements
100
101 The JDK is a massive project, and require machines ranging from decent to
102 powerful to be able to build in a reasonable amount of time, or to be able to
103 complete a build at all.
104
105 We *strongly* recommend usage of an SSD disk for the build, since disk speed is
106 one of the limiting factors for build performance.
107
108 ### Building on x86
109
110 At a minimum, a machine with 2-4 cores is advisable, as well as 2-4 GB of RAM.
111 (The more cores to use, the more memory you need.) At least 6 GB of free disk
112 space is required (8 GB minimum for building on Solaris).
113
114 Even for 32-bit builds, it is recommended to use a 64-bit build machine, and
115 instead create a 32-bit target using `--with-target-bits=32`.
116
117 ### Building on sparc
118
119 At a minimum, a machine with 4 cores is advisable, as well as 4 GB of RAM. (The
120 more cores to use, the more memory you need.) At least 8 GB of free disk space
121 is required.
122
123 Note: The sparc port is deprecated.
124
125 ### Building on aarch64
126
127 At a minimum, a machine with 8 cores is advisable, as well as 8 GB of RAM.
128 (The more cores to use, the more memory you need.) At least 6 GB of free disk
129 space is required.
130
131 If you do not have access to sufficiently powerful hardware, it is also
132 possible to use [cross-compiling](#cross-compiling).
133
134 ### Building on 32-bit arm
135
136 This is not recommended. Instead, see the section on [Cross-compiling](
137 #cross-compiling).
138
139 ## Operating System Requirements
140
141 The mainline JDK project supports Linux, Solaris, macOS, AIX and Windows.
142 Support for other operating system, e.g. BSD, exists in separate "port"
143 projects.
144
145 In general, the JDK can be built on a wide range of versions of these operating
146 systems, but the further you deviate from what is tested on a daily basis, the
147 more likely you are to run into problems.
148
149 This table lists the OS versions used by Oracle when building the JDK. Such
150 information is always subject to change, but this table is up to date at the
151 time of writing.
152
153 Operating system Vendor/version used
154 ----------------- -------------------------------------------------------
155 Linux Oracle Enterprise Linux 6.4 / 7.6
156 Solaris Solaris 11.3 SRU 20
157 macOS Mac OS X 10.13 (High Sierra)
158 Windows Windows Server 2012 R2
159
160 The double version numbers for Linux and Solaris are due to the hybrid model
161 used at Oracle, where header files and external libraries from an older version
162 are used when building on a more modern version of the OS.
163
164 The Build Group has a wiki page with [Supported Build Platforms](
165 https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms). From
166 time to time, this is updated by contributors to list successes or failures of
167 building on different platforms.
168
169 ### Windows
170
171 Windows XP is not a supported platform, but all newer Windows should be able to
172 build the JDK.
173
174 On Windows, it is important that you pay attention to the instructions in the
175 [Special Considerations](#special-considerations).
176
177 Windows is the only non-POSIX OS supported by the JDK, and as such, requires
178 some extra care. A POSIX support layer is required to build on Windows.
179 Currently, the only supported such layers are Cygwin and Windows Subsystem for
180 Linux (WSL). (Msys is no longer supported due to a too old bash; msys2 would
230 work but intermittent build failures have been observed.
231
232 It's possible to build both Windows and Linux binaries from WSL. To build
233 Windows binaries, you must use a Windows boot JDK (located in a
234 Windows-accessible directory). To build Linux binaries, you must use a Linux
235 boot JDK. The default behavior is to build for Windows. To build for Linux, pass
236 `--build=x86_64-unknown-linux-gnu --host=x86_64-unknown-linux-gnu` to
237 `configure`.
238
239 If building Windows binaries, the source code must be located in a Windows-
240 accessible directory. This is because Windows executables (such as Visual Studio
241 and the boot JDK) must be able to access the source code. Also, the drive where
242 the source is stored must be mounted as case-insensitive by changing either
243 /etc/fstab or /etc/wsl.conf in WSL. Individual directories may be corrected
244 using the fsutil tool in case the source was cloned before changing the mount
245 options.
246
247 Note that while it's possible to build on WSL, testing is still not fully
248 supported.
249
250 ### Solaris
251
252 See `make/devkit/solaris11.1-package-list.txt` for a list of recommended
253 packages to install when building on Solaris. The versions specified in this
254 list is the versions used by the daily builds at Oracle, and is likely to work
255 properly.
256
257 Older versions of Solaris shipped a broken version of `objcopy`. At least
258 version 2.21.1 is needed, which is provided by Solaris 11 Update 1. Objcopy is
259 needed if you want to have external debug symbols. Please make sure you are
260 using at least version 2.21.1 of objcopy, or that you disable external debug
261 symbols.
262
263 Note: The Solaris port is deprecated.
264
265 ### macOS
266
267 Apple is using a quite aggressive scheme of pushing OS updates, and coupling
268 these updates with required updates of Xcode. Unfortunately, this makes it
269 difficult for a project such as the JDK to keep pace with a continuously updated
270 machine running macOS. See the section on [Apple Xcode](#apple-xcode) on some
271 strategies to deal with this.
272
273 It is recommended that you use at least Mac OS X 10.13 (High Sierra). At the time
274 of writing, the JDK has been successfully compiled on macOS 10.12 (Sierra).
275
276 The standard macOS environment contains the basic tooling needed to build, but
277 for external libraries a package manager is recommended. The JDK uses
278 [homebrew](https://brew.sh/) in the examples, but feel free to use whatever
279 manager you want (or none).
280
281 ### Linux
282
283 It is often not much problem to build the JDK on Linux. The only general advice
284 is to try to use the compilers, external libraries and header files as provided
297 sudo yum groupinstall "Development Tools"
298 ```
299
300 ### AIX
301
302 Please consult the AIX section of the [Supported Build Platforms](
303 https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms) OpenJDK
304 Build Wiki page for details about which versions of AIX are supported.
305
306 ## Native Compiler (Toolchain) Requirements
307
308 Large portions of the JDK consists of native code, that needs to be compiled to
309 be able to run on the target platform. In theory, toolchain and operating
310 system should be independent factors, but in practice there's more or less a
311 one-to-one correlation between target operating system and toolchain.
312
313 Operating system Supported toolchain
314 ------------------ -------------------------
315 Linux gcc, clang
316 macOS Apple Xcode (using clang)
317 Solaris Oracle Solaris Studio
318 AIX IBM XL C/C++
319 Windows Microsoft Visual Studio
320
321 Please see the individual sections on the toolchains for version
322 recommendations. As a reference, these versions of the toolchains are used, at
323 the time of writing, by Oracle for the daily builds of the JDK. It should be
324 possible to compile the JDK with both older and newer versions, but the closer
325 you stay to this list, the more likely you are to compile successfully without
326 issues.
327
328 Operating system Toolchain version
329 ------------------ -------------------------------------------------------
330 Linux gcc 9.2.0
331 macOS Apple Xcode 10.1 (using clang 10.0.0)
332 Solaris Oracle Solaris Studio 12.6 (with compiler version 5.15)
333 Windows Microsoft Visual Studio 2019 update 16.5.3
334
335 All compilers are expected to be able to compile to the C99 language standard,
336 as some C99 features are used in the source code. Microsoft Visual Studio
337 doesn't fully support C99 so in practice shared code is limited to using C99
338 features that it does support.
339
340 ### gcc
341
342 The minimum accepted version of gcc is 5.0. Older versions will generate a warning
343 by `configure` and are unlikely to work.
344
345 The JDK is currently known to be able to compile with at least version 9.2 of
346 gcc.
347
348 In general, any version between these two should be usable.
349
350 ### clang
351
352 The minimum accepted version of clang is 3.2. Older versions will not be
362 the JDK. (Actually, *only* the command lines tools are needed, not the IDE.)
363 The simplest way to install these is to run:
364 ```
365 xcode-select --install
366 ```
367
368 It is advisable to keep an older version of Xcode for building the JDK when
369 updating Xcode. This [blog page](
370 http://iosdevelopertips.com/xcode/install-multiple-versions-of-xcode.html) has
371 good suggestions on managing multiple Xcode versions. To use a specific version
372 of Xcode, use `xcode-select -s` before running `configure`, or use
373 `--with-toolchain-path` to point to the version of Xcode to use, e.g.
374 `configure --with-toolchain-path=/Applications/Xcode8.app/Contents/Developer/usr/bin`
375
376 If you have recently (inadvertently) updated your OS and/or Xcode version, and
377 the JDK can no longer be built, please see the section on [Problems with the
378 Build Environment](#problems-with-the-build-environment), and [Getting
379 Help](#getting-help) to find out if there are any recent, non-merged patches
380 available for this update.
381
382 ### Oracle Solaris Studio
383
384 The minimum accepted version of the Solaris Studio compilers is 5.13
385 (corresponding to Solaris Studio 12.4). Older versions will not be accepted by
386 configure.
387
388 The Solaris Studio installation should contain at least these packages:
389
390 Package Version
391 -------------------------------------------------- -------------
392 developer/solarisstudio-124/backend 12.4-1.0.6.0
393 developer/solarisstudio-124/c++ 12.4-1.0.10.0
394 developer/solarisstudio-124/cc 12.4-1.0.4.0
395 developer/solarisstudio-124/library/c++-libs 12.4-1.0.10.0
396 developer/solarisstudio-124/library/math-libs 12.4-1.0.0.1
397 developer/solarisstudio-124/library/studio-gccrt 12.4-1.0.0.1
398 developer/solarisstudio-124/studio-common 12.4-1.0.0.1
399 developer/solarisstudio-124/studio-ja 12.4-1.0.0.1
400 developer/solarisstudio-124/studio-legal 12.4-1.0.0.1
401 developer/solarisstudio-124/studio-zhCN 12.4-1.0.0.1
402
403 Compiling with Solaris Studio can sometimes be finicky. This is the exact
404 version used by Oracle, which worked correctly at the time of writing:
405 ```
406 $ cc -V
407 cc: Sun C 5.13 SunOS_i386 2014/10/20
408 $ CC -V
409 CC: Sun C++ 5.13 SunOS_i386 151846-10 2015/10/30
410 ```
411
412 ### Microsoft Visual Studio
413
414 The minimum accepted version of Visual Studio is 2010. Older versions will not
415 be accepted by `configure`. The maximum accepted version of Visual Studio is
416 2019. Versions older than 2017 are unlikely to continue working for long.
417
418 If you have multiple versions of Visual Studio installed, `configure` will by
419 default pick the latest. You can request a specific version to be used by
420 setting `--with-toolchain-version`, e.g. `--with-toolchain-version=2015`.
421
422 If you get `LINK: fatal error LNK1123: failure during conversion to COFF: file
423 invalid` when building using Visual Studio 2010, you have encountered
424 [KB2757355](http://support.microsoft.com/kb/2757355), a bug triggered by a
425 specific installation order. However, the solution suggested by the KB article
426 does not always resolve the problem. See [this stackoverflow discussion](
427 https://stackoverflow.com/questions/10888391) for other suggestions.
428
429 ### IBM XL C/C++
430
431 Please consult the AIX section of the [Supported Build Platforms](
477 path to it. There are two forms of the `configure` arguments to point to an
478 external library: `--with-<LIB>=<path>` or `--with-<LIB>-include=<path to
479 include> --with-<LIB>-lib=<path to lib>`. The first variant is more concise,
480 but require the include files and library files to reside in a default
481 hierarchy under this directory. In most cases, it works fine.
482
483 As a fallback, the second version allows you to point to the include directory
484 and the lib directory separately.
485
486 ### FreeType
487
488 FreeType2 from [The FreeType Project](http://www.freetype.org/) is not required
489 on any platform. The exception is on Unix-based platforms when configuring such
490 that the build artifacts will reference a system installed library,
491 rather than bundling the JDK's own copy.
492
493 * To install on an apt-based Linux, try running `sudo apt-get install
494 libfreetype6-dev`.
495 * To install on an rpm-based Linux, try running `sudo yum install
496 freetype-devel`.
497 * To install on Solaris, try running `pkg install system/library/freetype-2`.
498
499 Use `--with-freetype-include=<path>` and `--with-freetype-lib=<path>`
500 if `configure` does not automatically locate the platform FreeType files.
501
502 ### CUPS
503
504 CUPS, [Common UNIX Printing System](http://www.cups.org) header files are
505 required on all platforms, except Windows. Often these files are provided by
506 your operating system.
507
508 * To install on an apt-based Linux, try running `sudo apt-get install
509 libcups2-dev`.
510 * To install on an rpm-based Linux, try running `sudo yum install
511 cups-devel`.
512 * To install on Solaris, try running `pkg install print/cups`.
513
514 Use `--with-cups=<path>` if `configure` does not properly locate your CUPS
515 files.
516
517 ### X11
518
519 Certain [X11](http://www.x.org/) libraries and include files are required on
520 Linux and Solaris.
521
522 * To install on an apt-based Linux, try running `sudo apt-get install
523 libx11-dev libxext-dev libxrender-dev libxrandr-dev libxtst-dev libxt-dev`.
524 * To install on an rpm-based Linux, try running `sudo yum install
525 libXtst-devel libXt-devel libXrender-devel libXrandr-devel libXi-devel`.
526 * To install on Solaris, try running `pkg install x11/header/x11-protocols
527 x11/library/libice x11/library/libpthread-stubs x11/library/libsm
528 x11/library/libx11 x11/library/libxau x11/library/libxcb
529 x11/library/libxdmcp x11/library/libxevie x11/library/libxext
530 x11/library/libxrender x11/library/libxrandr x11/library/libxscrnsaver
531 x11/library/libxtst x11/library/toolkit/libxt`.
532
533 Use `--with-x=<path>` if `configure` does not properly locate your X11 files.
534
535 ### ALSA
536
537 ALSA, [Advanced Linux Sound Architecture](https://www.alsa-project.org/) is
538 required on Linux. At least version 0.9.1 of ALSA is required.
539
540 * To install on an apt-based Linux, try running `sudo apt-get install
541 libasound2-dev`.
542 * To install on an rpm-based Linux, try running `sudo yum install
543 alsa-lib-devel`.
544
545 Use `--with-alsa=<path>` if `configure` does not properly locate your ALSA
546 files.
547
548 ### libffi
549
550 libffi, the [Portable Foreign Function Interface Library](
551 http://sourceware.org/libffi) is required when building the Zero version of
586 The JDK requires [GNU Make](http://www.gnu.org/software/make). No other flavors
587 of make are supported.
588
589 At least version 3.81 of GNU Make must be used. For distributions supporting
590 GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful
591 functionality to handle parallel building (supported by `--with-output-sync`)
592 and speed and stability improvements.
593
594 Note that `configure` locates and verifies a properly functioning version of
595 `make` and stores the path to this `make` binary in the configuration. If you
596 start a build using `make` on the command line, you will be using the version
597 of make found first in your `PATH`, and not necessarily the one stored in the
598 configuration. This initial make will be used as "bootstrap make", and in a
599 second stage, the make located by `configure` will be called. Normally, this
600 will present no issues, but if you have a very old `make`, or a non-GNU Make
601 `make` in your path, this might cause issues.
602
603 If you want to override the default make found by `configure`, use the `MAKE`
604 configure variable, e.g. `configure MAKE=/opt/gnu/make`.
605
606 On Solaris, it is common to call the GNU version of make by using `gmake`.
607
608 ### GNU Bash
609
610 The JDK requires [GNU Bash](http://www.gnu.org/software/bash). No other shells
611 are supported.
612
613 At least version 3.2 of GNU Bash must be used.
614
615 ## Running Configure
616
617 To build the JDK, you need a "configuration", which consists of a directory
618 where to store the build output, coupled with information about the platform,
619 the specific build machine, and choices that affect how the JDK is built.
620
621 The configuration is created by the `configure` script. The basic invocation of
622 the `configure` script looks like this:
623
624 ```
625 bash configure [options]
626 ```
627
1443 ### Specific Build Issues
1444
1445 #### Clock Skew
1446
1447 If you get an error message like this:
1448 ```
1449 File 'xxx' has modification time in the future.
1450 Clock skew detected. Your build may be incomplete.
1451 ```
1452 then the clock on your build machine is out of sync with the timestamps on the
1453 source files. Other errors, apparently unrelated but in fact caused by the
1454 clock skew, can occur along with the clock skew warnings. These secondary
1455 errors may tend to obscure the fact that the true root cause of the problem is
1456 an out-of-sync clock.
1457
1458 If you see these warnings, reset the clock on the build machine, run `make
1459 clean` and restart the build.
1460
1461 #### Out of Memory Errors
1462
1463 On Solaris, you might get an error message like this:
1464 ```
1465 Trouble writing out table to disk
1466 ```
1467 To solve this, increase the amount of swap space on your build machine.
1468
1469 On Windows, you might get error messages like this:
1470 ```
1471 fatal error - couldn't allocate heap
1472 cannot create ... Permission denied
1473 spawn failed
1474 ```
1475 This can be a sign of a Cygwin problem. See the information about solving
1476 problems in the [Cygwin](#cygwin) section. Rebooting the computer might help
1477 temporarily.
1478
1479 ### Getting Help
1480
1481 If none of the suggestions in this document helps you, or if you find what you
1482 believe is a bug in the build system, please contact the Build Group by sending
1483 a mail to [build-dev@openjdk.java.net](mailto:build-dev@openjdk.java.net).
1484 Please include the relevant parts of the configure and/or build log.
1485
1486 If you need general help or advice about developing for the JDK, you can also
1487 contact the Adoption Group. See the section on [Contributing to OpenJDK](
1488 #contributing-to-openjdk) for more information.
1587 ### Using Fine-Grained Make Targets
1588
1589 The default behavior for make is to create consistent and correct output, at
1590 the expense of build speed, if necessary.
1591
1592 If you are prepared to take some risk of an incorrect build, and know enough of
1593 the system to understand how things build and interact, you can speed up the
1594 build process considerably by instructing make to only build a portion of the
1595 product.
1596
1597 #### Building Individual Modules
1598
1599 The safe way to use fine-grained make targets is to use the module specific
1600 make targets. All source code in the JDK is organized so it belongs to a
1601 module, e.g. `java.base` or `jdk.jdwp.agent`. You can build only a specific
1602 module, by giving it as make target: `make jdk.jdwp.agent`. If the specified
1603 module depends on other modules (e.g. `java.base`), those modules will be built
1604 first.
1605
1606 You can also specify a set of modules, just as you can always specify a set of
1607 make targets: `make jdk.crypto.cryptoki jdk.crypto.ec jdk.crypto.mscapi
1608 jdk.crypto.ucrypto`
1609
1610 #### Building Individual Module Phases
1611
1612 The build process for each module is divided into separate phases. Not all
1613 modules need all phases. Which are needed depends on what kind of source code
1614 and other artifact the module consists of. The phases are:
1615
1616 * `gensrc` (Generate source code to compile)
1617 * `gendata` (Generate non-source code artifacts)
1618 * `copy` (Copy resource artifacts)
1619 * `java` (Compile Java code)
1620 * `launchers` (Compile native executables)
1621 * `libs` (Compile native libraries)
1622
1623 You can build only a single phase for a module by using the notation
1624 `$MODULE-$PHASE`. For instance, to build the `gensrc` phase for `java.base`,
1625 use `make java.base-gensrc`.
1626
1627 Note that some phases may depend on others, e.g. `java` depends on `gensrc` (if
1628 present). Make will build all needed prerequisites before building the
|
92 * Clone the JDK repository using the Cygwin command line `hg` client
93 as instructed in this document. That is, do *not* use another Mercurial
94 client such as TortoiseHg.
95
96 Failure to follow this procedure might result in hard-to-debug build
97 problems.
98
99 ## Build Hardware Requirements
100
101 The JDK is a massive project, and require machines ranging from decent to
102 powerful to be able to build in a reasonable amount of time, or to be able to
103 complete a build at all.
104
105 We *strongly* recommend usage of an SSD disk for the build, since disk speed is
106 one of the limiting factors for build performance.
107
108 ### Building on x86
109
110 At a minimum, a machine with 2-4 cores is advisable, as well as 2-4 GB of RAM.
111 (The more cores to use, the more memory you need.) At least 6 GB of free disk
112 space is required.
113
114 Even for 32-bit builds, it is recommended to use a 64-bit build machine, and
115 instead create a 32-bit target using `--with-target-bits=32`.
116
117 ### Building on aarch64
118
119 At a minimum, a machine with 8 cores is advisable, as well as 8 GB of RAM.
120 (The more cores to use, the more memory you need.) At least 6 GB of free disk
121 space is required.
122
123 If you do not have access to sufficiently powerful hardware, it is also
124 possible to use [cross-compiling](#cross-compiling).
125
126 ### Building on 32-bit arm
127
128 This is not recommended. Instead, see the section on [Cross-compiling](
129 #cross-compiling).
130
131 ## Operating System Requirements
132
133 The mainline JDK project supports Linux, macOS, AIX and Windows.
134 Support for other operating system, e.g. BSD, exists in separate "port"
135 projects.
136
137 In general, the JDK can be built on a wide range of versions of these operating
138 systems, but the further you deviate from what is tested on a daily basis, the
139 more likely you are to run into problems.
140
141 This table lists the OS versions used by Oracle when building the JDK. Such
142 information is always subject to change, but this table is up to date at the
143 time of writing.
144
145 Operating system Vendor/version used
146 ----------------- -------------------------------------------------------
147 Linux Oracle Enterprise Linux 6.4 / 7.6
148 macOS Mac OS X 10.13 (High Sierra)
149 Windows Windows Server 2012 R2
150
151 The double version numbers for Linux are due to the hybrid model
152 used at Oracle, where header files and external libraries from an older version
153 are used when building on a more modern version of the OS.
154
155 The Build Group has a wiki page with [Supported Build Platforms](
156 https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms). From
157 time to time, this is updated by contributors to list successes or failures of
158 building on different platforms.
159
160 ### Windows
161
162 Windows XP is not a supported platform, but all newer Windows should be able to
163 build the JDK.
164
165 On Windows, it is important that you pay attention to the instructions in the
166 [Special Considerations](#special-considerations).
167
168 Windows is the only non-POSIX OS supported by the JDK, and as such, requires
169 some extra care. A POSIX support layer is required to build on Windows.
170 Currently, the only supported such layers are Cygwin and Windows Subsystem for
171 Linux (WSL). (Msys is no longer supported due to a too old bash; msys2 would
221 work but intermittent build failures have been observed.
222
223 It's possible to build both Windows and Linux binaries from WSL. To build
224 Windows binaries, you must use a Windows boot JDK (located in a
225 Windows-accessible directory). To build Linux binaries, you must use a Linux
226 boot JDK. The default behavior is to build for Windows. To build for Linux, pass
227 `--build=x86_64-unknown-linux-gnu --host=x86_64-unknown-linux-gnu` to
228 `configure`.
229
230 If building Windows binaries, the source code must be located in a Windows-
231 accessible directory. This is because Windows executables (such as Visual Studio
232 and the boot JDK) must be able to access the source code. Also, the drive where
233 the source is stored must be mounted as case-insensitive by changing either
234 /etc/fstab or /etc/wsl.conf in WSL. Individual directories may be corrected
235 using the fsutil tool in case the source was cloned before changing the mount
236 options.
237
238 Note that while it's possible to build on WSL, testing is still not fully
239 supported.
240
241 ### macOS
242
243 Apple is using a quite aggressive scheme of pushing OS updates, and coupling
244 these updates with required updates of Xcode. Unfortunately, this makes it
245 difficult for a project such as the JDK to keep pace with a continuously updated
246 machine running macOS. See the section on [Apple Xcode](#apple-xcode) on some
247 strategies to deal with this.
248
249 It is recommended that you use at least Mac OS X 10.13 (High Sierra). At the time
250 of writing, the JDK has been successfully compiled on macOS 10.12 (Sierra).
251
252 The standard macOS environment contains the basic tooling needed to build, but
253 for external libraries a package manager is recommended. The JDK uses
254 [homebrew](https://brew.sh/) in the examples, but feel free to use whatever
255 manager you want (or none).
256
257 ### Linux
258
259 It is often not much problem to build the JDK on Linux. The only general advice
260 is to try to use the compilers, external libraries and header files as provided
273 sudo yum groupinstall "Development Tools"
274 ```
275
276 ### AIX
277
278 Please consult the AIX section of the [Supported Build Platforms](
279 https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms) OpenJDK
280 Build Wiki page for details about which versions of AIX are supported.
281
282 ## Native Compiler (Toolchain) Requirements
283
284 Large portions of the JDK consists of native code, that needs to be compiled to
285 be able to run on the target platform. In theory, toolchain and operating
286 system should be independent factors, but in practice there's more or less a
287 one-to-one correlation between target operating system and toolchain.
288
289 Operating system Supported toolchain
290 ------------------ -------------------------
291 Linux gcc, clang
292 macOS Apple Xcode (using clang)
293 AIX IBM XL C/C++
294 Windows Microsoft Visual Studio
295
296 Please see the individual sections on the toolchains for version
297 recommendations. As a reference, these versions of the toolchains are used, at
298 the time of writing, by Oracle for the daily builds of the JDK. It should be
299 possible to compile the JDK with both older and newer versions, but the closer
300 you stay to this list, the more likely you are to compile successfully without
301 issues.
302
303 Operating system Toolchain version
304 ------------------ -------------------------------------------------------
305 Linux gcc 9.2.0
306 macOS Apple Xcode 10.1 (using clang 10.0.0)
307 Windows Microsoft Visual Studio 2019 update 16.5.3
308
309 All compilers are expected to be able to compile to the C99 language standard,
310 as some C99 features are used in the source code. Microsoft Visual Studio
311 doesn't fully support C99 so in practice shared code is limited to using C99
312 features that it does support.
313
314 ### gcc
315
316 The minimum accepted version of gcc is 5.0. Older versions will generate a warning
317 by `configure` and are unlikely to work.
318
319 The JDK is currently known to be able to compile with at least version 9.2 of
320 gcc.
321
322 In general, any version between these two should be usable.
323
324 ### clang
325
326 The minimum accepted version of clang is 3.2. Older versions will not be
336 the JDK. (Actually, *only* the command lines tools are needed, not the IDE.)
337 The simplest way to install these is to run:
338 ```
339 xcode-select --install
340 ```
341
342 It is advisable to keep an older version of Xcode for building the JDK when
343 updating Xcode. This [blog page](
344 http://iosdevelopertips.com/xcode/install-multiple-versions-of-xcode.html) has
345 good suggestions on managing multiple Xcode versions. To use a specific version
346 of Xcode, use `xcode-select -s` before running `configure`, or use
347 `--with-toolchain-path` to point to the version of Xcode to use, e.g.
348 `configure --with-toolchain-path=/Applications/Xcode8.app/Contents/Developer/usr/bin`
349
350 If you have recently (inadvertently) updated your OS and/or Xcode version, and
351 the JDK can no longer be built, please see the section on [Problems with the
352 Build Environment](#problems-with-the-build-environment), and [Getting
353 Help](#getting-help) to find out if there are any recent, non-merged patches
354 available for this update.
355
356 ### Microsoft Visual Studio
357
358 The minimum accepted version of Visual Studio is 2010. Older versions will not
359 be accepted by `configure`. The maximum accepted version of Visual Studio is
360 2019. Versions older than 2017 are unlikely to continue working for long.
361
362 If you have multiple versions of Visual Studio installed, `configure` will by
363 default pick the latest. You can request a specific version to be used by
364 setting `--with-toolchain-version`, e.g. `--with-toolchain-version=2015`.
365
366 If you get `LINK: fatal error LNK1123: failure during conversion to COFF: file
367 invalid` when building using Visual Studio 2010, you have encountered
368 [KB2757355](http://support.microsoft.com/kb/2757355), a bug triggered by a
369 specific installation order. However, the solution suggested by the KB article
370 does not always resolve the problem. See [this stackoverflow discussion](
371 https://stackoverflow.com/questions/10888391) for other suggestions.
372
373 ### IBM XL C/C++
374
375 Please consult the AIX section of the [Supported Build Platforms](
421 path to it. There are two forms of the `configure` arguments to point to an
422 external library: `--with-<LIB>=<path>` or `--with-<LIB>-include=<path to
423 include> --with-<LIB>-lib=<path to lib>`. The first variant is more concise,
424 but require the include files and library files to reside in a default
425 hierarchy under this directory. In most cases, it works fine.
426
427 As a fallback, the second version allows you to point to the include directory
428 and the lib directory separately.
429
430 ### FreeType
431
432 FreeType2 from [The FreeType Project](http://www.freetype.org/) is not required
433 on any platform. The exception is on Unix-based platforms when configuring such
434 that the build artifacts will reference a system installed library,
435 rather than bundling the JDK's own copy.
436
437 * To install on an apt-based Linux, try running `sudo apt-get install
438 libfreetype6-dev`.
439 * To install on an rpm-based Linux, try running `sudo yum install
440 freetype-devel`.
441
442 Use `--with-freetype-include=<path>` and `--with-freetype-lib=<path>`
443 if `configure` does not automatically locate the platform FreeType files.
444
445 ### CUPS
446
447 CUPS, [Common UNIX Printing System](http://www.cups.org) header files are
448 required on all platforms, except Windows. Often these files are provided by
449 your operating system.
450
451 * To install on an apt-based Linux, try running `sudo apt-get install
452 libcups2-dev`.
453 * To install on an rpm-based Linux, try running `sudo yum install
454 cups-devel`.
455
456 Use `--with-cups=<path>` if `configure` does not properly locate your CUPS
457 files.
458
459 ### X11
460
461 Certain [X11](http://www.x.org/) libraries and include files are required on
462 Linux.
463
464 * To install on an apt-based Linux, try running `sudo apt-get install
465 libx11-dev libxext-dev libxrender-dev libxrandr-dev libxtst-dev libxt-dev`.
466 * To install on an rpm-based Linux, try running `sudo yum install
467 libXtst-devel libXt-devel libXrender-devel libXrandr-devel libXi-devel`.
468
469 Use `--with-x=<path>` if `configure` does not properly locate your X11 files.
470
471 ### ALSA
472
473 ALSA, [Advanced Linux Sound Architecture](https://www.alsa-project.org/) is
474 required on Linux. At least version 0.9.1 of ALSA is required.
475
476 * To install on an apt-based Linux, try running `sudo apt-get install
477 libasound2-dev`.
478 * To install on an rpm-based Linux, try running `sudo yum install
479 alsa-lib-devel`.
480
481 Use `--with-alsa=<path>` if `configure` does not properly locate your ALSA
482 files.
483
484 ### libffi
485
486 libffi, the [Portable Foreign Function Interface Library](
487 http://sourceware.org/libffi) is required when building the Zero version of
522 The JDK requires [GNU Make](http://www.gnu.org/software/make). No other flavors
523 of make are supported.
524
525 At least version 3.81 of GNU Make must be used. For distributions supporting
526 GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful
527 functionality to handle parallel building (supported by `--with-output-sync`)
528 and speed and stability improvements.
529
530 Note that `configure` locates and verifies a properly functioning version of
531 `make` and stores the path to this `make` binary in the configuration. If you
532 start a build using `make` on the command line, you will be using the version
533 of make found first in your `PATH`, and not necessarily the one stored in the
534 configuration. This initial make will be used as "bootstrap make", and in a
535 second stage, the make located by `configure` will be called. Normally, this
536 will present no issues, but if you have a very old `make`, or a non-GNU Make
537 `make` in your path, this might cause issues.
538
539 If you want to override the default make found by `configure`, use the `MAKE`
540 configure variable, e.g. `configure MAKE=/opt/gnu/make`.
541
542 ### GNU Bash
543
544 The JDK requires [GNU Bash](http://www.gnu.org/software/bash). No other shells
545 are supported.
546
547 At least version 3.2 of GNU Bash must be used.
548
549 ## Running Configure
550
551 To build the JDK, you need a "configuration", which consists of a directory
552 where to store the build output, coupled with information about the platform,
553 the specific build machine, and choices that affect how the JDK is built.
554
555 The configuration is created by the `configure` script. The basic invocation of
556 the `configure` script looks like this:
557
558 ```
559 bash configure [options]
560 ```
561
1377 ### Specific Build Issues
1378
1379 #### Clock Skew
1380
1381 If you get an error message like this:
1382 ```
1383 File 'xxx' has modification time in the future.
1384 Clock skew detected. Your build may be incomplete.
1385 ```
1386 then the clock on your build machine is out of sync with the timestamps on the
1387 source files. Other errors, apparently unrelated but in fact caused by the
1388 clock skew, can occur along with the clock skew warnings. These secondary
1389 errors may tend to obscure the fact that the true root cause of the problem is
1390 an out-of-sync clock.
1391
1392 If you see these warnings, reset the clock on the build machine, run `make
1393 clean` and restart the build.
1394
1395 #### Out of Memory Errors
1396
1397 On Windows, you might get error messages like this:
1398 ```
1399 fatal error - couldn't allocate heap
1400 cannot create ... Permission denied
1401 spawn failed
1402 ```
1403 This can be a sign of a Cygwin problem. See the information about solving
1404 problems in the [Cygwin](#cygwin) section. Rebooting the computer might help
1405 temporarily.
1406
1407 ### Getting Help
1408
1409 If none of the suggestions in this document helps you, or if you find what you
1410 believe is a bug in the build system, please contact the Build Group by sending
1411 a mail to [build-dev@openjdk.java.net](mailto:build-dev@openjdk.java.net).
1412 Please include the relevant parts of the configure and/or build log.
1413
1414 If you need general help or advice about developing for the JDK, you can also
1415 contact the Adoption Group. See the section on [Contributing to OpenJDK](
1416 #contributing-to-openjdk) for more information.
1515 ### Using Fine-Grained Make Targets
1516
1517 The default behavior for make is to create consistent and correct output, at
1518 the expense of build speed, if necessary.
1519
1520 If you are prepared to take some risk of an incorrect build, and know enough of
1521 the system to understand how things build and interact, you can speed up the
1522 build process considerably by instructing make to only build a portion of the
1523 product.
1524
1525 #### Building Individual Modules
1526
1527 The safe way to use fine-grained make targets is to use the module specific
1528 make targets. All source code in the JDK is organized so it belongs to a
1529 module, e.g. `java.base` or `jdk.jdwp.agent`. You can build only a specific
1530 module, by giving it as make target: `make jdk.jdwp.agent`. If the specified
1531 module depends on other modules (e.g. `java.base`), those modules will be built
1532 first.
1533
1534 You can also specify a set of modules, just as you can always specify a set of
1535 make targets: `make jdk.crypto.cryptoki jdk.crypto.ec jdk.crypto.mscapi`
1536
1537 #### Building Individual Module Phases
1538
1539 The build process for each module is divided into separate phases. Not all
1540 modules need all phases. Which are needed depends on what kind of source code
1541 and other artifact the module consists of. The phases are:
1542
1543 * `gensrc` (Generate source code to compile)
1544 * `gendata` (Generate non-source code artifacts)
1545 * `copy` (Copy resource artifacts)
1546 * `java` (Compile Java code)
1547 * `launchers` (Compile native executables)
1548 * `libs` (Compile native libraries)
1549
1550 You can build only a single phase for a module by using the notation
1551 `$MODULE-$PHASE`. For instance, to build the `gensrc` phase for `java.base`,
1552 use `make java.base-gensrc`.
1553
1554 Note that some phases may depend on others, e.g. `java` depends on `gensrc` (if
1555 present). Make will build all needed prerequisites before building the
|