At a minimum, a machine with 8 cores is advisable, as well as 8 GB of RAM. (The more cores to use, the more memory you need.) At least 6 GB of free disk space is required.
If you do not have access to sufficiently powerful hardware, it is also possible to use cross-compiling.
+In order to use Branch Protection features in the VM, --enable-branch-protection must be used. This option requires C++ compiler support (GCC 9.1.0+ or Clang 10+). The resulting build can be run on both machines with and without support for branch protection in hardware. Branch Protection is only supported for Linux targets.
This is not recommended. Instead, see the section on Cross-compiling.
Windows XP is not a supported platform, but all newer Windows should be able to build the JDK.
On Windows, it is important that you pay attention to the instructions in the Special Considerations.
-Windows is the only non-POSIX OS supported by the JDK, and as such, requires some extra care. A POSIX support layer is required to build on Windows. Currently, the only supported such layers are Cygwin and Windows Subsystem for Linux (WSL). (Msys is no longer supported due to a too old bash; msys2 would likely be possible to support in a future version but that would require effort to implement.)
+Windows is the only non-POSIX OS supported by the JDK, and as such, requires some extra care. A POSIX support layer is required to build on Windows. Currently, the only supported such layers are Cygwin, Windows Subsystem for Linux (WSL), and MSYS2. (MSYS is no longer supported due to an outdated bash; While OpenJDK can be built with MSYS2, support for it is still experimental, so build failures and unusual errors are not uncommon.)
Internally in the build system, all paths are represented as Unix-style paths, e.g. /cygdrive/c/git/jdk/Makefile rather than C:\git\jdk\Makefile. This rule also applies to input to the build system, e.g. in arguments to configure. So, use --with-msvcr-dll=/cygdrive/c/msvcr100.dll rather than --with-msvcr-dll=c:\msvcr100.dll. For details on this conversion, see the section on Fixpath.
A functioning Cygwin environment is required for building the JDK on Windows. If you have a 64-bit OS, we strongly recommend using the 64-bit version of Cygwin.
@@ -214,7 +216,7 @@Unfortunately, Cygwin can be unreliable in certain circumstances. If you experience build tool crashes or strange issues when building on Windows, please check the Cygwin FAQ on the "BLODA" list and the section on fork() failures.
Windows 10 1809 or newer is supported due to a dependency on the wslpath utility and support for environment variable sharing through WSLENV. Version 1803 can work but intermittent build failures have been observed.
-It's possible to build both Windows and Linux binaries from WSL. To build Windows binaries, you must use a Windows boot JDK (located in a Windows-accessible directory). To build Linux binaries, you must use a Linux boot JDK. The default behavior is to build for Windows. To build for Linux, pass --build=x86_64-unknown-linux-gnu --host=x86_64-unknown-linux-gnu to configure.
It's possible to build both Windows and Linux binaries from WSL. To build Windows binaries, you must use a Windows boot JDK (located in a Windows-accessible directory). To build Linux binaries, you must use a Linux boot JDK. The default behavior is to build for Windows. To build for Linux, pass --build=x86_64-unknown-linux-gnu --openjdk-target=x86_64-unknown-linux-gnu to configure.
If building Windows binaries, the source code must be located in a Windows- accessible directory. This is because Windows executables (such as Visual Studio and the boot JDK) must be able to access the source code. Also, the drive where the source is stored must be mounted as case-insensitive by changing either /etc/fstab or /etc/wsl.conf in WSL. Individual directories may be corrected using the fsutil tool in case the source was cloned before changing the mount options.
Note that while it's possible to build on WSL, testing is still not fully supported.
All compilers are expected to be able to compile to the C99 language standard, as some C99 features are used in the source code. Microsoft Visual Studio doesn't fully support C99 so in practice shared code is limited to using C99 features that it does support.
The minimum accepted version of gcc is 5.0. Older versions will generate a warning by configure and are unlikely to work.
The JDK is currently known to be able to compile with at least version 10.2 of gcc.
+The JDK is currently known to be able to compile with at least version 11.2 of gcc.
In general, any version between these two should be usable.
The minimum accepted version of clang is 3.5. Older versions will not be accepted by configure.
It is advisable to keep an older version of Xcode for building the JDK when updating Xcode. This blog page has good suggestions on managing multiple Xcode versions. To use a specific version of Xcode, use xcode-select -s before running configure, or use --with-toolchain-path to point to the version of Xcode to use, e.g. configure --with-toolchain-path=/Applications/Xcode8.app/Contents/Developer/usr/bin
If you have recently (inadvertently) updated your OS and/or Xcode version, and the JDK can no longer be built, please see the section on Problems with the Build Environment, and Getting Help to find out if there are any recent, non-merged patches available for this update.
The minimum accepted version of Visual Studio is 2017. Older versions will not be accepted by configure and will not work. The maximum accepted version of Visual Studio is 2019.
For aarch64 machines running Windows the minimum accepted version is Visual Studio 2019 (16.8 or higher). For all other platforms the minimum accepted version of Visual Studio is 2017. Older versions will not be accepted by configure and will not work. For all platforms the maximum accepted version of Visual Studio is 2022.
If you have multiple versions of Visual Studio installed, configure will by default pick the latest. You can request a specific version to be used by setting --with-toolchain-version, e.g. --with-toolchain-version=2017.
If you have Visual Studio installed but configure fails to detect it, it may be because of spaces in path.
To be able to build, we need a "Build JDK", which is a JDK built from the current sources (that is, the same as the end result of the entire build process), but able to run on the build system, and not the target system. (In contrast, the Boot JDK should be from an older release, e.g. JDK 8 when building JDK 9.)
The build process will create a minimal Build JDK for you, as part of building. To speed up the build, you can use --with-build-jdk to configure to point to a pre-built Build JDK. Please note that the build result is unpredictable, and can possibly break in subtle ways, if the Build JDK does not exactly match the current sources.
You must specify the target platform when cross-compiling. Doing so will also automatically turn the build into a cross-compiling mode. The simplest way to do this is to use the --openjdk-target argument, e.g. --openjdk-target=arm-linux-gnueabihf. or --openjdk-target=aarch64-oe-linux. This will automatically set the --build, --host and --target options for autoconf, which can otherwise be confusing. (In autoconf terminology, the "target" is known as "host", and "target" is used for building a Canadian cross-compiler.)
You must specify the target platform when cross-compiling. Doing so will also automatically turn the build into a cross-compiling mode. The simplest way to do this is to use the --openjdk-target argument, e.g. --openjdk-target=arm-linux-gnueabihf. or --openjdk-target=aarch64-oe-linux. This will automatically set the --host and --target options for autoconf, which can otherwise be confusing. (In autoconf terminology, the "target" is known as "host", and "target" is used for building a Canadian cross-compiler.)
If --build has not been explicitly passed to configure, --openjdk-target will autodetect the build platform and internally set the flag automatically, otherwise the platform that was explicitly passed to --build will be used instead.
You will need two copies of your toolchain, one which generates output that can run on the target system (the normal, or target, toolchain), and one that generates output that can run on the build system (the build toolchain). Note that cross-compiling is only supported for gcc at the time being. The gcc standard is to prefix cross-compiling toolchains with the target denominator. If you follow this standard, configure is likely to pick up the toolchain correctly.
The build toolchain will be autodetected just the same way the normal build/target toolchain will be autodetected when not cross-compiling. If this is not what you want, or if the autodetection fails, you can specify a devkit containing the build toolchain using --with-build-devkit to configure, or by giving BUILD_CC and BUILD_CXX arguments.
If you need general help or advice about developing for the JDK, you can also contact the Adoption Group. See the section on Contributing to OpenJDK for more information.
Build reproducibility is the property of getting exactly the same bits out when building, every time, independent on who builds the product, or where. This is for many reasons a harder goal than it initially appears, but it is an important goal, for security reasons and others. Please see Reproducible Builds for more information about the background and reasons for reproducible builds.
-Currently, it is not possible to build OpenJDK fully reproducibly, but getting there is an ongoing effort. There are some things you can do to minimize non-determinism and make a larger part of the build reproducible:
+Currently, it is not possible to build OpenJDK fully reproducibly, but getting there is an ongoing effort.
+An absolute prerequisite for building reproducible is to speficy a fixed build time, since time stamps are embedded in many file formats. This is done by setting the SOURCE_DATE_EPOCH environment variable, which is an industry standard, that many tools, such as gcc, recognize, and use in place of the current time when generating output.
To generate reproducible builds, you must set SOURCE_DATE_EPOCH before running configure. The value in SOURCE_DATE_EPOCH will be stored in the configuration, and used by make. Setting SOURCE_DATE_EPOCH before running make will have no effect on the build.
You must also make sure your build does not rely on configure's default adhoc version strings. Default adhoc version strings OPT segment include user name and source directory. You can either override just the OPT segment using --with-version-opt=<any fixed string>, or you can specify the entire version string using --with-version-string=<your version>.
This is a typical example of how to build the JDK in a reproducible way:
+export SOURCE_DATE_EPOCH=946684800
+bash configure --with-version-opt=adhoc
+makeNote that regardless if you specify a source date for configure or not, the JDK build system will set SOURCE_DATE_EPOCH for all build tools when building. If --with-source-date has the value updated (which is the default unless SOURCE_DATE_EPOCH is found by in the environment by configure), the source date value will be determined at build time.
There are several aspects of reproducible builds that can be individually adjusted by configure arguments. If any of these are given, they will override the value derived from SOURCE_DATE_EPOCH. These arguments are:
--with-source-date
This option controls how the JDK build sets SOURCE_DATE_EPOCH when building. It can be set to a value describing a date, either an epoch based timestamp as an integer, or a valid ISO-8601 date.
It can also be set to one of the special values current, updated or version. current means that the time of running configure will be used. version will use the nominal release date for the current JDK version. updated, which means that SOURCE_DATE_EPOCH will be set to the current time each time you are running make. All choices, except for updated, will set a fixed value for the source date timestamp.
When SOURCE_DATE_EPOCH is set, the default value for --with-source-date will be the value given by SOURCE_DATE_EPOCH. Otherwise, the default value is updated.
--with-hotspot-build-time
This option controls the build time string that will be included in the hotspot library (libjvm.so or jvm.dll). When the source date is fixed (e.g. by setting SOURCE_DATE_EPOCH), the default value for --with-hotspot-build-time will be an ISO 8601 representation of that time stamp. Otherwise the default value will be the current time when building hotspot.
--with-copyright-year
This option controls the copyright year in some generated text files. When the source date is fixed (e.g. by setting SOURCE_DATE_EPOCH), the default value for --with-copyright-year will be the year of that time stamp. Otherwise the default is the current year at the time of running configure. This can be overridden by --with-copyright-year=<year>.
--enable-reproducible-build
This option controls some additional behavior needed to make the build reproducible. When the source date is fixed (e.g. by setting SOURCE_DATE_EPOCH), this flag will be turned on by default. Otherwise, the value is determined by heuristics. If it is explicitly turned off, the build might not be reproducible.
Add the flag --enable-reproducible-builds to your configure command line. This will turn on support for reproducible builds where it could otherwise be lacking.
configure's default adhoc version stringsDefault adhoc version strings OPT segment include user name, source directory and timestamp. You can either override just the OPT segment using --with-version-opt=<any fixed string>, or you can specify the entire version string using --with-version-string=<your version>.
SOURCE_DATE_EPOCHThe JDK build system will set the SOURCE_DATE_EPOCH environment variable during building, depending on the value of the --with-source-date option for configure. The default value is updated, which means that SOURCE_DATE_EPOCH will be set to the current time each time you are running make.
The SOURCE_DATE_EPOCH environment variable is an industry standard, that many tools, such as gcc, recognize, and use in place of the current time when generating output.
For reproducible builds, you need to set this to a fixed value. You can use the special value version which will use the nominal release date for the current JDK version, or a value describing a date, either an epoch based timestamp as an integer, or a valid ISO-8601 date.
Hint: If your build environment already sets SOURCE_DATE_EPOCH, you can propagate this using --with-source-date=$SOURCE_DATE_EPOCH.
Set a fixed hotspot build time. This will be included in the hotspot library (libjvm.so or jvm.dll) and defaults to the current time when building hotspot. Use --with-hotspot-build-time=<any fixed string> for reproducible builds. It's a string so you don't need to format it specifically, so e.g. n/a will do. Another solution is to use the SOURCE_DATE_EPOCH variable, e.g. --with-hotspot-build-time=$(date --date=@$SOURCE_DATE_EPOCH).
The copyright year in some generated text files are normally set to the current year. This can be overridden by --with-copyright-year=<year>. For fully reproducible builds, this needs to be set to a fixed value.
The configure and make commands tries to play nice with bash command-line completion (using <tab> or <tab><tab>). To use this functionality, make sure you enable completion in your ~/.bashrc (see instructions for bash in your operating system).
Many of the guidelines mentioned here have (sometimes widespread) counterexamples in the HotSpot code base. Finding a counterexample is not sufficient justification for new code to follow the counterexample as a precedent, since readers of your code will rightfully expect your code to follow the greater bulk of precedents documented here.
Occasionally a guideline mentioned here may be just out of synch with the actual HotSpot code base. If you find that a guideline is consistently contradicted by a large number of counterexamples, please bring it up for discussion and possible change. The architectural rule, of course, is "When in Rome do as the Romans". Sometimes in the suburbs of Rome the rules are a little different; these differences can be pointed out here.
-Proposed changes should be discussed on the HotSpot Developers mailing list, and approved by rough consensus of the HotSpot Group Members. The Group Lead determines whether consensus has been reached. Changes are likely to be cautious and incremental, since HotSpot coders have been using these guidelines for years.
+Proposed changes should be discussed on the HotSpot Developers mailing list. Changes are likely to be cautious and incremental, since HotSpot coders have been using these guidelines for years.
+Substantive changes are approved by rough consensus of the HotSpot Group Members. The Group Lead determines whether consensus has been reached.
+Editorial changes (changes that only affect the description of HotSpot style, not its substance) do not require the full consensus gathering process. The normal HotSpot pull request process may be used for editorial changes, with the additional requirement that the requisite reviewers are also HotSpot Group Members.
In general, don't change whitespace unless it improves readability or consistency. Gratuitous whitespace changes will make integrations and backports more difficult.
Use One-True-Brace-Style. The opening brace for a function or class is normally at the end of the line; it is sometimes moved to the beginning of the next line for emphasis. Substatements are enclosed in braces, even if there is only a single statement. Extremely simple one-line statements may drop braces around a substatement.
Use One-True-Brace-Style. The opening brace for a function or class is normally at the end of the line; it is sometimes moved to the beginning of the next line for emphasis. Substatements are enclosed in braces, even if there is only a single statement. Extremely simple one-line statements may drop braces around a substatement.
Indentation levels are two columns.
There is no hard line length limit. That said, bear in mind that excessively long lines can cause difficulties. Some people like to have multiple side-by-side windows in their editors, and long lines may force them to choose among unpleasant options. They can use wide windows, reducing the number that can fit across the screen, and wasting a lot of screen real estate because most lines are not that long. Alternatively, they can have more windows across the screen, with long lines wrapping (or worse, requiring scrolling to see in their entirety), which is harder to read. Similar issues exist for side-by-side code reviews.
Tabs are not allowed in code. Set your editor accordingly.
(Emacs: (setq-default indent-tabs-mode nil).)
Google C++ Style Guide — Currently (2020) targeting C++17.
C++11 and C++14 use in Chromium — Categorizes features as allowed, banned, or to be discussed.
C++11 and C++14 use in Chromium — Categorizes features as allowed, banned, or to be discussed.
llvm Coding Standards — Currently (2020) targeting C++14.
Using C++ in Mozilla code — C++17 support is required for recent versions (2020).
Do not use the standard global allocation and deallocation functions (operator new and related functions). Use of these functions by HotSpot code is disabled for some platforms.
-Rationale: HotSpot often uses "resource" or "arena" allocation. Even where heap allocation is used, the standard global functions are avoided in favor of wrappers around malloc and free that support the VM's Native Memory Tracking (NMT) feature.
+Rationale: HotSpot often uses "resource" or "arena" allocation. Even where heap allocation is used, the standard global functions are avoided in favor of wrappers around malloc and free that support the VM's Native Memory Tracking (NMT) feature. Typically, uses of the global operator new are inadvertent and therefore often associated with memory leaks.
Native memory allocation failures are often treated as non-recoverable. The place where "out of memory" is (first) detected may be an innocent bystander, unrelated to the actual culprit.
Use public single inheritance.
@@ -268,8 +270,8 @@ while ( test_foo(args...) ) { // No, excess spaces around controlThe underlying type of a scoped-enum should also be specified explicitly if conversions may be applied to values of that type.Due to bugs in certain (very old) compilers, there is widespread use of enums and avoidance of in-class initialization of static integral constant members. Compilers having such bugs are no longer supported. Except where an enum is semantically appropriate, new code should use integral constants.
Do not use thread_local (n2659); instead, use the HotSpot macro THREAD_LOCAL. The initializer must be a constant expression.
As was discussed in the review for JDK-8230877, thread_local allows dynamic initialization and destruction semantics. However, that support requires a run-time penalty for references to non-function-local thread_local variables defined in a different translation unit, even if they don't need dynamic initialization. Dynamic initialization and destruction of namespace-scoped thread local variables also has the same ordering problems as for ordinary namespace-scoped variables.
Avoid use of thread_local (n2659); and instead, use the HotSpot macro THREAD_LOCAL, for which the initializer must be a constant expression. When thread_local must be used, use the Hotspot macro APPROVED_CPP_THREAD_LOCAL to indicate that the use has been given appropriate consideration.
As was discussed in the review for JDK-8230877, thread_local allows dynamic initialization and destruction semantics. However, that support requires a run-time penalty for references to non-function-local thread_local variables defined in a different translation unit, even if they don't need dynamic initialization. Dynamic initialization and destruction of non-local thread_local variables also has the same ordering problems as for ordinary non-local variables. So we avoid use of thread_local in general, limiting its use to only those cases where dynamic initialization or destruction are essential. See JDK-8282469 for further discussion.
Prefer nullptr (n2431) to NULL. Don't use (constexpr or literal) 0 for pointers.
For historical reasons there are widespread uses of both NULL and of integer 0 as a pointer value.
Inline namespaces (n2535) — HotSpot makes very limited use of namespaces.
using namespace directives. In particular, don't use using namespace std; to avoid needing to qualify Standard Library names.
Propagating exceptions (n2179) — HotSpot does not permit the use of exceptions, so this feature isn't useful.
Avoid namespace-scoped variables with non-constexpr initialization. In particular, avoid variables with types requiring non-trivial initialization or destruction. Initialization order problems can be difficult to deal with and lead to surprises, as can destruction ordering. HotSpot doesn't generally try to cleanup on exit, and running destructors at exit can also lead to problems.
Avoid non-local variables with non-constexpr initialization. In particular, avoid variables with types requiring non-trivial initialization or destruction. Initialization order problems can be difficult to deal with and lead to surprises, as can destruction ordering. HotSpot doesn't generally try to cleanup on exit, and running destructors at exit can also lead to problems.
[[deprecated]] attribute (n3760) — Not relevant in HotSpot code.
Avoid most operator overloading, preferring named functions. When operator overloading is used, ensure the semantics conform to the normal expected behavior of the operation.
Avoid most implicit conversion constructors and (implicit or explicit) conversion operators. (Note that conversion to bool isn't needed in HotSpot code because of the "no implicit boolean" guideline.)
make vscode-project-clangdAdditional instructions for configuring the given indexer will be displayed after the workspace has been generated.
This section is a work in progress.
-make ide-projectThe make system can generate a Visual Studio project for the Hotspot native source. After configuring, the project is generated using:
+make hotspot-ide-projectThis creates a file named jvm.vcxproj in ide\hotspot-visualstudio subfolder of the build output folder. The file can be opened in Visual Studio via File -> Open -> Project/Solution.
The make system can generate generic native code indexing support in the form of a Compilation Database that can be used by many different IDEs and source code indexers.
make compile-commandsIt's also possible to generate the Compilation Database for the HotSpot source code only, which is a bit faster as it includes less information.
make compile-commands-hotspotThis section is a work in progress.
+The JDK project has a script that can be used for indexing the project with IntelliJ. After configuring and building the JDK, an IntelliJ workspace can be generated by running the following command in the top-level folder of the cloned repository:
+bash bin/idea.shTo use it, choose File -> Open... in IntelliJ and select the folder where you ran the above script.
Next, configure the project SDK in IntelliJ. Open File -> Project Structure -> Project and select build/<config>/images/jdk as the SDK to use.
In order to run the tests from the IDE, you can use the JTReg plugin. Instructions for building and using the plugin can be found here.