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