JEP draft: JDK Source Structure

OwnerMagnus Ihse Bursie
TypeInformational
ScopeJDK
StatusSubmitted
Componentinfrastructure
Created2022/03/15 23:29
Updated2022/04/25 17:09
Issue8283227

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:

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/

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/

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/

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:

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.