add more method-level options for -XX:CompileCommand
eg. -XX:CompileCommand=option,java.lang.String::startsWith,BreakAtCompile directs JIT compilers to hit BREAKPOINT when they compile the method java.lang.String::startsWith.
Reviewed-by: neliasso, azeemj, phh
Use the code motion trace produced by TraceOptoPipelining (excluding traces of
stubs) to assert that two compilations with the same seed cause StressLCM and
StressGCM to take the same randomized decisions. Previously, the entire output
produced by PrintOptoStatistics was used instead, which has shown to be too
fragile. Also, disable inlining in both TestStressCM.java and the similar
TestStressIGVN.java to prevent flaky behavior, and run both tests for ten
different seeds to improve coverage.
Reviewed-by: kvn, thartmann
disconnect_inputs() needs to iterate precedences edges in reverse order because rm_prec(i) may backfill _in[i] with a value afterward.
also remove the predicate if (n != NULL) in set_prec because it's always true.
Reviewed-by: kvn, redestad
Remove test assertion checking that different random seeds lead to different
code motion decisions. This was the case for the specific pair of random seeds,
IR fed to code motion, and target platforms tested originally; but does not need
to hold in general. Remove similar test assertion in IGVN randomization test
case. Re-enable the test case.
Reviewed-by: shade, kvn
Use the compilation-local seed in 'StressLCM' and 'StressGCM' rather than the
global one. As a consequence, these options use by default a fresh seed in every
compilation, unless 'StressSeed=N' is specified, in which case they behave
deterministically. Annotate tests that use 'StressLCM' and 'StressGCM' with the
'stress' and 'randomness' keys to reflect this change in default behavior.
Reviewed-by: kvn, thartmann
Record nodes as dead in Node::destruct() if their index cannot be directly
reclaimed. This prevents the "Live Node limit exceeded limit" assertion failure
by improving the accuracy of Compile::live_nodes() when "hook" nodes in
ConvI2LNode::Ideal() are created and deleted non-consecutively.
This addition might result in multiple calls to compile::record_dead_node() for
the same node (e.g. from PhaseIdealLoop::spinup()), but this is safe, as
compile::record_dead_node() is idempotent.
Reviewed-by: neliasso, thartmann
Account for interface files for swap and memory being reported independently.
The cgroup v1-like value is now reported by adding the memory.max value to
the memory.swap.max value, and memory.current and memory.swap.current
respectively.
Reviewed-by: bobv, shade
Update NodeClasses::_max_classes to the max class id within the
enumeration. Update comment and assertion to reflect that NodeClasses uses now
32 bits after the addition of Opaque1 in JDK-8229495.
Reviewed-by: neliasso, kvn
Replace double array with short array in AdapterHandlerLibrary::create_native_wrapper, add parens around ?: in CSystemColors:getColor
Reviewed-by: prr, kbarrett, lucy
The early implementation of cgroups v2 support was done with
crun 0.8 and it contained a bug which set memory.high over
memory.low when --memory-reservation was being used as a CLI
option.
This bug has been fixed in later crun versions, starting with
crun 0.11. Use memory.low in OpenJDK as well.
Reviewed-by: bobv, adinn
Add 'StressIGVN' option to let C2 randomize IGVN worklist order. When enabled,
the worklist is shuffled before each main run of the IGVN loop. Also add
'StressSeed=N' option to specify the seed. If the seed is not specified, a
random one is generated. In either case, the seed is logged if 'LogCompilation'
is enabled. The new options are declared as production+diagnostic for
consistency with the existing 'StressLCM' and 'StressGCM' options.
Reviewed-by: kvn, chagedorn, thartmann
Remove unused notion of 'PhiNode-to-copy degradation', where PhiNodes can be
degraded to copies by setting their RegionNode to NULL. Remove corresponding
PhiNode::is_copy() test, which always returned NULL (false). Assert that
PhiNodes have an associated RegionNode in PhiNode::Ideal().
Reviewed-by: thartmann, kvn
8253238: [REDO] Improve object array chunking test in G1's copy_to_survivor_space
8253236: [REDO] Investigate fast-path for scanning only objects with references during gc
Generate multiple partial array tasks for large objArrays.
Reviewed-by: sjohanss, ayang, tschatzl
Add release fence to ClassValueMap constructor.
* Release fence guarantees that cacheArray field will published
with a non-null value.
* Without this fix, CacheValueMap.cacheArray can sometimes be
seen as null.
Reviewed-by: shade, psandoz
Remove the KILL_COMPILE_ON_FATAL_ and KILL_COMPILE_ON_ANY macros, replacing uses
of KILL_COMPILE_ON_FATAL_ with CHECK_AND_CLEAR_. Unlike KILL_COMPILE_ON_FATAL_,
CHECK_AND_CLEAR_ ignores ThreadDeath exceptions, which compiler threads should
not receive anyway.
Reviewed-by: vlivanov, neliasso
Revert "8027545: Improve object array chunking test in G1's copy_to_survivor_space"
Revert "8158045: Improve large object handling during evacuation"
Revert "8027761: Investigate fast-path for scanning only objects with references during gc"
Reviewed-by: tschatzl, sjohanss
8158045: Improve large object handling during evacuation
8027761: Investigate fast-path for scanning only objects with references during gc
Generate multiple partial array tasks for large objArrays.
Reviewed-by: sjohanss, ayang, tschatzl
Reimpliment PrimitiveConversions::cast, with some cases now constexpr.
<!-- Anything below this marker will be automatically updated, please do not edit manually! -->
---------
### Progress
- [x] Change must not contain extraneous whitespace
- [x] Commit message must refer to an issue
- [ ] Change must be properly reviewed
### Issue
* [JDK-8247909](https://bugs.openjdk.java.net/browse/JDK-8247909): Improve PrimitiveConversions::cast using C++14
### Download
`$ git fetch https://git.openjdk.java.net/jdk pull/143/head:pull/143`
`$ git checkout pull/143`
Reviewed-by: dholmes, stefank
Remove dead definition of ptr_type in TypeAryPtr::cast_to_autobox_cache. Also remove
unnecessary cache parameter (always true) for simplicity.
Reviewed-by: shade, vlivanov, thartmann
The comment is wrong. The 'us' in 'cpu.cfs_quota_us' stands for
microseconds, which is read verbatim. Similarly for cgroups v2
all units in 'cpu.max' are in microseconds.
Reviewed-by: shade, hseigel
Some CPUs (like ARM32) does not support unaligned memory accesses. To avoid JVM crashes tests that perform such accesses should be skipped on corresponding platforms.
Reviewed-by: iignatyev, clanger
Cleanup code for jlink classes generation, move parsing file work to java.lang.invoke and add a new API in interface JavaLangInvokeAccess to generate holder classes, remove old APIs. The new API is used both by JLI and CDS.
Reviewed-by: mchung, sundar
Remove @ignore since @requires os.maxMemory is enough to ensure tests will not be executed if memory requirements are not satisfied
Reviewed-by: coffeys
This patch adds a new flatmap-like operation called mapMulti to the java.util.Stream class as well as the primitive variations of this operation i.e. mapMultiToInt, IntStream mapMulti, etc.
Reviewed-by: psandoz, smarks
Call ClassLoaderDataGraph::loaded_cld_do to collect ClassLoaderData in a GrowableArray and then walk through them to link the classes in each ClassLoaderData.
Reviewed-by: coleenp, iklam
The JDK-specific API `jdk.net.Sockets` has been redundant since Java SE 9 added standard methods to get/set socket options and retrieve per-Socket supported options. This fix deprecates the class and its public methods.
Reviewed-by: chegar, dfuchs
Fix wrong replacement of loads by zero for non-completed InitializationNodes belonging to a clone when ReduceBulkZeroing is disabled.
Reviewed-by: kvn, thartmann
OOME seems to have happened in older version and does not show up in modern VM, hence the test OverloadCompileQueueTest.java gets un-quarantined.
Reviewed-by: iignatyev
Avoid inserting InstanceKlass into the DumpTimeSharedClassTable after dynamic CDS dumping has started. Acquire the DumpTimeTable_lock before iterations on _dumptime_table to ensure memory order correctness.
Reviewed-by: iklam, minqi
This fix changes the test to run with the new impl of DatagramSocket, which remedies the issue that caused the test to fail with a wrong expection and can now be taken off the ProblemList.
Reviewed-by: dfuchs
This fix updates `java/net/DatagramSocket/SendReceiveMaxSize.java` and `java/net/DatagramSocket/SendReceiveMaxSize.java` to check (on all platforms) that the sending/receiving of large datagrams across a network are sent, fragmented, and re-assembled correctly
Reviewed-by: alanb, dfuchs
The original change missed to update an assert.
Co-authored-by: Ludovic Henry <luhenry@microsoft.com>
Co-authored-by: Bernhard Urban-Forster <beurba@microsoft.com>
Reviewed-by: dholmes
The `test java/net/DatagramSocket/SendReceiveMaxSize` is currently failing when run with `-Djdk.net.usePlainDatagramSocketImpl` and `-Djava.net.preferIPv4Stack=true`. This fix removes these run settings from the test until a more permanent solution can be found.
Reviewed-by: dfuchs
This fix changes the current max size for IPv6 datagrams on macOS from it's current size of 65507, which is the IPv4 limit, to 65527, the actual limit for IPv6 on macOS
Reviewed-by: alanb, dfuchs, vtewari
This fix updates these tests to explicitly run with `-Djdk.net.usePlainDatagramSocketImpl=false` to avoid false failures when running all tests with a global jtreg -Djdk.net.usePlainDatagramSocketImpl switch.
Reviewed-by: vtewari
Release OopStorage oops for threadObj for exiting threads outside the service lock region that is marked as safe for safepoint.
Reviewed-by: zgu, dholmes, kbarrett
This fix addresses an issue where an AsynchronousCloseException was being thrown instead of a ChannelClosedException when SocketChannel.write() is called on a closed SocketChannel.
Reviewed-by: alanb, chegar, dfuchs
SO_RCVBUF was previously set to match the SO_SNDBUF, however the kernel value for SO_RCVBUF is much larger. This mismatch caused the test to fail, and the fix removes this issue.
Reviewed-by: alanb, dfuchs
Move recent timestamp of most recent whole heap liveness analysis into CollectedHeap, removing the duplicates in all collectors
Reviewed-by: kbarrett, ayang, stefank
SocketTube is fixed to cater for errors caused by pausing/resuming events on an asynchronously closed connection, from within the selector's manager thread. Http2Connection and Stream are fixed to prevent sending a DataFrame on a stream after Reset has been sent.
Reviewed-by: chegar
TransportImpl is modified to make sure the CLOSED state is recorded before the channel is closed. The tests are modified to enable their retry mechanism on windows, similar to what was done previously for macOS.
Reviewed-by: prappo, chegar
Move the oop and handle releasing it in the service thread. Remove Universe::oops_do from callers.
Co-authored-by: Erik Osterlund <erik.osterlund@oracle.com>
Co-authored-by: Tom Rodriguez <tom.rodriguez@oracle.com>
Reviewed-by: dholmes, zgu, eosterlund, cjplummer
OopStorage instance now owned by subsystems, and generalize dead entry notification
Co-authored-by: Erik Osterlund <erik.osterlund@oracle.com>
Co-authored-by: Stefan Karlsson <stefan.karlsson@oracle.com>
Reviewed-by: coleenp, tschatzl
The API documentation of NetworkInterface::equals is clarified to warn about the possibility that two NetworkInterface representing the same underlying interface objects might not compare equal if the IP addresses bound to the interfaces are being dynamically updated by the system.
Reviewed-by: alanb, chegar
8237743: test/langtools/jdk/jshell/FailOverExecutionControlTest.java fails No ExecutionControlProvider with name 'nonExistent' and parameter keys: []
8199646: JShell tests: jdk/jshell/FailOverDirectExecutionControlTest.java failed with java.lang.UnsupportedOperationException
Reviewed-by: jlahoda
8237743: test/langtools/jdk/jshell/FailOverExecutionControlTest.java fails No ExecutionControlProvider with name 'nonExistent' and parameter keys: []
8199646: JShell tests: jdk/jshell/FailOverDirectExecutionControlTest.java failed with java.lang.UnsupportedOperationException
Reviewed-by: jlahoda
Implement parallel processing of strong OopStorage entries for G1.
Co-authored-by: Erik Osterlund <erik.osterlund@oracle.com>
Co-authored-by: Stefan Karlsson <stefan.karlsson@oracle.com>
Reviewed-by: kbarrett, stefank
Use a synthetic annotation instead of inaccessible jdk.internal.PreviewFeature in ct.sym, and avoid resolving that annotation, to prevent errors being printed for the inaccessible types.
Reviewed-by: jlaskey
Change CC_INTERP conditional to ZERO and remove in places where unnecessary. Fix build to exclude compilers and rename CppInterpreter to ZeroInterpreter. The "C++ Interpreter" has been removed from the code a while ago.
Reviewed-by: dholmes, ihse
8248135: Build microbenchmarks with --enable-preview
Test contributed by Chris Hegarty <chris.hegarty@oracle.com>
Reviewed-by: chegar, psandoz, redestad, ihse
Bail out in PhaseIdealLoop:split_thru_phi when trying to split a Div or ModNode iv phi whose zero check was removed but could potentially still be zero based on type information.
Reviewed-by: kvn, thartmann
The fix saves result type from the first pass through the Attr.visitLambda and returns it after recovery pass to avoid NPE caused by exposure of Type.recoveryType
Reviewed-by: mcimadamore
OptimizeModuleHandlingTest.java should be disabled for jvmci since jvmci will set jdk.module.addmods.0=jdk.internal.vm.ci which lead to optimization disabled.
Reviewed-by: dcubed
This fix removes NetworkPermission checks that were made redundant in jdk/net/ExtendedSocketOptions after the socket option SO_FLOW_SLA was removed.
Reviewed-by: alanb
This fix clarifies the behaviours of constructors from DatagramSocket and MulticastSocket when no address or a null address is supplied.
Reviewed-by: dfuchs
Fix for intermitant failure with AsynchronousSocketChannelNAPITest that sometimes fails with a NotYetConnectedException while trying to read data after connecting
Reviewed-by: alanb, dfuchs
This patch removes ExtendedSocketOptions.SO_FLOW_SLA, SocketFlow and SocketFlow.Status which were terminally deprecated in JDK 14 in preparation for the removal of the Solaris port.
Reviewed-by: alanb, dfuchs, chegar, vtewari
Rework non-default file system paths of BodySubscriber::ofFile and BodyHandler::ofFile and fix BodyHandler::ofFileDownload to throw consistently for non-default file system paths
Reviewed-by: dfuchs, chegar
This fix updates the spec for DatagramSocket's constructors to inform the user of the Exceptions thrown when an invalid argument is passed.
Reviewed-by: dfuchs
Concurrent work of symbol table caused _shared_table not walkable in dumping archive which led symbols not sorted in shared archive. Change to use do_safepoint_scan of _local_table to collect symbols.
Reviewed-by: iklam, ccheung
The fix updates sun.net.httpserver.ExchangeImpl to use thread safe DateTimeFormatter for response headers, this replaces DateFormat that was using ThreadLocal.
Reviewed-by: dfuchs, alanb, chegar
This patch updates the @modules tag with +open in the tests UnreferencedDatagramSockets and UnreferncedMulticastSockets in advance of the removal of --illegal-access to allow access to private member fields required by the tests.
Reviewed-by: alanb, dfuchs
8245585: Add SourceVersion.RELEASE_16
8245586: Add source 16 and target 16 to javac
8245544: com/sun/tools/javac/platform/JDKPlatformProvider.java does not support ct.sym with platform versions 16+
Co-authored-by: David Holmes <david.holmes@oracle.com>
Co-authored-by: Jan Lahoda <jan.lahoda@oracle.com>
Reviewed-by: erikj, dholmes, ihse, neugens, jjg, jlahoda, jlaskey, mikael
SystemDitionary::load_shared_class can avoid calling is_shared_class_visible if dumptime and runtime do not use modulepath and boot classpath appending.
Reviewed-by: iklam, ccheung
Fix Parse::Block::init_graph() to also count predecessors for exception blocks because they can have a direct bytecode jump to them resulting in this assertion failure.
Reviewed-by: kvn, thartmann
This fix updates the javadoc for `DatagramSocket.connect` to inform the user that it may cause datagrams in the socket receive buffer to be discarded if not previously received via a call to `DatagramSocket.receive`.
Reviewed-by: alanb, dfuchs
Add support for the SO_INCOMING_NAPI_ID socket option to jdk.net.ExtendedSocketOptions
Co-authored-by: Dinesh Kumar <dinesh.kumar@intel.com>
Reviewed-by: alanb, chegar, dfuchs, vtewari, pconcannon
Fix of 8237750 changed the loading zip library to on-demand loading, on Windows, jlink/jimage still assume that zip has been loaded already. Fix to load zip on not loaded.
Reviewed-by: kbarrett, mchung, dholmes, dcubed
The fix updates jdk.internal.net.http.websocket. OpeningHandshake.send() method to process the response body from server
Reviewed-by: chegar, dfuchs, prappo
Record loader constraints for built-in class which is loaded by app loader or platform loader in shared archive in dump time. When the class loaded from shared archive at runtime, directly check loader constraints using the saved info so avoid lengthy relayout i/v-table at class link stage.
Reviewed-by: iklam, ccheung
Replace the underlying implementations of the java.net.DatagramSocket and java.net.MulticastSocket APIs with simpler and more modern implementations that are easy to maintain and debug.
Co-authored-by: Alan Bateman <alan.bateman@oracle.com>
Co-authored-by: Chris Hegarty <chris.hegarty@oracle.com>
Co-authored-by: Daniel Fuchs <daniel.fuchs@oracle.com>
Reviewed-by: alanb, chegar, dfuchs
The test java.net.httpclient.websocket.WSHandshakeExceptionTest.java checks that the websocket client handles invalid utf-8 sent by the websocket server
Reviewed-by: dfuchs
Adjusting langtools ant build and Idea project to Nashorn removal.
Co-authored-by: Maurizio Cimadamore <maurizio.cimadamore@oracle.com>
Reviewed-by: mcimadamore, jlahoda
Avoid calling ClassLoaders.definePackage during loading of shared classes originated from the module image since java.lang.Package for named modules are automatically defined.
Reviewed-by: mchung, lfoltan
Tests added for methods: setSendBufferSize(int), getSendBufferSize(), and getReceieveBufferSize() to increase test coverage in the DatagramSocket class
Reviewed-by: alanb, chegar, dfuchs
This patch fixes two instances of bad unicode formatting in the javadoc for Arrays.java where the null character constant was incorrectly specified.
Reviewed-by: jlaskey, lancea, prappo, dfuchs
Add support for AsyncDeflateIdleMonitors (default true); the async deflation work is performed by the ServiceThread.
Co-authored-by: Carsten Varming <varming@gmail.com>
Reviewed-by: dcubed, rehn, rkennke, cvarming, coleenp, acorn, dholmes, eosterlund
In SuperWord::find_align_to_ref(), only discard unalignable memory ops if memory references should be aligned on this platform.
Reviewed-by: roland, thartmann
8225056: VM support for sealed classes
8227044: javax.lang.model for sealed classes
8227045: Preview APIs support for sealed classes
8227047: Javadoc for sealed types
8245854: JVM TI Specification for sealed classes
Co-authored-by: Harold Seigel <harold.seigel@oracle.com>
Co-authored-by: Jan Lahoda <jan.lahoda@oracle.com>
Reviewed-by: mcimadamore, forax, darcy, dholmes, jlahoda, lfoltan, mchung, sspitsyn, vromero
8245432: Lookup::defineHiddenClass should throw UnsupportedClassVersionError if bytes are of an unsupported major or minor version
8245596: Clarify Lookup::defineHiddenClass spec @throws IAE if the bytes has ACC_MODULE flag set
Reviewed-by: alanb, dholmes
Fixed java.lang.ArrayIndexOutOfBoundsException in com.sun.tools.classfile.Code_attribute.getInstructions() for methods with no instructions
Reviewed-by: vromero
<p>The JDK is a massive project, and require machines ranging from decent to powerful to be able to build in a reasonable amount of time, or to be able to complete a build at all.</p>
<p>We <em>strongly</em> recommend usage of an SSD disk for the build, since disk speed is one of the limiting factors for build performance.</p>
<h3id="building-on-x86">Building on x86</h3>
<p>At a minimum, a machine with 2-4 cores is advisable, as well as 2-4 GB of RAM. (The more cores to use, the more memory you need.) At least 6 GB of free disk space is required (8 GB minimum for building on Solaris).</p>
<p>At a minimum, a machine with 2-4 cores is advisable, as well as 2-4 GB of RAM. (The more cores to use, the more memory you need.) At least 6 GB of free disk space is required.</p>
<p>Even for 32-bit builds, it is recommended to use a 64-bit build machine, and instead create a 32-bit target using <code>--with-target-bits=32</code>.</p>
<h3id="building-on-sparc">Building on sparc</h3>
<p>At a minimum, a machine with 4 cores is advisable, as well as 4 GB of RAM. (The more cores to use, the more memory you need.) At least 8 GB of free disk space is required.</p>
<p>Note: The sparc port is deprecated.</p>
<h3id="building-on-aarch64">Building on aarch64</h3>
<p>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.</p>
<p>If you do not have access to sufficiently powerful hardware, it is also possible to use <ahref="#cross-compiling">cross-compiling</a>.</p>
<h3id="building-on-32-bit-arm">Building on 32-bit arm</h3>
<p>This is not recommended. Instead, see the section on <ahref="#cross-compiling">Cross-compiling</a>.</p>
<h2id="operating-system-requirements">Operating System Requirements</h2>
<p>The mainline JDK project supports Linux, Solaris, macOS, AIX and Windows. Support for other operating system, e.g. BSD, exists in separate "port" projects.</p>
<p>The mainline JDK project supports Linux, macOS, AIX and Windows. Support for other operating system, e.g. BSD, exists in separate "port" projects.</p>
<p>In general, the JDK can be built on a wide range of versions of these operating systems, but the further you deviate from what is tested on a daily basis, the more likely you are to run into problems.</p>
<p>This table lists the OS versions used by Oracle when building the JDK. Such information is always subject to change, but this table is up to date at the time of writing.</p>
<table>
@@ -184,20 +179,16 @@
<tdstyle="text-align: left;">Oracle Enterprise Linux 6.4 / 7.6</td>
<tdstyle="text-align: left;">Mac OS X 10.13 (High Sierra)</td>
</tr>
<trclass="even">
<trclass="odd">
<tdstyle="text-align: left;">Windows</td>
<tdstyle="text-align: left;">Windows Server 2012 R2</td>
</tr>
</tbody>
</table>
<p>The double version numbers for Linux and Solaris are due to the hybrid model used at Oracle, where header files and external libraries from an older version are used when building on a more modern version of the OS.</p>
<p>The double version numbers for Linux are due to the hybrid model used at Oracle, where header files and external libraries from an older version are used when building on a more modern version of the OS.</p>
<p>The Build Group has a wiki page with <ahref="https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms">Supported Build Platforms</a>. From time to time, this is updated by contributors to list successes or failures of building on different platforms.</p>
<h3id="windows">Windows</h3>
<p>Windows XP is not a supported platform, but all newer Windows should be able to build the JDK.</p>
@@ -223,10 +214,6 @@
<p>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 <code>--build=x86_64-unknown-linux-gnu --host=x86_64-unknown-linux-gnu</code> to <code>configure</code>.</p>
<p>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.</p>
<p>Note that while it's possible to build on WSL, testing is still not fully supported.</p>
<h3id="solaris">Solaris</h3>
<p>See <code>make/devkit/solaris11.1-package-list.txt</code> for a list of recommended packages to install when building on Solaris. The versions specified in this list is the versions used by the daily builds at Oracle, and is likely to work properly.</p>
<p>Older versions of Solaris shipped a broken version of <code>objcopy</code>. At least version 2.21.1 is needed, which is provided by Solaris 11 Update 1. Objcopy is needed if you want to have external debug symbols. Please make sure you are using at least version 2.21.1 of objcopy, or that you disable external debug symbols.</p>
<p>Note: The Solaris port is deprecated.</p>
<h3id="macos">macOS</h3>
<p>Apple is using a quite aggressive scheme of pushing OS updates, and coupling these updates with required updates of Xcode. Unfortunately, this makes it difficult for a project such as the JDK to keep pace with a continuously updated machine running macOS. See the section on <ahref="#apple-xcode">Apple Xcode</a> on some strategies to deal with this.</p>
<p>It is recommended that you use at least Mac OS X 10.13 (High Sierra). At the time of writing, the JDK has been successfully compiled on macOS 10.12 (Sierra).</p>
<p>Please consult the AIX section of the <ahref="https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms">Supported Build Platforms</a> OpenJDK Build Wiki page for details about which versions of AIX are supported.</p>
<tdstyle="text-align: left;">Oracle Solaris Studio 12.6 (with compiler version 5.15)</td>
</tr>
<trclass="even">
<tdstyle="text-align: left;">Windows</td>
<tdstyle="text-align: left;">Microsoft Visual Studio 2017 update 15.9.16</td>
<tdstyle="text-align: left;">Microsoft Visual Studio 2019 update 16.7.2</td>
</tr>
</tbody>
</table>
<p>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.</p>
<h3id="gcc">gcc</h3>
<p>The minimum accepted version of gcc is 5.0. Older versions will generate a warning by <code>configure</code> and are unlikely to work.</p>
<p>The JDK is currently known to be able to compile with at least version 9.2 of gcc.</p>
<p>The JDK is currently known to be able to compile with at least version 10.2 of gcc.</p>
<p>In general, any version between these two should be usable.</p>
<h3id="clang">clang</h3>
<p>The minimum accepted version of clang is 3.2. Older versions will not be accepted by <code>configure</code>.</p>
<p>The minimum accepted version of clang is 3.5. Older versions will not be accepted by <code>configure</code>.</p>
<p>To use clang instead of gcc on Linux, use <code>--with-toolchain-type=clang</code>.</p>
<h3id="apple-xcode">Apple Xcode</h3>
<p>The oldest supported version of Xcode is 8.</p>
@@ -313,68 +294,9 @@
<pre><code>xcode-select --install</code></pre>
<p>It is advisable to keep an older version of Xcode for building the JDK when updating Xcode. This <ahref="http://iosdevelopertips.com/xcode/install-multiple-versions-of-xcode.html">blog page</a> has good suggestions on managing multiple Xcode versions. To use a specific version of Xcode, use <code>xcode-select -s</code> before running <code>configure</code>, or use <code>--with-toolchain-path</code> to point to the version of Xcode to use, e.g. <code>configure --with-toolchain-path=/Applications/Xcode8.app/Contents/Developer/usr/bin</code></p>
<p>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 <ahref="#problems-with-the-build-environment">Problems with the Build Environment</a>, and <ahref="#getting-help">Getting Help</a> to find out if there are any recent, non-merged patches available for this update.</p>
<h3id="oracle-solaris-studio">Oracle Solaris Studio</h3>
<p>The minimum accepted version of the Solaris Studio compilers is 5.13 (corresponding to Solaris Studio 12.4). Older versions will not be accepted by configure.</p>
<p>The Solaris Studio installation should contain at least these packages:</p>
<p>Compiling with Solaris Studio can sometimes be finicky. This is the exact version used by Oracle, which worked correctly at the time of writing:</p>
<pre><code>$ cc -V
cc: Sun C 5.13 SunOS_i386 2014/10/20
$ CC -V
CC: Sun C++ 5.13 SunOS_i386 151846-10 2015/10/30</code></pre>
<p>The minimum accepted version of Visual Studio is 2010. Older versions will not be accepted by <code>configure</code>. The maximum accepted version of Visual Studio is 2019. Versions older than 2017 are unlikely to continue working for long.</p>
<p>If you have multiple versions of Visual Studio installed, <code>configure</code> will by default pick the latest. You can request a specific version to be used by setting <code>--with-toolchain-version</code>, e.g. <code>--with-toolchain-version=2015</code>.</p>
<p>If you get <code>LINK: fatal error LNK1123: failure during conversion to COFF: file invalid</code> when building using Visual Studio 2010, you have encountered <ahref="http://support.microsoft.com/kb/2757355">KB2757355</a>, a bug triggered by a specific installation order. However, the solution suggested by the KB article does not always resolve the problem. See <ahref="https://stackoverflow.com/questions/10888391">this stackoverflow discussion</a> for other suggestions.</p>
<p>The minimum accepted version of Visual Studio is 2017. Older versions will not be accepted by <code>configure</code> and will not work. The maximum accepted version of Visual Studio is 2019.</p>
<p>If you have multiple versions of Visual Studio installed, <code>configure</code> will by default pick the latest. You can request a specific version to be used by setting <code>--with-toolchain-version</code>, e.g. <code>--with-toolchain-version=2017</code>.</p>
<h3id="ibm-xl-cc">IBM XL C/C++</h3>
<p>Please consult the AIX section of the <ahref="https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms">Supported Build Platforms</a> OpenJDK Build Wiki page for details about which versions of XLC are supported.</p>
<p>Use <code>--with-freetype-include=<path></code> and <code>--with-freetype-lib=<path></code> if <code>configure</code> does not automatically locate the platform FreeType files.</p>
<h3id="cups">CUPS</h3>
@@ -402,15 +324,15 @@ CC: Sun C++ 5.13 SunOS_i386 151846-10 2015/10/30</code></pre>
<ul>
<li>To install on an apt-based Linux, try running <code>sudo apt-get install libcups2-dev</code>.</li>
<li>To install on an rpm-based Linux, try running <code>sudo yum install cups-devel</code>.</li>
<li>To install on Solaris, try running <code>pkg install print/cups</code>.</li>
<li>To install on macOS, try running <code>brew install autoconf</code>.</li>
<li>To install on Windows, try running <code><path to Cygwin setup>/setup-x86_64 -q -P autoconf</code>.</li>
</ul>
@@ -443,7 +368,6 @@ CC: Sun C++ 5.13 SunOS_i386 151846-10 2015/10/30</code></pre>
<p>At least version 3.81 of GNU Make must be used. For distributions supporting GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful functionality to handle parallel building (supported by <code>--with-output-sync</code>) and speed and stability improvements.</p>
<p>Note that <code>configure</code> locates and verifies a properly functioning version of <code>make</code> and stores the path to this <code>make</code> binary in the configuration. If you start a build using <code>make</code> on the command line, you will be using the version of make found first in your <code>PATH</code>, and not necessarily the one stored in the configuration. This initial make will be used as "bootstrap make", and in a second stage, the make located by <code>configure</code> will be called. Normally, this will present no issues, but if you have a very old <code>make</code>, or a non-GNU Make <code>make</code> in your path, this might cause issues.</p>
<p>If you want to override the default make found by <code>configure</code>, use the <code>MAKE</code> configure variable, e.g. <code>configure MAKE=/opt/gnu/make</code>.</p>
<p>On Solaris, it is common to call the GNU version of make by using <code>gmake</code>.</p>
<h3id="gnu-bash">GNU Bash</h3>
<p>The JDK requires <ahref="http://www.gnu.org/software/bash">GNU Bash</a>. No other shells are supported.</p>
<p>At least version 3.2 of GNU Bash must be used.</p>
@@ -578,7 +502,12 @@ CC: Sun C++ 5.13 SunOS_i386 151846-10 2015/10/30</code></pre>
</ul>
<h2id="running-tests">Running Tests</h2>
<p>Most of the JDK tests are using the <ahref="http://openjdk.java.net/jtreg">JTReg</a> test framework. Make sure that your configuration knows where to find your installation of JTReg. If this is not picked up automatically, use the <code>--with-jtreg=<path to jtreg home></code> option to point to the JTReg framework. Note that this option should point to the JTReg home, i.e. the top directory, containing <code>lib/jtreg.jar</code> etc.</p>
<p>The <ahref="https://wiki.openjdk.java.net/display/Adoption">Adoption Group</a> provides recent builds of jtreg <ahref="https://adopt-openjdk.ci.cloudbees.com/job/jtreg/lastSuccessfulBuild/artifact">here</a>. Download the latest <code>.tar.gz</code> file, unpack it, and point <code>--with-jtreg</code> to the <code>jtreg</code> directory that you just unpacked.</p>
<p>The <ahref="https://wiki.openjdk.java.net/display/Adoption">Adoption Group</a> provides recent builds of jtreg <ahref="https://ci.adoptopenjdk.net/view/Dependencies/job/jtreg/lastSuccessfulBuild/artifact">here</a>. Download the latest <code>.tar.gz</code> file, unpack it, and point <code>--with-jtreg</code> to the <code>jtreg</code> directory that you just unpacked.</p>
<p>Building of Hotspot Gtest suite requires the source code of Google Test framework. The top directory, which contains both <code>googletest</code> and <code>googlemock</code> directories, should be specified via <code>--with-gtest</code>. The supported version of Google Test is 1.8.1, whose source code can be obtained:</p>
<ul>
<li>by downloading and unpacking the source bundle from <ahref="https://github.com/google/googletest/releases/tag/release-1.8.1">here</a></li>
<li>or by checking out <code>release-1.8.1</code> tag of <code>googletest</code> project: <code>git clone -b release-1.8.1 https://github.com/google/googletest</code></li>
</ul>
<p>To execute the most basic tests (tier 1), use:</p>
<pre><code>make run-test-tier1</code></pre>
<p>For more details on how to run tests, please see the <ahref="testing.html">Testing the JDK</a> document.</p>
@@ -768,6 +697,15 @@ ls build/linux-aarch64-normal-server-release/</code></pre>
<p>Additional architectures might be supported by Debian/Ubuntu Ports.</p>
<h3id="building-for-armaarch64">Building for ARM/aarch64</h3>
<p>A common cross-compilation target is the ARM CPU. When building for ARM, it is useful to set the ABI profile. A number of pre-defined ABI profiles are available using <code>--with-abi-profile</code>: arm-vfp-sflt, arm-vfp-hflt, arm-sflt, armv5-vfp-sflt, armv6-vfp-hflt. Note that soft-float ABIs are no longer properly supported by the JDK.</p>
<h3id="building-for-musl">Building for musl</h3>
<p>Just like it's possible to cross-compile for a different CPU, it's possible to cross-compile for musl libc on a glibc-based <em>build</em> system. A devkit suitable for most target CPU architectures can be obtained from <ahref="https://musl.cc">musl.cc</a>. After installing the required packages in the sysroot, configure the build with <code>--openjdk-target</code>:</p>
<h3id="verifying-the-build">Verifying the Build</h3>
<p>The build will end up in a directory named like <code>build/linux-arm-normal-server-release</code>.</p>
<p>Inside this build output directory, the <code>images/jdk</code> will contain the newly built JDK, for your <em>target</em> system.</p>
@@ -865,9 +803,6 @@ Clock skew detected. Your build may be incomplete.</code></pre>
<p>then the clock on your build machine is out of sync with the timestamps on the source files. Other errors, apparently unrelated but in fact caused by the clock skew, can occur along with the clock skew warnings. These secondary errors may tend to obscure the fact that the true root cause of the problem is an out-of-sync clock.</p>
<p>If you see these warnings, reset the clock on the build machine, run <code>make clean</code> and restart the build.</p>
<h4id="out-of-memory-errors">Out of Memory Errors</h4>
<p>On Solaris, you might get an error message like this:</p>
<pre><code>Trouble writing out table to disk</code></pre>
<p>To solve this, increase the amount of swap space on your build machine.</p>
<p>On Windows, you might get error messages like this:</p>
<p>If you are prepared to take some risk of an incorrect build, and know enough of the system to understand how things build and interact, you can speed up the build process considerably by instructing make to only build a portion of the product.</p>
<p>The safe way to use fine-grained make targets is to use the module specific make targets. All source code in the JDK is organized so it belongs to a module, e.g. <code>java.base</code> or <code>jdk.jdwp.agent</code>. You can build only a specific module, by giving it as make target: <code>make jdk.jdwp.agent</code>. If the specified module depends on other modules (e.g. <code>java.base</code>), those modules will be built first.</p>
<p>You can also specify a set of modules, just as you can always specify a set of make targets: <code>make jdk.crypto.cryptoki jdk.crypto.ec jdk.crypto.mscapi jdk.crypto.ucrypto</code></p>
<p>You can also specify a set of modules, just as you can always specify a set of make targets: <code>make jdk.crypto.cryptoki jdk.crypto.ec jdk.crypto.mscapi</code></p>
<p>The build process for each module is divided into separate phases. Not all modules need all phases. Which are needed depends on what kind of source code and other artifact the module consists of. The phases are:</p>
<p>This is a collection of rules, guidelines, and suggestions for writing HotSpot code. Following these will help new code fit in with existing HotSpot code, making it easier to read and maintain. Failure to follow these guidelines may lead to discussion during code reviews, if not outright rejection of a change.</p>
<h3id="why-care-about-style">Why Care About Style?</h3>
<p>Some programmers seem to have lexers and even C preprocessors installed directly behind their eyeballs. The rest of us require code that is not only functionally correct but also easy to read. More than that, since there is no one style for easy-to-read code, and since a mashup of many styles is just as confusing as no style at all, it is important for coders to be conscious of the many implicit stylistic choices that historically have gone into the HotSpot code base.</p>
<p>Some of these guidelines are driven by the cross-platform requirements for HotSpot. Shared code must work on a variety of platforms, and may encounter deficiencies in some. Using platform conditionalization in shared code is usually avoided, while shared code is strongly preferred to multiple platform-dependent implementations, so some language features may be recommended against.</p>
<p>Some of the guidelines here are relatively arbitrary choices among equally plausible alternatives. The purpose of stating and enforcing these rules is largely to provide a consistent look to the code. That consistency makes the code more readable by avoiding non-functional distractions from the interesting functionality.</p>
<p>When changing pre-existing code, it is reasonable to adjust it to match these conventions. Exception: If the pre-existing code clearly conforms locally to its own peculiar conventions, it is not worth reformatting the whole thing. Also consider separating changes that make extensive stylistic updates from those which make functional changes.</p>
<h3id="counterexamples-and-updates">Counterexamples and Updates</h3>
<p>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.</p>
<p>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.</p>
<p>Proposed changes should be discussed on the <ahref="mailto:hotspot-dev@openjdk.java.net">HotSpot Developers</a> mailing list, and approved by <ahref="https://en.wikipedia.org/wiki/Rough_consensus">rough consensus</a> of the <ahref="https://openjdk.java.net/census#hotspot">HotSpot Group</a> 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.</p>
<h2id="structure-and-formatting">Structure and Formatting</h2>
<h3id="factoring-and-class-design">Factoring and Class Design</h3>
<ul>
<li><p>Group related code together, so readers can concentrate on one section of one file.</p></li>
<li><p>Classes are the primary code structuring mechanism. Place related functionality in a class, or a set of related classes. Use of either namespaces or public non-member functions is rare in HotSpot code. Static non-member functions are not uncommon.</p></li>
<li><p>If a class <code>FooBar</code> is going to be used in more than one place, put it a file named fooBar.hpp and fooBar.cpp. If the class is a sidekick to a more important class <code>BazBat</code>, it can go in bazBat.hpp.</p></li>
<li><p>Put a member function <code>FooBar::bang</code> into the same file that defined <code>FooBar</code>, or its associated <em>.inline.hpp or </em>.cpp file.</p></li>
<li><p>Use public accessor functions for member variables accessed outside the class.</p></li>
<li><p>Assign names to constant literals and use the names instead.</p></li>
<li><p>Keep functions small, a screenful at most. Split out chunks of logic into file-local classes or static functions if needed.</p></li>
<li><p>Factor away nonessential complexity into local inline helper functions and helper classes.</p></li>
<li><p>Think clearly about internal invariants that apply to each class, and document them in the form of asserts within member functions.</p></li>
<li><p>Make simple, self-evident contracts for member functions. If you cannot communicate a simple contract, redesign the class.</p></li>
<li><p>Implement classes as if expecting rough usage by clients. Check for incorrect usage of a class using <code>assert(...)</code>, <code>guarantee(...)</code>, <code>ShouldNotReachHere()</code> and comments wherever needed. Performance is almost never a reason to omit asserts.</p></li>
<li><p>When possible, design as if for reusability. This forces a clear design of the class's externals, and clean hiding of its internals.</p></li>
<li><p>Initialize all variables and data structures to a known state. If a class has a constructor, initialize it there.</p></li>
<li><p>Do no optimization before its time. Prove the need to optimize.</p></li>
<li><p>When you must defactor to optimize, preserve as much structure as possible. If you must hand-inline some name, label the local copy with the original name.</p></li>
<li><p>If you need to use a hidden detail (e.g., a structure offset), name it (as a constant or function) in the class that owns it.</p></li>
<li><p>Don't use the Copy and Paste keys to replicate more than a couple lines of code. Name what you must repeat.</p></li>
<li><p>If a class needs a member function to change a user-visible attribute, the change should be done with a "setter" accessor matched to the simple "getter".</p></li>
</ul>
<h3id="source-files">Source Files</h3>
<ul>
<li><p>All source files must have a globally unique basename. The build system depends on this uniqueness.</p></li>
<li><p>Do not put non-trivial function implementations in .hpp files. If the implementation depends on other .hpp files, put it in a .cpp or a .inline.hpp file.</p></li>
<li><p>.inline.hpp files should only be included in .cpp or .inline.hpp files.</p></li>
<li><p>All .cpp files include precompiled.hpp as the first include line.</p></li>
<li><p>precompiled.hpp is just a build time optimization, so don't rely on it to resolve include problems.</p></li>
<li><p>Keep the include lines alphabetically sorted.</p></li>
<li><p>Put conditional inclusions (<code>#if ...</code>) at the end of the include list.</p></li>
</ul>
<h3id="jtreg-tests">JTReg Tests</h3>
<ul>
<li><p>JTReg tests should have meaningful names.</p></li>
<li><p>JTReg tests associated with specific bugs should be tagged with the <code>@bug</code> keyword in the test description.</p></li>
<li><p>JTReg tests should be organized by component or feature under <code>test/</code>, in a directory hierarchy that generally follows that of the <code>src/</code> directory. There may be additional subdirectories to further categorize tests by feature. This structure makes it easy to run a collection of tests associated with a specific feature by specifying the associated directory as the source of the tests to run.</p>
<ul>
<li>Some (older) tests use the associated bug number in the directory name, the test name, or both. That naming style should no longer be used, with existing tests using that style being candidates for migration.</li>
</ul></li>
</ul>
<h3id="naming">Naming</h3>
<ul>
<li><p>The length of a name may be correlated to the size of its scope. In particular, short names (even single letter names) may be fine in a small scope, but are usually inappropriate for larger scopes.</p></li>
<li><p>Prefer whole words rather than abbreviations, unless the abbreviation is more widely used than the long form in the code's domain.</p></li>
<li><p>Choose names consistently. Do not introduce spurious variations. Abbreviate corresponding terms to a consistent length.</p></li>
<li><p>Global names must be unique, to avoid <ahref="https://en.cppreference.com/w/cpp/language/definition"title="One Definition Rule">One Definition Rule</a> (ODR) violations. A common prefixing scheme for related global names is often used. (This is instead of using namespaces, which are mostly avoided in HotSpot.)</p></li>
<li><p>Don't give two names to the semantically same thing. But use different names for semantically different things, even if they are representationally the same. (So use meaningful <code>typedef</code> or template alias names where appropriate.)</p></li>
<li><p>When choosing names, avoid categorical nouns like "variable", "field", "parameter", "value", and verbs like "compute", "get". (<code>storeValue(int param)</code> is bad.)</p></li>
<li><p>Type names and global names should use mixed-case with the first letter of each word capitalized (<code>FooBar</code>).</p></li>
<li><p>Embedded abbreviations in otherwise mixed-case names are usually capitalized entirely rather than being treated as a single word with only the initial letter capitalized, e.g. "HTML" rather than "Html".</p></li>
<li><p>Function and local variable names use lowercase with words separated by a single underscore (<code>foo_bar</code>).</p></li>
<li><p>Class data member names have a leading underscore, and use lowercase with words separated by a single underscore (<code>_foo_bar</code>).</p></li>
<li><p>Constant names may be upper-case or mixed-case, according to historical necessity. (Note: There are many examples of constants with lowercase names.)</p></li>
<li><p>Constant names should follow an existing pattern, and must have a distinct appearance from other names in related APIs.</p></li>
<li><p>Class and type names should be noun phrases. Consider an "er" suffix for a class that represents an action.</p></li>
<li><p>Function names should be verb phrases that reflect changes of state known to a class's user, or else noun phrases if they cause no change of state visible to the class's user.</p></li>
<li><p>Getter accessor names are noun phrases, with no "<code>get_</code>" noise word. Boolean getters can also begin with "<code>is_</code>" or "<code>has_</code>". Member function for reading data members usually have the same name as the data member, exclusive of the leading underscore.</p></li>
<li><p>Setter accessor names prepend "<code>set_</code>" to the getter name.</p></li>
<li><p>Other member function names are verb phrases, as if commands to the receiver.</p></li>
<li><p>Avoid leading underscores (as "<code>_oop</code>") except in cases required above. (Names with leading underscores can cause portability problems.)</p></li>
</ul>
<h3id="commenting">Commenting</h3>
<ul>
<li><p>Clearly comment subtle fixes.</p></li>
<li><p>Clearly comment tricky classes and functions.</p></li>
<li><p>If you have to choose between commenting code and writing wiki content, comment the code. Link from the wiki to the source file if it makes sense.</p></li>
<li><p>As a general rule don't add bug numbers to comments (they would soon overwhelm the code). But if the bug report contains significant information that can't reasonably be added as a comment, then refer to the bug report.</p></li>
<li><p>Personal names are discouraged in the source code, which is a team product.</p></li>
</ul>
<h3id="macros">Macros</h3>
<ul>
<li><p>You can almost always use an inline function or class instead of a macro. Use a macro only when you really need it.</p></li>
<li><p>Templates may be preferable to multi-line macros. (There may be subtle performance effects with templates on some platforms; revert to macros if absolutely necessary.)</p></li>
<li><p><code>#ifdef</code>s should not be used to introduce platform-specific code into shared code (except for <code>_LP64</code>). They must be used to manage header files, in the pattern found at the top of every source file. They should be used mainly for major build features, including <code>PRODUCT</code>, <code>ASSERT</code>, <code>_LP64</code>, <code>INCLUDE_SERIALGC</code>, <code>COMPILER1</code>, etc.</p></li>
<li><p>For build features such as <code>PRODUCT</code>, use <code>#ifdef PRODUCT</code> for multiple-line inclusions or exclusions.</p></li>
<li><p>For short inclusions or exclusions based on build features, use macros like <code>PRODUCT_ONLY</code> and <code>NOT_PRODUCT</code>. But avoid using them with multiple-line arguments, since debuggers do not handle that well.</p></li>
<li><p>Use <code>CATCH</code>, <code>THROW</code>, etc. for HotSpot-specific exception processing.</p></li>
</ul>
<h3id="whitespace">Whitespace</h3>
<ul>
<li><p>In general, don't change whitespace unless it improves readability or consistency. Gratuitous whitespace changes will make integrations and backports more difficult.</p></li>
<li><p>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.</p></li>
<li><p>Indentation levels are two columns.</p></li>
<li><p>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.</p></li>
<li><p>Tabs are not allowed in code. Set your editor accordingly.<br> (Emacs: <code>(setq-default indent-tabs-mode nil)</code>.)</p></li>
<li><p>Use good taste to break lines and align corresponding tokens on adjacent lines.</p></li>
<li><p>Use spaces around operators, especially comparisons and assignments. (Relaxable for boolean expressions and high-precedence operators in classic math-style formulas.)</p></li>
<li><p>Put spaces on both sides of control flow keywords <code>if</code>, <code>else</code>, <code>for</code>, <code>switch</code>, etc. Don't add spaces around the associated <em>control</em> expressions. Examples:</p>
<pre><code>while (test_foo(args...)) { // Yes
while(test_foo(args...)) { // No, missing space after while
while ( test_foo(args...) ) { // No, excess spaces around control</code></pre></li>
<li><p>Use extra parentheses in expressions whenever operator precedence seems doubtful. Always use parentheses in shift/mask expressions (<code><<</code>, <code>&</code>, <code>|</code>). Don't add whitespace immediately inside parentheses.</p></li>
<li><p>Use more spaces and blank lines between larger constructs, such as classes or function definitions.</p></li>
<li><p>If the surrounding code has any sort of vertical organization, adjust new lines horizontally to be consistent with that organization. (E.g., trailing backslashes on long macro definitions often align.)</p></li>
</ul>
<h3id="miscellaneous">Miscellaneous</h3>
<ul>
<li><p>Use the <ahref="https://en.cppreference.com/w/cpp/language/raii"title="Resource Acquisition Is Initialization">Resource Acquisition Is Initialization</a> (RAII) design pattern to manage bracketed critical sections. See class <code>ResourceMark</code> for an example.</p></li>
<li>Avoid implicit conversions to <code>bool</code>.
<ul>
<li>Use <code>bool</code> for boolean values.</li>
<li>Do not use ints or pointers as (implicit) booleans with <code>&&</code>, <code>||</code>, <code>if</code>, <code>while</code>. Instead, compare explicitly, i.e. <code>if (x != 0)</code> or <code>if (ptr != nullptr)</code>, etc.</li>
<li>Do not use declarations in <em>condition</em> forms, i.e. don't use <code>if (T v = value) { ... }</code>.</li>
</ul></li>
<li><p>Use functions from globalDefinitions.hpp and related files when performing bitwise operations on integers. Do not code directly as C operators, unless they are extremely simple. (Examples: <code>align_up</code>, <code>is_power_of_2</code>, <code>exact_log2</code>.)</p></li>
<li><p>Use arrays with abstractions supporting range checks.</p></li>
<li><p>Always enumerate all cases in a switch statement or provide a default case. It is ok to have an empty default with comment.</p></li>
</ul>
<h2id="use-of-c-features">Use of C++ Features</h2>
<p>HotSpot was originally written in a subset of the C++98/03 language. More recently, support for C++14 is provided, though again, HotSpot only uses a subset. (Backports to JDK versions lacking support for more recent Standards must of course stick with the original C++98/03 subset.)</p>
<p>This section describes that subset. Features from the C++98/03 language may be used unless explicitly excluded here. Features from C++11 and C++14 may be explicitly permitted or explicitly excluded, and discussed accordingly here. There is a third category, undecided features, about which HotSpot developers have not yet reached a consensus, or perhaps have not discussed at all. Use of these features is also excluded.</p>
<p>(The use of some features may not be immediately obvious and may slip in anyway, since the compiler will accept them. The code review process is the main defense against this.)</p>
<p>Some features are discussed in their own subsection, typically to provide more extensive discussion or rationale for limitations. Features that don't have their own subsection are listed in omnibus feature sections for permitted, excluded, and undecided features.</p>
<p>Lists of new features for C++11 and C++14, along with links to their descriptions, can be found in the online documentation for some of the compilers and libraries. The C++14 Standard is the definitive description.</p>
<ul>
<li><ahref="https://gcc.gnu.org/projects/cxx-status.html">C++ Standards Support in GCC</a></li>
<li><ahref="https://clang.llvm.org/cxx_status.html">C++ Support in Clang</a></li>
<li><ahref="https://docs.microsoft.com/en-us/cpp/visual-cpp-language-conformance">Visual C++ Language Conformance</a></li>
<p>As a rule of thumb, permitting features which simplify writing code and, especially, reading code, is encouraged.</p>
<p>Similar discussions for some other projects:</p>
<ul>
<li><p><ahref="https://google.github.io/styleguide/cppguide.html">Google C++ Style Guide</a> — Currently (2020) targeting C++17.</p></li>
<li><p><ahref="https://chromium-cpp.appspot.com">C++11 and C++14 use in Chromium</a> — Categorizes features as allowed, banned, or to be discussed.</p></li>
<li><p><ahref="https://llvm.org/docs/CodingStandards.html">llvm Coding Standards</a> — Currently (2020) targeting C++14.</p></li>
<li><p><ahref="https://firefox-source-docs.mozilla.org/code-quality/coding-style/using_cxx_in_firefox_code.html">Using C++ in Mozilla code</a> — C++17 support is required for recent versions (2020).</p></li>
</ul>
<h3id="error-handling">Error Handling</h3>
<p>Do not use exceptions. Exceptions are disabled by the build configuration for some platforms.</p>
<p>Rationale: There is significant concern over the performance cost of exceptions and their usage model and implications for maintainable code. That's not just a matter of history that has been fixed; there remain questions and problems even today (2019). See, for example, <ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0709r0.pdf">Zero cost deterministic exceptions</a>. Because of this, HotSpot has always used a build configuration that disables exceptions where that is available. As a result, HotSpot code uses error handling mechanisms such as two-phase construction, factory functions, returning error codes, and immediate termination. Even if the cost of exceptions were not a concern, the existing body of code was not written with exception safety in mind. Making HotSpot exception safe would be a very large undertaking.</p>
<p>In addition to the usual alternatives to exceptions, HotSpot provides its own exception mechanism. This is based on a set of macros defined in utilities/exceptions.hpp.</p>
<h3id="rtti-runtime-type-information">RTTI (Runtime Type Information)</h3>
<p>Do not use <ahref="https://en.wikipedia.org/wiki/Run-time_type_information"title="Runtime Type Information">Runtime Type Information</a> (RTTI). <ahref="https://en.wikipedia.org/wiki/Run-time_type_information"title="Runtime Type Information">RTTI</a> is disabled by the build configuration for some platforms. Among other things, this means <code>dynamic_cast</code> cannot be used.</p>
<p>Rationale: Other than to implement exceptions (which HotSpot doesn't use), most potential uses of <ahref="https://en.wikipedia.org/wiki/Run-time_type_information"title="Runtime Type Information">RTTI</a> are better done via virtual functions. Some of the remainder can be replaced by bespoke mechanisms. The cost of the additional runtime data structures needed to support <ahref="https://en.wikipedia.org/wiki/Run-time_type_information"title="Runtime Type Information">RTTI</a> are deemed not worthwhile, given the alternatives.</p>
<h3id="memory-allocation">Memory Allocation</h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h3id="class-inheritance">Class Inheritance</h3>
<p>Use public single inheritance.</p>
<p>Prefer composition rather than non-public inheritance.</p>
<p>Restrict inheritance to the "is-a" case; use composition rather than non-is-a related inheritance.</p>
<p>Avoid multiple inheritance. Never use virtual inheritance.</p>
<h3id="namespaces">Namespaces</h3>
<p>Avoid using namespaces. HotSpot code normally uses "all static" classes rather than namespaces for grouping. An "all static" class is not instantiable, has only static members, and is normally derived (possibly indirectly) from the helper class <code>AllStatic</code>.</p>
<p>Benefits of using such classes include:</p>
<ul>
<li><p>Provides access control for members, which is unavailable with namespaces.</p></li>
<li><p>Closed for additional members. Namespaces allow names to be added in multiple contexts, making it harder to see the complete API.</p></li>
</ul>
<p>Namespaces should be used only in cases where one of those "benefits" is actually a hindrance.</p>
<p>In particular, don't use anonymous namespaces. They seem like they should be useful, and indeed have some real benefits for naming and generated code size on some platforms. Unfortunately, debuggers don't seem to like them at all.</p>
<p><ahref="https://groups.google.com/forum/#!topic/mozilla.dev.platform/KsaG3lEEaRM"class="uri">https://groups.google.com/forum/#!topic/mozilla.dev.platform/KsaG3lEEaRM</a><br> Suggests Visual Studio debugger might not be able to refer to anonymous namespace symbols, so can't set breakpoints in them. Though the discussion seems to go back and forth on that.</p>
<p><ahref="https://firefox-source-docs.mozilla.org/code-quality/coding-style/coding_style_cpp.html"class="uri">https://firefox-source-docs.mozilla.org/code-quality/coding-style/coding_style_cpp.html</a><br> Search for "Anonymous namespaces" Suggests preferring "static" to anonymous namespaces where applicable, because of poor debugger support for anonymous namespaces.</p>
<p><ahref="https://sourceware.org/bugzilla/show_bug.cgi?id=16874"class="uri">https://sourceware.org/bugzilla/show_bug.cgi?id=16874</a><br> Bug for similar gdb problems.</p>
<h3id="c-standard-library">C++ Standard Library</h3>
<p>Avoid using the C++ Standard Library.</p>
<p>Historically, HotSpot has mostly avoided use of the Standard Library.</p>
<p>(It used to be impossible to use most of it in shared code, because the build configuration for Solaris with Solaris Studio made all but a couple of pieces inaccessible. Support for header-only parts was added in mid-2017. Support for Solaris was removed in 2020.)</p>
<p>Some reasons for this include</p>
<ul>
<li><p>Exceptions. Perhaps the largest core issue with adopting the use of Standard Library facilities is exceptions. HotSpot does not use exceptions and, for platforms which allow doing so, builds with them turned off. Many Standard Library facilities implicitly or explicitly use exceptions.</p></li>
<li><p><code>assert</code>. An issue that is quickly encountered is the <code>assert</code> macro name collision (<ahref="https://bugs.openjdk.java.net/browse/JDK-8007770">JDK-8007770</a>). Some mechanism for addressing this would be needed before much of the Standard Library could be used. (Not all Standard Library implementations use assert in header files, but some do.)</p></li>
<li><p>Memory allocation. HotSpot requires explicit control over where allocations occur. The C++98/03 <code>std::allocator</code> class is too limited to support our usage. (Changes in more recent Standards may remove this limitation.)</p></li>
<li><p>Implementation vagaries. Bugs, or simply different implementation choices, can lead to different behaviors among the various Standard Libraries we need to deal with.</p></li>
<li><p>Inconsistent naming conventions. HotSpot and the C++ Standard use different naming conventions. The coexistence of those different conventions might appear jarring and reduce readability.</p></li>
</ul>
<p>There are a few exceptions to this rule.</p>
<ul>
<li><code>#include <new></code> to use placement <code>new</code>, <code>std::nothrow</code>, and <code>std::nothrow_t</code>.</li>
<li><code>#include <limits></code> to use <code>std::numeric_limits</code>.</li>
<li><code>#include <cstddef></code> to use <code>std::nullptr_t</code>.</li>
</ul>
<p>TODO: Rather than directly #including (permitted) Standard Library headers, use a convention of #including wrapper headers (in some location like hotspot/shared/stdcpp). This provides a single place for dealing with issues we might have for any given header, esp. platform-specific issues.</p>
<h3id="type-deduction">Type Deduction</h3>
<p>Use type deduction only if it makes the code clearer or safer. Do not use it merely to avoid the inconvenience of writing an explicit type, unless that type is itself difficult to write. An example of the latter is a function template return type that depends on template parameters in a non-trivial way.</p>
<p>There are several contexts where types are deduced.</p>
<ul>
<li><p>Function argument deduction. This is always permitted, and indeed encouraged. It is nearly always better to allow the type of a function template argument to be deduced rather than explicitly specified.</p></li>
<li><p><code>auto</code> variable declarations (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf">n1984</a>)<br> For local variables, this can be used to make the code clearer by eliminating type information that is obvious or irrelevant. Excessive use can make code much harder to understand.</p></li>
<li><p>Function return type deduction (<ahref="https://isocpp.org/files/papers/N3638.html">n3638</a>)<br> Only use if the function body has a very small number of <code>return</code> statements, and generally relatively little other code.</p></li>
<li><p>Generic lambdas. Lambdas are not (yet) permitted.</p></li>
<li><p>Lambda init captures. Lambdas are not (yet) permitted.</p></li>
</ul>
<h3id="expression-sfinae">Expression SFINAE</h3>
<p><ahref="https://en.cppreference.com/w/cpp/language/sfinae"title="Substitution Failure Is Not An Error">Substitution Failure Is Not An Error</a> (SFINAE) is a template metaprogramming technique that makes use of template parameter substitution failures to make compile-time decisions.</p>
<p>C++11 relaxed the rules for what constitutes a hard-error when attempting to substitute template parameters with template arguments, making most deduction errors be substitution errors; see (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2634.html">n2634</a>). This makes <ahref="https://en.cppreference.com/w/cpp/language/sfinae"title="Substitution Failure Is Not An Error">SFINAE</a> more powerful and easier to use. However, the implementation complexity for this change is significant, and this seems to be a place where obscure corner-case bugs in various compilers can be found. So while this feature can (and indeed should) be used (and would be difficult to avoid), caution should be used when pushing to extremes.</p>
<p>Here are a few closely related example bugs:<br><ahref="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95468"class="uri">https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95468</a><br><ahref="https://developercommunity.visualstudio.com/content/problem/396562/sizeof-deduced-type-is-sometimes-not-a-constant-ex.html"class="uri">https://developercommunity.visualstudio.com/content/problem/396562/sizeof-deduced-type-is-sometimes-not-a-constant-ex.html</a></p>
<h3id="enum">enum</h3>
<p>Where appropriate, <em>scoped-enums</em> should be used. (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2347.pdf">n2347</a>)</p>
<p>Use of <em>unscoped-enums</em> is permitted, though ordinary constants may be preferable when the automatic initializer feature isn't used.</p>
<p>The underlying type (the <em>enum-base</em>) of an unscoped enum type should always be specified explicitly. When unspecified, the underlying type is dependent on the range of the enumerator values and the platform.</p>
<p>The underlying type of a <em>scoped-enum</em> should also be specified explicitly if conversions may be applied to values of that type.</p>
<p>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.</p>
<h3id="thread_local">thread_local</h3>
<p>Do not use <code>thread_local</code> (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2659.htm">n2659</a>); instead, use the HotSpot macro <code>THREAD_LOCAL</code>. The initializer must be a constant expression.</p>
<p>As was discussed in the review for <ahref="https://mail.openjdk.java.net/pipermail/hotspot-dev/2019-September/039487.html">JDK-8230877</a>, <code>thread_local</code> allows dynamic initialization and destruction semantics. However, that support requires a run-time penalty for references to non-function-local <code>thread_local</code> 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.</p>
<h3id="nullptr">nullptr</h3>
<p>Prefer <code>nullptr</code> (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2431.pdf">n2431</a>) to <code>NULL</code>. Don't use (constexpr or literal) 0 for pointers.</p>
<p>For historical reasons there are widespread uses of both <code>NULL</code> and of integer 0 as a pointer value.</p>
<h3id="atomic"><atomic></h3>
<p>Do not use facilities provided by the <code><atomic></code> header (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2427.html">n2427</a>), (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2752.htm">n2752</a>); instead, use the HotSpot <code>Atomic</code> class and related facilities.</p>
<p>Atomic operations in HotSpot code must have semantics which are consistent with those provided by the JDK's compilers for Java. There are platform-specific implementation choices that a C++ compiler might make or change that are outside the scope of the C++ Standard, and might differ from what the Java compilers implement.</p>
<p>In addition, HotSpot <code>Atomic</code> has a concept of "conservative" memory ordering, which may differ from (may be stronger than) sequentially consistent. There are algorithms in HotSpot that are believed to rely on that ordering.</p>
<li><p>Default template arguments for function templates (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#226">CWG D226</a>)</p></li>
<li><p>Defaulted and deleted functions (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">n2346</a>)</p></li>
<li><p>Dynamic initialization and destruction with concurrency (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2660.htm">n2660</a>)</p></li>
<li><p><code>final</code> virtual specifiers for classes and virtual functions (<ahref="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm">n2928</a>), (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm">n3206</a>), (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm">n3272</a>)</p></li>
<li><p>Local and unnamed types as template parameters (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm">n2657</a>)</p></li>
</ul>
<h3id="excluded-features">Excluded Features</h3>
<ul>
<li>New string and character literals
<ul>
<li>New character types (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2249.html">n2249</a>)</li>
<li>Universal character name literals (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2170.html">n2170</a>)</li>
</ul>
<p>HotSpot doesn't need any of the new character and string literal types.</p></li>
<li><p>User-defined literals (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf">n2765</a>) — User-defined literals should not be added casually, but only through a proposal to add a specific UDL.</p></li>
<li><p>Inline namespaces (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2535.htm">n2535</a>) — HotSpot makes very limited use of namespaces.</p></li>
<li><p><code>using namespace</code> directives. In particular, don't use <code>using namespace std;</code> to avoid needing to qualify Standard Library names.</p></li>
<li><p>Propagating exceptions (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2179.html">n2179</a>) — HotSpot does not permit the use of exceptions, so this feature isn't useful.</p></li>
<li><p>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.</p></li>
<li><p><code>[[deprecated]]</code> attribute (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html">n3760</a>) — Not relevant in HotSpot code.</p></li>
<li><p>Avoid most operator overloading, preferring named functions. When operator overloading is used, ensure the semantics conform to the normal expected behavior of the operation.</p></li>
<li><p>Avoid most implicit conversion constructors and (implicit or explicit) conversion operators. (Note that conversion to <code>bool</code> isn't needed in HotSpot code because of the "no implicit boolean" guideline.)</p></li>
<p>The purpose of these guidelines is to establish a shared vision on what kind of native tests and how we want to develop them for Hotspot using GoogleTest. Hence these guidelines include style items as well as test approach items.</p>
<p>First section of this document describes properties of good tests which are common for almost all types of test regardless of language, framework, etc. Further sections provide recommendations to achieve those properties and other HotSpot and/or GoogleTest specific guidelines.</p>
<h2id="good-test-properties">Good test properties</h2>
<h3id="lightness">Lightness</h3>
<p>Use the most lightweight type of tests.</p>
<p>In Hotspot, there are 3 different types of tests regarding their dependency on a JVM, each next level is slower than previous</p>
<ul>
<li><p><code>TEST</code> : a test does not depend on a JVM</p></li>
<li><p><code>TEST_VM</code> : a test does depend on an initialized JVM, but are supposed not to break a JVM, i.e. leave it in a workable state.</p></li>
<li><p><code>TEST_OTHER_VM</code> : a test depends on a JVM and requires a freshly initialized JVM or leaves a JVM in non-workable state</p></li>
</ul>
<h3id="isolation">Isolation</h3>
<p>Tests have to be isolated: not to have visible side-effects, influences on other tests results.</p>
<p>Results of one test should not depend on test execution order, other tests, otherwise it is becoming almost impossible to find out why a test failed. Due to hotspot-specific, it is not so easy to get a full isolation, e.g. we share an initialized JVM between all <code>TEST_VM</code> tests, so if your test changes JVM's state too drastically and does not change it back, you had better consider <code>TEST_OTHER_VM</code>.</p>
<h3id="atomicity-and-self-containment">Atomicity and self-containment</h3>
<p>Tests should be <em>atomic</em> and <em>self-contained</em> at the same time.</p>
<p>One test should check a particular part of a class, subsystem, functionality, etc. Then it is quite easy to determine what parts of a product are broken basing on test failures. On the other hand, a test should test that part more-or-less entirely, because when one sees a test <code>FooTest::bar</code>, they assume all aspects of bar from <code>Foo</code> are tested.</p>
<p>However, it is impossible to cover all aspects even of a method, not to mention a subsystem. In such cases, it is recommended to have several tests, one for each aspect of a thing under test. For example one test to tests how <code>Foo::bar</code> works if an argument is <code>null</code>, another test to test how it works if an argument is acceptable but <code>Foo</code> is not in the right state to accept it and so on. This helps not only to make tests atomic, self-contained but also makes test name self-descriptive (discussed in more details in <ahref="#test-names">Test names</a>).</p>
<h3id="repeatability">Repeatability</h3>
<p>Tests have to be repeatable.</p>
<p>Reproducibility is very crucial for a test. No one likes sporadic test failures, they are hard to investigate, fix and verify a fix.</p>
<p>In some cases, it is quite hard to write a 100% repeatable test, since besides a test there can be other moving parts, e.g. in case of <code>TEST_VM</code> there are several concurrently running threads. Despite this, we should try to make a test as reproducible as possible.</p>
<h3id="informativeness">Informativeness</h3>
<p>In case of a failure, a test should be as <em>informative</em> as possible.</p>
<p>Having more information about a test failure than just compared values can be very useful for failure troubleshooting, it can reduce or even completely eliminate debugging hours. This is even more important in case of not 100% reproducible failures.</p>
<p>Achieving this property, one can easily make a test too verbose, so it will be really hard to find useful information in the ocean of useless information. Hence they should not only think about how to provide <ahref="#error-messages">good information</a>, but also <ahref="#uncluttered-output">when to do it</a>.</p>
<h3id="testing-instead-of-visiting">Testing instead of visiting</h3>
<p>Tests should <em>test</em>.</p>
<p>It is not enough just to "visit" some code, a test should check that code does that it has to do, compare return values with expected values, check that desired side effects are done, and undesired are not, and so on. In other words, a test should contain at least one GoogleTest assertion and do not rely on JVM asserts.</p>
<p>Generally speaking to write a good test, one should create a model of the system under tests, a model of possible bugs (or bugs which one wants to find) and design tests using those models.</p>
<h3id="nearness">Nearness</h3>
<p>Prefer having checks inside test code.</p>
<p>Not only does having test logic outside, e.g. verification method, depending on asserts in product code contradict with several items above but also decreases test’s readability and stability. It is much easier to understand that a test is testing when all testing logic is located inside a test or nearby in shared test libraries. As a rule of thumb, the closer a check to a test, the better.</p>
<h2id="asserts">Asserts</h2>
<h3id="several-checks">Several checks</h3>
<p>Prefer <code>EXPECT</code> over <code>ASSERT</code> if possible.</p>
<p>This is related to the <ahref="#informativeness">informativeness</a> property of tests, information for other checks can help to better localize a defect’s root-cause. One should use <code>ASSERT</code> if it is impossible to continue test execution or if it does not make much sense. Later in the text, <code>EXPECT</code> forms will be used to refer to both <code>ASSERT/EXPECT</code>.</p>
<p>When it is possible to make several different checks, but impossible to continue test execution if at least one check fails, you can use <code>::testing::Test::HasNonfatalFailure()</code> function. The recommended way to express that is <code>ASSERT_FALSE(::testing::Test::HasNonfatalFailure())</code>. Besides making it clear why a test is aborted, it also allows you to provide more information about a failure.</p>
<h3id="first-parameter-is-expected-value">First parameter is expected value</h3>
<p>In all equality assertions, expected values should be passed as the first parameter.</p>
<p>This convention is adopted by GoogleTest, and there is a slight difference in how GoogleTest treats parameters, the most important one is <code>null</code> detection. Due to different reasons, <code>null</code> detection is enabled only for the first parameter, that is to said <code>EXPECT_EQ(NULL, object)</code> checks that object is <code>null</code>, while <code>EXPECT_EQ(object, NULL)</code> checks that object equals to <code>NULL</code>, GoogleTest is very strict regarding types of compared values so the latter will generates a compile-time error.</p>
<p>Use floating-point special macros to compare <code>float/double</code> values.</p>
<p>Because of floating-point number representations and round-off errors, regular equality comparison will not return true in most cases. There are special <code>EXPECT_FLOAT_EQ/EXPECT_DOUBLE_EQ</code> assertions which check that the distance between compared values is not more than 4 ULPs, there is also <code>EXPECT_NEAR(v1, v2, eps)</code> which checks that the absolute value of the difference between <code>v1</code> and <code>v2</code> is not greater than <code>eps</code>.</p>
<p>Use string special macros for C strings comparisons.</p>
<p><code>EXPECT_EQ</code> just compares pointers’ values, which is hardly what one wants comparing C strings. GoogleTest provides <code>EXPECT_STREQ</code> and <code>EXPECT_STRNE</code> macros to compare C string contents. There are also case-insensitive versions <code>EXPECT_STRCASEEQ</code>, <code>EXPECT_STRCASENE</code>.</p>
<h3id="error-messages">Error messages</h3>
<p>Provide informative, but not too verbose error messages.</p>
<p>All GoogleTest asserts print compared expressions and their values, so there is no need to have them in error messages. Asserts print only compared values, they do not print any of interim variables, e.g. <code>ASSERT_TRUE((val1 == val2 && isFail(foo(8)) || i == 18)</code> prints only one value. If you use some complex predicates, please consider <code>EXPECT_PRED*</code> or <code>EXPECT_FORMAT_PRED</code> assertions family, they check that a predicate returns true/success and print out all parameters values.</p>
<p>However in some cases, default information is not enough, a commonly used example is an assert inside a loop, GoogleTest will not print iteration values (unless it is an assert's parameter). Other demonstrative examples are printing error code and a corresponding error message; printing internal states which might have an impact on results. One should add this information to assert message using <code><<</code> operator.</p>
<p>Too verbose tests which print all information even if they pass are very bad practice. They just pollute output, so it becomes harder to find useful information. In order not print information till it is really needed, one should consider saving it to a temporary buffer and pass to an assert. <ahref="https://hg.openjdk.java.net/jdk/jdk/file/tip/test/hotspot/gtest/gc/shared/test_memset_with_concurrent_readers.cpp"class="uri">https://hg.openjdk.java.net/jdk/jdk/file/tip/test/hotspot/gtest/gc/shared/test_memset_with_concurrent_readers.cpp</a> has a good example how to do that.</p>
<p>Wrap a subroutine call into <code>EXPECT_NO_FATAL_FAILURE</code> macro to propagate failures.</p>
<p><code>ASSERT</code> and <code>FAIL</code> abort only the current function, so if you have them in a subroutine, a test will not be aborted after the subroutine even if <code>ASSERT</code> or <code>FAIL</code> fails. You should call such subroutines in <code>ASSERT_NO_FATAL_FAILURE</code> macro to propagate fatal failures and abort a test. <code>(EXPECT|ASSERT)_NO_FATAL_FAILURE</code> can also be used to provide more information.</p>
<p>Due to obvious reasons, there are no <code>(EXPECT|ASSERT)_NO_NONFATAL_FAILURE</code> macros. However, if you need to check if a subroutine generated a nonfatal failure (failed an <code>EXPECT</code>), you can use <code>::testing::Test::HasNonfatalFailure</code> function, or <code>::testing::Test::HasFailure</code> function to check if a subroutine generated any failures, see <ahref="#several-checks">Several checks</a>.</p>
<h2id="naming-and-grouping">Naming and Grouping</h2>
<h3id="test-group-names">Test group names</h3>
<p>Test group names should be in CamelCase, start and end with a letter. A test group should be named after tested class, functionality, subsystem, etc.</p>
<p>This naming scheme helps to find tests, filter them and simplifies test failure analysis. For example, class <code>Foo</code> - test group <code>Foo</code>, compiler logging subsystem - test group <code>CompilerLogging</code>, G1 GC — test group <code>G1GC</code>, and so forth.</p>
<h3id="filename">Filename</h3>
<p>A test file must have <code>test_</code> prefix and <code>.cpp</code> suffix.</p>
<p>Both are actually requirements from the current build system to recognize your tests.</p>
<h3id="file-location">File location</h3>
<p>Test file location should reflect a location of the tested part of the product.</p>
<ul>
<li><p>All unit tests for a class from <code>foo/bar/baz.cpp</code> should be placed <code>foo/bar/test_baz.cpp</code> in <code>hotspot/test/native/</code> directory. Having all tests for a class in one file is a common practice for unit tests, it helps to see all existing tests at once, share functions and/or resources without losing encapsulation.</p></li>
<li><p>For tests which test more than one class, directory hierarchy should be the same as product hierarchy, and file name should reflect the name of the tested subsystem/functionality. For example, if a sub-system under tests belongs to <code>gc/g1</code>, tests should be placed in <code>gc/g1</code> directory.</p></li>
</ul>
<p>Please note that framework prepends directory name to a test group name. For example, if <code>TEST(foo, check_this)</code> and <code>TEST(bar, check_that)</code> are defined in <code>hotspot/test/native/gc/shared/test_foo.cpp</code> file, they will be reported as <code>gc/shared/foo::check_this</code> and <code>gc/shared/bar::check_that</code>.</p>
<h3id="test-names">Test names</h3>
<p>Test names should be in small_snake_case, start and end with a letter. A test name should reflect that a test checks.</p>
<p>Such naming makes tests self-descriptive and helps a lot during the whole test life cycle. It is easy to do test planning, test inventory, to see what things are not tested, to review tests, to analyze test failures, to evolve a test, etc. For example <code>foo_return_0_if_name_is_null</code> is better than <code>foo_sanity</code> or <code>foo_basic</code> or just <code>foo</code>, <code>humongous_objects_can_not_be_moved_by_young_gc</code> is better than <code>ho_young_gc</code>.</p>
<p>Actually using underscore is against GoogleTest project convention, because it can lead to illegal identifiers, however, this is too strict. Restricting usage of underscore for test names only and prohibiting test name starts or ends with an underscore are enough to be safe.</p>
<h3id="fixture-classes">Fixture classes</h3>
<p>Fixture classes should be named after tested classes, subsystems, etc (follow <ahref="#test-group-names">Test group names rule</a>) and have <code>Test</code> suffix to prevent class name conflicts.</p>
<h3id="friend-classes">Friend classes</h3>
<p>All test purpose friends should have either <code>Test</code> or <code>Testable</code> suffix.</p>
<p>It greatly simplifies understanding of friendship’s purpose and allows statically check that private members are not exposed unexpectedly. Having <code>FooTest</code> as a friend of <code>Foo</code> without any comments will be understood as a necessary evil to get testability.</p>
<h3id="oscpu-specific-tests">OS/CPU specific tests</h3>
<p>Guard OS/CPU specific tests by <code>#ifdef</code> and have OS/CPU name in filename.</p>
<p>For the time being, we do not support separate directories for OS, CPU, OS-CPU specific tests, in case we will have lots of such tests, we will change directory layout and build system to support that in the same way it is done in hotspot.</p>
<h2id="miscellaneous">Miscellaneous</h2>
<h3id="hotspot-style">Hotspot style</h3>
<p>Abide the norms and rules accepted in Hotspot style guide.</p>
<p>Tests are a part of Hotspot, so everything (if applicable) we use for Hotspot, should be used for tests as well. Those guidelines cover test-specific things.</p>
<h3id="codetest-metrics">Code/test metrics</h3>
<p>Coverage information and other code/test metrics are quite useful to decide what tests should be written, what tests should be improved and what can be removed.</p>
<p>For unit tests, widely used and well-known coverage metric is branch coverage, which provides good quality of tests with relatively easy test development process. For other levels of testing, branch coverage is not as good, and one should consider others metrics, e.g. transaction flow coverage, data flow coverage.</p>
<h3id="access-to-non-public-members">Access to non-public members</h3>
<p>Use explicit friend class to get access to non-public members.</p>
<p>We do not use GoogleTest macro to declare friendship relation, because, from our point of view, it is less clear than an explicit declaration.</p>
<p>Declaring a test fixture class as a friend class of a tested test is the easiest and the clearest way to get access. However, it has some disadvantages, here is some of them:</p>
<ul>
<li>Each test has to be declared as a friend</li>
<li>Subclasses do not inheritance friendship relation</li>
</ul>
<p>In other words, it is harder to share code between tests. Hence if you want to share code or expect it to be useful in other tests, you should consider making members in a tested class protected and introduce a shared test-only class which expose those members via public functions, or even making members publicly accessible right away in a product class. If it is not an option to change members visibility, one can create a friend class which exposes members.</p>
<h3id="death-tests">Death tests</h3>
<p>You can not use death tests inside <code>TEST_OTHER_VM</code> and <code>TEST_VM_ASSERT*</code>.</p>
<p>We tried to make Hotspot-GoogleTest integration as transparent as possible, however, due to the current implementation of <code>TEST_OTHER_VM</code> and <code>TEST_VM_ASSERT*</code> tests, you cannot use death test functionality in them. These tests are implemented as GoogleTest death tests, and GoogleTest does not allow to have a death test inside another death test.</p>
<h3id="external-flags">External flags</h3>
<p>Passing external flags to a tested JVM is not supported.</p>
<p>The rationality of such design decision is to simplify both tests and a test framework and to avoid failures related to incompatible flags combination till there is a good solution for that. However there are cases when one wants to test a JVM with specific flags combination, <code>_JAVA_OPTIONS</code> environment variable can be used to do that. Flags from <code>_JAVA_OPTIONS</code> will be used in <code>TEST_VM</code>, <code>TEST_OTHER_VM</code> and <code>TEST_VM_ASSERT*</code> tests.</p>
<p>Passing flags to a tested JVM in <code>TEST_OTHER_VM</code> and <code>TEST_VM_ASSERT*</code> should be possible, but is not implemented yet.</p>
<p>Facility to pass test-specific flags is needed for system, regression or other types of tests which require a fully initialized JVM in some particular configuration, e.g. with Serial GC selected. There is no support for such tests now, however, there is a plan to add that in upcoming releases.</p>
<p>For now, if a test depends on flags values, it should have <code>if (!<flag>) { return }</code> guards in the very beginning and <code>@requires</code> comment similar to jtreg <code>@requires</code> directive right before test macros. <ahref="https://hg.openjdk.java.net/jdk/jdk/file/tip/test/hotspot/gtest/gc/g1/test_g1IHOPControl.cpp"class="uri">https://hg.openjdk.java.net/jdk/jdk/file/tip/test/hotspot/gtest/gc/g1/test_g1IHOPControl.cpp</a> ha an example of this temporary workaround. It is important to follow that pattern as it allows us to easily find all such tests and update them as soon as there is an implementation of flag passing facility.</p>
<p>In long-term, we expect jtreg to support GoogleTest tests as first class citizens, that is to say, jtreg will parse <spanclass="citation"data-cites="requires">@requires</span> comments and filter out inapplicable tests.</p>
<h3id="flag-restoring">Flag restoring</h3>
<p>Restore changed flags.</p>
<p>It is quite common for tests to configure JVM in a certain way changing flags’ values. GoogleTest provides two ways to set up environment before a test and restore it afterward: using either constructor and destructor or <code>SetUp</code> and <code>TearDown</code> functions. Both ways require to use a test fixture class, which sometimes is too wordy. The simpler facilities like <code>FLAG_GUARD</code> macro or <code>*FlagSetting</code> classes could be used in such cases to restore/set values.</p>
<p>Caveats:</p>
<ul>
<li><p>Changing a flag’s value could break the invariants between flags' values and hence could lead to unexpected/unsupported JVM state.</p></li>
<li><p><code>FLAG_SET_*</code> macros can change more than one flag (in order to maintain invariants) so it is hard to predict what flags will be changed and it makes restoring all changed flags a nontrivial task. Thus in case one uses <code>FLAG_SET_*</code> macros, they should use <code>TEST_OTHER_VM</code> test type.</p></li>
<p>In case you have any questions regarding GoogleTest itself, its asserts, test declaration macros, other macros, etc, please consult its documentation.</p>
<h2id="todo">TODO</h2>
<p>Although this document provides guidelines on the most important parts of test development using GTest, it still misses a few items:</p>
<ul>
<li><p>Examples, esp for <ahref="#access-to-non-public-members">access to non-public members</a></p></li>
<li>test types: purpose, drawbacks, limitation
<ul>
<li><code>TEST_VM</code></li>
<li><code>TEST_VM_F</code></li>
<li><code>TEST_OTHER_VM</code></li>
<li><code>TEST_VM_ASSERT</code></li>
<li><code>TEST_VM_ASSERT_MSG</code></li>
</ul></li>
<li>Miscellaneous
<ul>
<li>Test libraries
<ul>
<li>where to place</li>
<li>how to write</li>
<li>how to use</li>
</ul></li>
<li>test your tests
<ul>
<li>how to run tests in random order</li>
<li>how to run only specific tests</li>
<li>how to run each test separately</li>
<li>check that a test can find bugs it is supposed to by introducing them</li>
</ul></li>
<li>mocks/stubs/dependency injection</li>
<li>setUp/tearDown
<ul>
<li>vs c-tor/d-tor</li>
<li>empty test to test them</li>
</ul></li>
<li>internal (declared in .cpp) struct/classes</li>
<divid="sharepage"class="smallpagetitle"><h1>Java Scripting Programmer's Guide</h1><divclass="sharepage"><divclass="sharepagew1 share-mailto"><tablesummary=""cellpadding="0"cellspacing="0"><tbody><tr><tdid="share-mailto"><ahref="mailto:?subject=Java%20Documentation%20Page:%20Java%20Scripting%20Programmer%27s%20Guide&body=Check%20out%20this%20page:%20%0A%0Ahttp%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html"class="sharelink mailto"title="Email this page to a friend"></a></td><tdid="share-technorati"><ahref="http://technorati.com/search/http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html"class="sharelink technorati"title="See who links to this page on Technorati"></a></td><tdid="share-delicious"><ahref="http://del.icio.us/post?v=4;url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html;title=Java%20Scripting%20Programmer%27s%20Guide"class="sharelink delicious"title="Bookmark this page in del.icio.us"></a></td><tdid="share-digg"><ahref="http://digg.com/submit?phase=2&url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html&title=Java%20Scripting%20Programmer%27s%20Guide"class="sharelink digg"title="Submit this page to Digg"></a></td><tdid="share-slashdot"><ahref="http://slashdot.org/bookmark.pl?title=Java%20Scripting%20Programmer%27s%20Guide&url=http%3A%2F%2Fdocs.oracle.com%2Fjavase%2F6%2Fdocs%2Ftechnotes%2Fguides%2Fscripting%2Fprogrammer_guide%2Findex.html"class="sharelink slashdot"title="Submit this page to Slashdot"></a></td><tdid="share-blank"></td></tr></tbody></table></div></div></div>
</td>
</tr>
</tbody></table>
<!-- Body text begins here -->
<ul>
<li><span><ahref="#who">Who is the Java Scripting API
<h2><span>Who is the Java Scripting API For?</span></h2>
<span>Some useful characteristics of scripting languages
are:</span>
<ul>
<li><span><b>Convenience</b>: Most scripting languages are
dynamically typed. You can usually create new variables without
declaring the variable type, and you can reuse variables to store
objects of different types. Also, scripting languages tend to
perform many type conversions automatically, for example,
converting the number 10 to the text "10" as necessary.</span></li>
<li><span><b>Developing rapid prototypes</b>: You can avoid the
edit-compile-run cycle and just use edit-run!</span></li>
<li><span><b>Application extension/customization</b>: You can
"externalize" parts of your application - like configuration
scripts, business logic/rules and math expressions for financial
applications.</span></li>
<li><span><b>"Command line" shells for applications</b> -for
debugging, runtime/deploy time configuration etc. Most applications
have a web-based GUI configuaration tool these days. But
sysadmins/deployers frequently prefer command line tools. Instead
of inventing ad-hoc scripting language for that purpose, a
"standard" scripting language can be used.</span></li>
</ul>
<p><span>The Java<fontsize="-1"><sup>TM</sup></font> Scripting API
is a scripting language indepedent framework for using script
engines from Java code. With the Java Scripting API, it is possible
to write customizable/extendable applications in the Java language
and leave the customization scripting language choice to the end
user. The Java application developer need not choose the extension
language during development. If you write your application with
JSR-223 API, then your users can use any JSR-223 compliant
scripting language.</span></p>
<hr>
<span><aname="package"id="package"></a></span>
<h2><span>Scripting Package</span></h2>
<p><span>The Java Scripting functionality is in the <code><ahref="http://docs.oracle.com/javase/9/docs/api/javax/script/package-summary.html">javax.script</a></code>
package. This is a relatively small, simple API. The starting point
of the scripting API is the <code>ScriptEngineManager</code> class.
A ScriptEngineManager object can discover script engines through
the jar file service discovery mechanism. It can also instantiate
ScriptEngine objects that interpret scripts written in a specific
scripting language. The simplest way to use the scripting API is as
follows:</span></p>
<ol>
<li><span>Create a <code>ScriptEngineManager</code>
object.</span></li>
<li><span>Get a <code>ScriptEngine</code> object from the
manager.</span></li>
<li><span>Evaluate script using the <code>ScriptEngine</code>'s
<code>eval</code> methods.</span></li>
</ol>
<p><span>Now, it is time to look at some sample code. While it is
not mandatory, it may be useful to know a bit of JavaScript to read
// execute the same script - but this time pass a different script context
engine.eval("print(x);", newContext);
// the above line prints "world"
}
}
</code>
</pre>
<hr>
<aname="jsengine"id="jsengine"></a>
<h2>JavaScript Script Engine</h2>
<p>Oracle's implementation of JDK 8 is co-bundled with the Nashorn ECMAScript
script engine.
<hr>
<aname="jstojava"id="jstojava"></a>
<h2>JavaScript to Java Communication</h2>
<p>For the most part, accessing Java classes, objects and methods
is straightforward. In particular field and method access from
JavaScript is the same as it is from Java. We highlight important
aspects of JavaScript Java access here.
The following examples are JavaScript snippets accessing Java. This
section requires knowledge of JavaScript. This section can be
skipped if you are planning to use some other JSR-223 scripting
language rather than JavaScript.</p>
<hr>
<aname="jsjavaclass"id=jsjavalass"></a>
<h3>Accessing Java Classes</h3>
<pre>
<code>
// <ahref="source/javatypes.js">javatypes.js</a>
var arrayListType = Java.type("java.util.ArrayList")
var intType = Java.type("int")
var stringArrayType = Java.type("java.lang.String[]")
var int2DArrayType = Java.type("int[][]")
</code>
</pre>
Note that the name of the type is always a string for a fully qualified name. You can use any of these expressions to create new instances, e.g.:
<pre><code>
var anArrayList = new (Java.type("java.util.ArrayList"))
</code></pre>
or
<pre><code>
var ArrayList = Java.type("java.util.ArrayList")
var anArrayList = new ArrayList
var anArrayListWithSize = new ArrayList(16)
</code></pre>
In the special case of inner classes, you can either use the JVM fully qualified name, meaning using the dollar sign in the class name, or you can use the dot:
<pre><code>
var ftype = Java.type("java.awt.geom.Arc2D$Float")
</code></pre>
and
<pre><code>
var ftype = Java.type("java.awt.geom.Arc2D.Float")
</code></pre>
both work. Note however that using the dollar sign is faster, as Java.type first tries to resolve the class name as it is originally specified, and the internal JVM names for inner classes use the dollar sign. If you use the dot, Java.type will internally get a ClassNotFoundException and subsequently retry by changing the last dot to dollar sign. As a matter of fact, it'll keep replacing dots with dollar signs until it either successfully loads the class or runs out of all dots in the name. This way it can correctly resolve and load even multiply nested inner classes with the dot notation. Again, this will be slower than using the dollar signs in the name. An alternative way to access the inner class is as a property of the outer class:
<pre><code>
var arctype = Java.type("java.awt.geom.Arc2D")
var ftype = arctype.Float
</code></pre>
<p>
You can access both static and non-static inner classes. If you want to create an instance of a non-static inner class, remember to pass an instance of its outer class as the first argument to the constructor.
</p>
<p>
In addition to creating new instances, the type objects returned from <code>Java.type</code> calls can also be used to access the
static fields and methods of the classes:
<pre><code>
var File = Java.type("java.io.File")
File.createTempFile("nashorn", ".tmp")
</code></pre>
<p>
Methods with names of the form <code>isXxx()</code>, <code>getXxx()</code>, and <code>setXxx()</code> can also be used as properties, for both instances and statics.
</p>
<p>
A type object returned from <code>Java.type</code> is distinct from a <code>java.lang.Class</code> object. You can obtain one from the other using properties <code>class</code> and <code>static</code> on them.
<pre><code>
var ArrayList = Java.type("java.util.ArrayList")
var a = new ArrayList
// All of the following print true:
print("Type acts as target of instanceof: " + (a instanceof ArrayList))
print("Class doesn't act as target of instanceof: " + !(a instanceof a.getClass()))
print("Type is not same as instance's getClass(): " + (a.getClass() !== ArrayList))
print("Type's `class` property is same as instance getClass(): " + (a.getClass() === ArrayList.class))
print("Type is same as instance getClass()'s `static` property: " + (a.getClass().static === ArrayList))
</code></pre>
<p>
You can think of the type object as similar to the class names as used in Java source code: you use them as the
arguments to the <code>new</code> and <code>instanceof</code> operators and as the namespace for the static fields
and methods, but they are different than the runtime <code>Class</code> objects returned by <code>getClass()</code> calls.
Syntactically and semantically, this separation produces code that is most similar to Java code, where a distinction
between compile-time class expressions and runtime class objects also exists. (Also, Java can't have the equivalent of <code>static</code>
property on a <code>Class</code> object since compile-time class expressions are never reified as objects).
</p>
<hr>
<aname="jsimport"id="jsimport"></a>
<h3>Importing Java Packages, Classes</h3>
<p>The built-in functions <code>importPackage</code> (in compatibility script) and
<code>importClass</code> can be used to import Java packages and
// create JavaImporter with specific packages and classes to import
var SwingGui = new <spanclass="functionref">JavaImporter</span>(javax.swing,
javax.swing.event,
javax.swing.border,
java.awt.event);
with (SwingGui) {
// within this 'with' statement, we can access Swing and AWT
// classes by unqualified (simple) names.
var mybutton = new JButton("test");
var myframe = new JFrame("test");
}
</code>
</pre>
<hr>
<aname="jsarrays"id="jsarrays"></a>
<h3>Creating, Converting and Using Java Arrays</h3>
<p>
Array element access or length access is the same as in Java.</p>
<pre><code>
// <ahref="source/javaarray.js">javaarray.js</a>
// create Java String array of 5 elements
var StringArray = Java.type("java.lang.String[]");
var a = new StringArray(5);
// Accessing elements and length access is by usual Java syntax
a[0] = "scripting is great!";
print(a.length);
print(a[0]);
</code>
</pre>
<p>
It is also possible to convert between JavaScript and Java arrays.
Given a JavaScript array and a Java type, <code>Java.to</code> returns a Java array with the same initial contents, and with the specified array type.
</p>
<pre><code>
var anArray = [1, "13", false]
var javaIntArray = Java.to(anArray, "int[]")
print(javaIntArray[0]) // prints 1
print(javaIntArray[1]) // prints 13, as string "13" was converted to number 13 as per ECMAScript ToNumber conversion
print(javaIntArray[2]) // prints 0, as boolean false was converted to number 0 as per ECMAScript ToNumber conversion
</code></pre>
<p>
You can use either a string or a type object returned from <code>Java.type()</code> to specify the type of the array.
You can also omit the array type, in which case a <code>Object[]</code> will be created.
</p>
<p>
Given a Java array or Collection, <code>Java.from</code> returns a JavaScript array with a shallow copy of its contents. Note that in most cases, you can use Java arrays and lists natively in Nashorn; in cases where for some reason you need to have an actual JavaScript native array (e.g. to work with the array comprehensions functions), you will want to use this method.
</p>
<pre><code>
var File = Java.type("java.io.File");
var listCurDir = new File(".").listFiles();
var jsList = Java.from(listCurDir);
print(jsList);
</code></pre>
<hr>
<aname="jsimplement"id="jsimplement"></a>
<h3>Implementing Java interfaces</h3>
<p>A Java interface can be implemented in JavaScript by using a
Java anonymous class-like syntax:</p>
<pre><code>
// <ahref="source/runnable.js">runnable.js</a>
var r = new java.lang.Runnable() {
run: function() {
print("running...\n");
}
};
// "r" can be passed to Java methods that expect java.lang.Runnable
var th = new java.lang.Thread(r);
th.start();
th.join();
</code>
</pre>
<p>When an interface with a single method is expected, you can pass
a script function directly.(auto conversion)</p>
<pre><code>
// <ahref="source/samfunc.js">samfunc.js</a>
function func() {
print("I am func!");
}
// pass script function for java.lang.Runnable argument
If a Java class is abstract, you can instantiate an anonymous subclass of it using an argument list that is applicable to any of its public or protected constructors, but inserting a JavaScript object with functions properties that provide JavaScript implementations of the abstract methods. If method names are overloaded, the JavaScript function will provide implementation for all overloads. E.g.:
</p>
<pre><code>
var TimerTask = Java.type("java.util.TimerTask")
var task = new TimerTask({ run: function() { print("Hello World!") } })
</code></pre>
Nashorn supports a syntactic extension where a "new" expression followed by an argument is identical to invoking the constructor and passing the argument to it, so you can write the above example also as:
<pre><code>
var task = new TimerTask {
run: function() {
print("Hello World!")
}
}
</code></pre>
which is very similar to Java anonymous inner class definition. On the other hand, if the type is an abstract type with a single abstract method (commonly referred to as a "SAM type") or all abstract methods it has share the same overloaded name), then instead of an object, you can just pass a function, so the above example can become even more simplified to:
<pre><code>
var task = new TimerTask(function() { print("Hello World!") })
</code></pre>
<p>
Note that in every one of these cases if you are trying to instantiate an abstract class that has constructors that take some arguments, you can invoke those simply by specifying the arguments after the initial implementation object or function.
</p>
<p>
The use of functions can be taken even further; if you are invoking a Java method that takes a SAM type, you can just pass in a function object, and Nashorn will know what you meant:
Here, <code>Timer.schedule()</code> expects a <code>TimerTask</code> as its argument, so Nashorn creates an instance of a TimerTask subclass and uses the passed function to implement its only abstract method, run(). In this usage though, you can't use non-default constructors; the type must be either an interface, or must have a protected or public no-arg constructor.
To extend a concrete Java class, you have to use <code>Java.extend</code> function.
<code>Java.extend</code> returns a type object for a subclass of the specified Java class (or implementation of the specified interface) that acts as a script-to-Java adapter for it.
<tdwidth="30%"><imgsrc="Java%20Scripting%20Programmer%27s%20Guide_files/logo_oracle_footer.gif"alt="Oracle and/or its affiliates"border="0"height="29"width="100"><br>
<fontsize="+1"><i>Java Technology</i></font></td>
<tdwidth="30%">
<p><fontsize="-2">
<ahref="http://docs.oracle.com/javase/6/docs/legal/cpyr.html">Copyright <20></a> 2013, Oracle and/or its affiliates. All rights reserved.
$ make test-only TEST="gtest:LogTagSet gtest:LogTagSetDescriptions" GTEST="REPEAT=-1"
$ make test TEST="hotspot:hotspot_gc" JTREG="JOBS=1;TIMEOUT_FACTOR=8;VM_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"
$ make test TEST="hotspot:hotspot_gc" JTREG="JOBS=1;TIMEOUT_FACTOR=8;JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"
$ make test TEST="jtreg:test/hotspot:hotspot_gc test/hotspot/jtreg/native_sanity/JniVersion.java"
$ make test TEST="micro:java.lang.reflect" MICRO="FORK=1;WARMUP_ITER=2"
$ make exploded-test TEST=tier2</code></pre>
@@ -106,8 +106,8 @@ TEST FAILURE</code></pre>
<h2id="test-suite-control">Test suite control</h2>
<p>It is possible to control various aspects of the test suites using make control variables.</p>
<p>These variables use a keyword=value approach to allow multiple values to be set. So, for instance, <code>JTREG="JOBS=1;TIMEOUT_FACTOR=8"</code> will set the JTReg concurrency level to 1 and the timeout factor to 8. This is equivalent to setting <code>JTREG_JOBS=1 JTREG_TIMEOUT_FACTOR=8</code>, but using the keyword format means that the <code>JTREG</code> variable is parsed and verified for correctness, so <code>JTREG="TMIEOUT_FACTOR=8"</code> would give an error, while <code>JTREG_TMIEOUT_FACTOR=8</code> would just pass unnoticed.</p>
<p>To separate multiple keyword=value pairs, use <code>;</code> (semicolon). Since the shell normally eats <code>;</code>, the recommended usage is to write the assignment inside qoutes, e.g. <code>JTREG="...;..."</code>. This will also make sure spaces are preserved, as in <code>JTREG="VM_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"</code>.</p>
<p>(Other ways are possible, e.g. using backslash: <code>JTREG=JOBS=1\;TIMEOUT_FACTOR=8</code>. Also, as a special technique, the string <code>%20</code> will be replaced with space for certain options, e.g. <code>JTREG=VM_OPTIONS=-XshowSettings%20-Xlog:gc+ref=debug</code>. This can be useful if you have layers of scripts and have trouble getting proper quoting of command line arguments through.)</p>
<p>To separate multiple keyword=value pairs, use <code>;</code> (semicolon). Since the shell normally eats <code>;</code>, the recommended usage is to write the assignment inside qoutes, e.g. <code>JTREG="...;..."</code>. This will also make sure spaces are preserved, as in <code>JTREG="JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"</code>.</p>
<p>(Other ways are possible, e.g. using backslash: <code>JTREG=JOBS=1\;TIMEOUT_FACTOR=8</code>. Also, as a special technique, the string <code>%20</code> will be replaced with space for certain options, e.g. <code>JTREG=JAVA_OPTIONS=-XshowSettings%20-Xlog:gc+ref=debug</code>. This can be useful if you have layers of scripts and have trouble getting proper quoting of command line arguments through.)</p>
<p>As far as possible, the names of the keywords have been standardized between test suites.</p>
<p>Some keywords are valid across different test suites. If you want to run tests from multiple test suites, or just don't want to care which test suite specific control variable to use, then you can use the general TEST_OPTS control variable.</p>
@@ -116,16 +116,16 @@ TEST FAILURE</code></pre>
<p>Currently only applies to JTReg.</p>
<h4id="timeout_factor">TIMEOUT_FACTOR</h4>
<p>Currently only applies to JTReg.</p>
<h4id="vm_options">VM_OPTIONS</h4>
<p>Applies to JTReg, GTest and Micro.</p>
<h4id="java_options">JAVA_OPTIONS</h4>
<p>Applies to JTReg, GTest and Micro.</p>
<h4id="vm_options">VM_OPTIONS</h4>
<p>Applies to JTReg, GTest and Micro.</p>
<h4id="aot_modules">AOT_MODULES</h4>
<p>Applies to JTReg and GTest.</p>
<h4id="jcov">JCOV</h4>
<p>This keywords applies globally to the test runner system. If set to <code>true</code>, it enables JCov coverage reporting for all tests run. To be useful, the JDK under test must be run with a JDK built with JCov instrumentation (<code>configure --with-jcov=<path to directory containing lib/jcov.jar></code>, <code>make jcov-image</code>).</p>
<p>The simplest way to run tests with JCov coverage report is to use the special target <code>jcov-test</code> instead of <code>test</code>, e.g. <code>make jcov-test TEST=jdk_lang</code>. This will make sure the JCov image is built, and that JCov reporting is enabled.</p>
<p>The JCov report is stored in <code>build/$BUILD/test-results/jcov-output</code>.</p>
<p>The JCov report is stored in <code>build/$BUILD/test-results/jcov-output/report</code>.</p>
<p>Please note that running with JCov reporting can be very memory intensive.</p>
<p>While collecting code coverage with JCov, it is also possible to find coverage for only recently changed code. JCOV_DIFF_CHANGESET specifies a source revision. A textual report will be generated showing coverage of the diff between the specified revision and the repository tip.</p>
@@ -133,10 +133,12 @@ TEST FAILURE</code></pre>
<h3id="jtreg-keywords">JTReg keywords</h3>
<h4id="jobs-1">JOBS</h4>
<p>The test concurrency (<code>-concurrency</code>).</p>
<p>Defaults to TEST_JOBS (if set by <code>--with-test-jobs=</code>), otherwise it defaults to JOBS, except for Hotspot, where the default is <em>number of CPU cores/2</em> (for sparc, if more than 16 cpus, then <em>number of CPU cores/5</em>, otherwise <em>number of CPU cores/4</em>), but never more than <em>memory size in GB/2</em>.</p>
<p>Defaults to TEST_JOBS (if set by <code>--with-test-jobs=</code>), otherwise it defaults to JOBS, except for Hotspot, where the default is <em>number of CPU cores/2</em>, but never more than <em>memory size in GB/2</em>.</p>
<p>Sets the argument <code>-timeoutHandlerTimeout</code> for JTReg. The default value is 0. This is only valid if the failure handler is built.</p>
<h4id="test_mode">TEST_MODE</h4>
<p>The test mode (<code>agentvm</code> or <code>othervm</code>).</p>
<p>Defaults to <code>agentvm</code>.</p>
@@ -153,8 +155,10 @@ TEST FAILURE</code></pre>
<p>Limit memory consumption (<code>-Xmx</code> and <code>-vmoption:-Xmx</code>, or none).</p>
<p>Limit memory consumption for JTReg test framework and VM under test. Set to 0 to disable the limits.</p>
<p>Defaults to 512m, except for hotspot, where it defaults to 0 (no limit).</p>
<h4id="max_output">MAX_OUTPUT</h4>
<p>Set the property <code>javatest.maxOutputSize</code> for the launcher, to change the default JTReg log limit.</p>
<h4id="keywords">KEYWORDS</h4>
<p>JTReg kewords sent to JTReg using <code>-k</code>. Please be careful in making sure that spaces and special characters (like <code>!</code>) are properly quoted. To avoid some issues, the special value <code>%20</code> can be used instead of space.</p>
<p>JTReg keywords sent to JTReg using <code>-k</code>. Please be careful in making sure that spaces and special characters (like <code>!</code>) are properly quoted. To avoid some issues, the special value <code>%20</code> can be used instead of space.</p>
<p>Use additional problem lists file or files, in addition to the default ProblemList.txt located at the JTReg test roots.</p>
<p>If multiple file names are specified, they should be separated by space (or, to help avoid quoting issues, the special value <code>%20</code>).</p>
@@ -166,9 +170,12 @@ TEST FAILURE</code></pre>
<p>Additional options to the JTReg test framework.</p>
<p>Use <code>JTREG="OPTIONS=--help all"</code> to see all available JTReg options.</p>
<h4id="java_options-1">JAVA_OPTIONS</h4>
<p>Additional Java options to JTReg (<code>-javaoption</code>).</p>
<p>Additional Java options for running test classes (sent to JTReg as <code>-javaoption</code>).</p>
<h4id="vm_options-1">VM_OPTIONS</h4>
<p>Additional VM options to JTReg (<code>-vmoption</code>).</p>
<p>Additional Java options to be used when compiling and running classes (sent to JTReg as <code>-vmoption</code>).</p>
<p>This option is only needed in special circumstances. To pass Java options to your test classes, use <code>JAVA_OPTIONS</code>.</p>
<h4id="launcher_options">LAUNCHER_OPTIONS</h4>
<p>Additional Java options that are sent to the java launcher that starts the JTReg harness.</p>
<h4id="aot_modules-1">AOT_MODULES</h4>
<p>Generate AOT modules before testing for the specified module, or set of modules. If multiple modules are specified, they should be separated by space (or, to help avoid quoting issues, the special value <code>%20</code>).</p>
<h4id="retry_count">RETRY_COUNT</h4>
@@ -204,14 +211,19 @@ TEST FAILURE</code></pre>
<p>Docker tests with default parameters may fail on systems with glibc versions not compatible with the one used in the default docker image (e.g., Oracle Linux 7.6 for x86). For example, they pass on Ubuntu 16.04 but fail on Ubuntu 18.04 if run like this on x86:</p>
<pre><code>$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"</code></pre>
<p>To run these tests correctly, additional parameters for the correct docker image are required on Ubuntu 18.04 by using <code>JAVA_OPTIONS</code>.</p>
<pre><code>$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"JTREG="JAVA_OPTIONS=-Djdk.test.docker.image.name=ubuntu -Djdk.test.docker.image.version=latest"</code></pre>
<pre><code>$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"\
<p>If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting <code>LANG="en_US"</code> in the environment before running tests should work. On Windows, setting <code>JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"</code> helps for most, but not all test cases. For example:</p>
<p>If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting <code>LANG="en_US"</code> in the environment before running tests should work. On Windows, setting <code>JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"</code> helps for most, but not all test cases.</p>
<p>For example:</p>
<pre><code>$ export LANG="en_US"&& make test TEST=...
$ make test JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US" TEST=...</code></pre>
<h3id="pkcs11-tests">PKCS11 Tests</h3>
<p>It is highly recommended to use the latest NSS version when running PKCS11 tests. Improper NSS version may lead to unexpected failures which are hard to diagnose. For example, sun/security/pkcs11/Secmod/AddTrustedCert.java may fail on Ubuntu 18.04 with the default NSS version in the system. To run these tests correctly, the system property <code>test.nss.lib.paths</code> is required on Ubuntu 18.04 to specify the alternative NSS lib directories. For example:</p>
<pre><code>$ make test TEST="jtreg:sun/security/pkcs11/Secmod/AddTrustedCert.java" JTREG="JAVA_OPTIONS=-Dtest.nss.lib.paths=/path/to/your/latest/NSS-libs"</code></pre>
<p>It is highly recommended to use the latest NSS version when running PKCS11 tests. Improper NSS version may lead to unexpected failures which are hard to diagnose. For example, sun/security/pkcs11/Secmod/AddTrustedCert.java may fail on Ubuntu 18.04 with the default NSS version in the system. To run these tests correctly, the system property <code>test.nss.lib.paths</code> is required on Ubuntu 18.04 to specify the alternative NSS lib directories.</p>
<p>For example:</p>
<pre><code>$ make test TEST="jtreg:sun/security/pkcs11/Secmod/AddTrustedCert.java" \
<p>For more notes about the PKCS11 tests, please refer to test/jdk/sun/security/pkcs11/README.</p>
<h3id="client-ui-tests">Client UI Tests</h3>
<p>Some Client UI tests use key sequences which may be reserved by the operating system. Usually that causes the test failure. So it is highly recommended to disable system key shortcuts prior testing. The steps to access and disable system key shortcuts for various platforms are provided below.</p>
Defaults to TEST_JOBS (if set by `--with-test-jobs=`), otherwise it defaults to
JOBS, except for Hotspot, where the default is *number of CPU cores/2* (for
sparc, if more than 16 cpus, then *number of CPU cores/5*, otherwise *number of
CPU cores/4*), but never more than *memory size in GB/2*.
JOBS, except for Hotspot, where the default is *number of CPU cores/2*,
but never more than *memory size in GB/2*.
#### TIMEOUT_FACTOR
The timeout factor (`-timeoutFactor`).
Defaults to 4.
#### FAILURE_HANDLER_TIMEOUT
Sets the argument `-timeoutHandlerTimeout` for JTReg. The default value is 0.
This is only valid if the failure handler is built.
#### TEST_MODE
The test mode (`agentvm` or `othervm`).
Defaults to `agentvm`.
#### ASSERT
Enable asserts (`-ea -esa`, or none).
Set to `true` or `false`. If true, adds `-ea -esa`. Defaults to true, except
for hotspot.
#### VERBOSE
The verbosity level (`-verbose`).
Defaults to `fail,error,summary`.
#### RETAIN
What test data to retain (`-retain`).
Defaults to `fail,error`.
#### MAX_MEM
Limit memory consumption (`-Xmx` and `-vmoption:-Xmx`, or none).
Limit memory consumption for JTReg test framework and VM under test. Set to 0
@@ -299,9 +311,14 @@ to disable the limits.
Defaults to 512m, except for hotspot, where it defaults to 0 (no limit).
#### MAX_OUTPUT
Set the property `javatest.maxOutputSize` for the launcher, to change the
default JTReg log limit.
#### KEYWORDS
JTReg kewords sent to JTReg using `-k`. Please be careful in making sure that
JTReg keywords sent to JTReg using `-k`. Please be careful in making sure that
spaces and special characters (like `!`) are properly quoted. To avoid some
issues, the special value `%20` can be used instead of space.
@@ -324,17 +341,29 @@ Set to `true` or `false`.
If `true`, JTReg will use `-match:` option, otherwise `-exclude:` will be used.
Default is `false`.
#### OPTIONS
Additional options to the JTReg test framework.
Use `JTREG="OPTIONS=--help all"` to see all available JTReg options.
#### JAVA_OPTIONS
Additional Java options to JTReg (`-javaoption`).
Additional Java options for running test classes (sent to JTReg as
`-javaoption`).
#### VM_OPTIONS
Additional VM options to JTReg (`-vmoption`).
Additional Java options to be used when compiling and running classes (sent to
JTReg as `-vmoption`).
This option is only needed in special circumstances. To pass Java options to
your test classes, use `JAVA_OPTIONS`.
#### LAUNCHER_OPTIONS
Additional Java options that are sent to the java launcher that starts the
JTReg harness.
#### AOT_MODULES
@@ -349,6 +378,7 @@ Retry failed tests up to a set number of times. Defaults to 0.
### Gtest keywords
#### REPEAT
The number of times to repeat the tests (`--gtest_repeat`).
Default is 1. Set to -1 to repeat indefinitely. This can be especially useful
@@ -356,6 +386,7 @@ combined with `OPTIONS=--gtest_break_on_failure` to reproduce an intermittent
problem.
#### OPTIONS
Additional options to the Gtest test framework.
Use `GTEST="OPTIONS=--help"` to see all available Gtest options.
@@ -369,98 +400,127 @@ modules. If multiple modules are specified, they should be separated by space
### Microbenchmark keywords
#### FORK
Override the number of benchmark forks to spawn. Same as specifying `-f <num>`.
#### ITER
Number of measurement iterations per fork. Same as specifying `-i <num>`.
#### TIME
Amount of time to spend in each measurement iteration, in seconds. Same as
specifying `-r <num>`
#### WARMUP_ITER
Number of warmup iterations to run before the measurement phase in each fork.
Same as specifying `-wi <num>`.
#### WARMUP_TIME
Amount of time to spend in each warmup iteration. Same as specifying `-w <num>`.
#### RESULTS_FORMAT
Specify to have the test run save a log of the values. Accepts the same values
as `-rff`, i.e., `text`, `csv`, `scsv`, `json`, or `latex`.
#### VM_OPTIONS
Additional VM arguments to provide to forked off VMs. Same as `-jvmArgs <args>`
#### OPTIONS
Additional arguments to send to JMH.
## Notes for Specific Tests
### Docker Tests
Docker tests with default parameters may fail on systems with glibc versions not
compatible with the one used in the default docker image (e.g., Oracle Linux 7.6 for x86).
For example, they pass on Ubuntu 16.04 but fail on Ubuntu 18.04 if run like this on x86:
Docker tests with default parameters may fail on systems with glibc versions
not compatible with the one used in the default docker image (e.g., Oracle
Linux 7.6 for x86). For example, they pass on Ubuntu 16.04 but fail on Ubuntu
18.04 if run like this on x86:
$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"
```
$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"
```
To run these tests correctly, additional parameters for the correct docker image are
required on Ubuntu 18.04 by using `JAVA_OPTIONS`.
To run these tests correctly, additional parameters for the correct docker
image are required on Ubuntu 18.04 by using `JAVA_OPTIONS`.
$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker" JTREG="JAVA_OPTIONS=-Djdk.test.docker.image.name=ubuntu -Djdk.test.docker.image.version=latest"
```
$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker" \
AC_MSG_ERROR([--with-version-string must have a value])
elif test "x$with_version_string" != x; then
# Additional [] needed to keep m4 from mangling shell constructs.
if [ [[ $with_version_string =~ ^([0-9]+)(\.([0-9]+))?(\.([0-9]+))?(\.([0-9]+))?(\.([0-9]+))?(\.([0-9]+))?(\.([0-9]+))?(-([a-zA-Z]+))?((\+)([0-9]+)?(-([-a-zA-Z0-9.]+))?)?$ ]] ]; then
if [ [[ $with_version_string =~ ^([0-9]+)(\.([0-9]+))?(\.([0-9]+))?(\.([0-9]+))?(\.([0-9]+))?(\.([0-9]+))?(\.([0-9]+))?(-([a-zA-Z0-9]+))?(((\+)([0-9]*))?(-([-a-zA-Z0-9.]+))?)?$ ]] ]; then
AC_MSG_ERROR([jtreg home directory from --with-jtreg=$with_jtreg does not exist])
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
