JEP draft: JDK Source Structure

Summary

This informational JEP describes the overall layout and structure of the JDK source code and related files in the JDK repository.

Motivation

Having a clear and communicated structure helps developers understand code relationship and location. It minimizes the risk of "bike shedding", makes the code easier to maintain, and enables engineers to focus on relevant aspects of the functionality instead of superficial code organization.

The structure of the bulk of the JDK source code, residing in src/$MODULE, was described by JEP 201 (Modular Source Code). However, adapting the source code structure is an ongoing process, and this informational JEP can be kept up-to-date as needed.

Description

The top-level directory of the JDK repository contains the following directories:

• src
• test
• make
• doc
• bin

The top-level directory also contains a highly restricted set of individual files. These include essential legal documents, contributor information and necessary build system files. Great restriction should be exercised before introducing additional top-level files, and this should be avoided if at all possible.

The src directory

The src directory contains the source code that is used to build the JDK. It consists of individual directories for the modules that comprise the JDK, and a separate directory for the Hotspot JVM.

Overview of the src directory structure:

src/hotspot/share/
              cpu/$CPU/
              os/$OS/
              os_cpu/$OS_$CPU/
      $MODULE/{share,$OS}/classes/$PACKAGE/
                          native/include/
                                 common/
                                 lib$LIBRARY/
                                 $EXECUTABLE/
                          man/
                          legal/
                          data/
                          conf/
                          lib/
      utils/

• src/hotspot contains the Hotspot source code. Hotspot code is written in C++.

  • src/hotspot/share contains shared, cross-platform code.

  • src/hotspot/cpu/$CPU contains code that is dependent on a particular CPU. $CPU denotes a particular CPU architecture, e.g. aarch64, x64, etc.

  • src/hotspot/os/$OS contains code that is dependent on a particular operating system. $OS denotes a particular OS or OS family, e.g. linux, windows, etc. Note that due to historical reasons, unix is called posix, and macos is called bsd.

  • src/hotspot/os_cpu/$OS_$CPU contains code that is dependent on both a particular OS and a particular CPU.

  Files in src/hotspot/cpu/$CPU are normally named ending in _$CPU.{hpp,cpp}. Likewise are files in src/hotspot/os/$OS and src/hotspot/os_cpu/$OS_$CPU normally named ending in *_$OS.{hpp,cpp} and *_$OS_$CPU.{hpp,cpp}, respectively.

• The src/$MODULE set of directories contain source code for the individual JDK modules. $MODULE is the module name (e.g., java.base).

  The share directory contains shared, cross-platform code and related files.

  The $OS directory contains operating system specific code and related files. $OS denotes a particular OS or OS family, e.g. unix, windows, etc. Note that due to historical reasons, macos is called macosx.

  • src/$MODULE/{share,$OS}/classes contains Java source files and resource files organized into a directory tree reflecting their API $PACKAGE hierarchy.

  • src/$MODULE/{share,$OS}/native/include contains C or C++ header files intended to be exported for external use (e.g., jni.h).

  • src/$MODULE/{share,$OS}/native/common contains C or C++ source or header files shared between multiple native libraries or executables in this module.

  • src/$MODULE/{share,$OS}/native/lib$LIBRARY contains C or C++ source files that will be built to a shared library or DLL with the name $LIBRARY. For instance, the files in src/java.base/share/native/libjava will be compiled into java.dll, libjava.so or libjava.dylib, depending on platform.

  • src/$MODULE/{share,$OS}/native/$EXECUTABLE contains C or C++ source files that will be built to an executable binary with the name $EXECUTABLE or $EXECUTABLE.exe, depending on platform.

  • The man directory contains man pages in nroff or Markdown format.

  • The legal directory contains legal notices for included 3rd party code, in Markdown format.

  • The data directory contains data files needed to build the module.

  • The conf directory contains configuration files meant to be edited by end users.

  • The lib directory contains configuration files not meant to be edited by end users.

• src/utils contains stand-alone utilities designed to help JDK developers. Each utility resides in a separate directory within src/utils, but the structure of individual utilities is left unspecified

Additional legacy directories directly under src might be present, but new such directories should not be added.

The test directory

The test directory contains code for running tests on the JDK, or files that are needed to support writing or running tests.

Overview of the test directory structure:

test/hotspot/gtest/
               jtreg/
       jdk/
       langtools/
       micro/
       make/
       lib/
       lib-test/

• test/hotspot/gtest contains GTest based unit tests for code under src/hotspot.

• test/hotspot/jtreg contains JTReg based tests for code under src/hotspot.

• test/jdk and test/langtools contains JTReg based tests for code under src/$MODULE. For historical reasons, tests for some modules are located in test/langtools instead of test/jdk.

• test/micro contains microbenchmarks, i.e. tests designed to check performance of a singe, well-defined task.

• test/make contains tests that exercise the build system.

• test/lib contains various code that supports the writing or execution of other tests.

• test/lib-test contains tests that checks test/lib.

The test directory also contains a few other directories to support various special case testing. Exercise great restriction before adding new directories directly under test.

The make directory

The make directory contains files used by or related to the JDK build system.

Overview of the make directory structure:

make/conf/
       modules/$MODULE/

• make/conf contains essential configuration for the JDK build.

• The make/modules/$MODULE set of directories contain makefile snippets for individual modules that require special build handling, or need to override default build settings.

Additional files and directories in make are build system implementation specific and subject to change.

The doc directory

The doc directory contains documentation that can be helpful for JDK developers.

The criteria for documentation to fit in the doc directory is that:

• it is not intended to be shipped with the built JDK,

• it is targeting JDK developers as opposed to JDK users, and

• the content is tied to a particular release or otherwise related to the current content of the repository.

The documentation in doc is typically provided in both Markdown and HTML format, which are updated in tandem.

The bin directory

The bin directory contains an assortment of scripts that can assist JDK developers in various tasks.

No executable permission is set on the files in this directory, nor any other files in the JDK repository.