JEP draft: JDK Source Structure

Аннотация

Этот информационный JEP описывает общую организацию и структуру исходного кода JDK и связанных с ним файлов в репозитории JDK.

Мотивация

Понятная и явно описанная структура помогает разработчикам понимать, как связан код и где он находится. Она снижает риск «споров о мелочах» (bike shedding), упрощает сопровождение кода и позволяет инженерам сосредоточиться на существенных аспектах функциональности, а не на поверхностной организации кода.

Структура основной части исходного кода JDK, расположенной в src/$MODULE, была описана в JEP 201 (Modular Source Code). Однако адаптация структуры исходного кода — непрерывный процесс, и этот информационный JEP можно при необходимости обновлять.

Описание

Корневой каталог репозитория JDK содержит следующие каталоги:

• src
• test
• make
• doc
• bin

Корневой каталог также содержит строго ограниченный набор отдельных файлов. К ним относятся необходимые юридические документы, информация для участников и необходимые файлы системы сборки. Прежде чем добавлять новые файлы в корневой каталог, следует проявлять большую сдержанность, и по возможности этого следует избегать.

Каталог src

Каталог src содержит исходный код, из которого собирается JDK. Он состоит из отдельных каталогов для модулей, из которых состоит JDK, и отдельного каталога для JVM HotSpot.

Обзор структуры каталога src:

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 содержит исходный код HotSpot. Код HotSpot написан на C++.

  • src/hotspot/share содержит общий, кроссплатформенный код.

  • src/hotspot/cpu/$CPU содержит код, зависящий от конкретного процессора. $CPU обозначает конкретную процессорную архитектуру, например aarch64, x64 и т. д.

  • src/hotspot/os/$OS содержит код, зависящий от конкретной операционной системы. $OS обозначает конкретную ОС или семейство ОС, например linux, windows и т. д. Обратите внимание, что по историческим причинам unix называется posix, а macos называется bsd.

  • src/hotspot/os_cpu/$OS_$CPU содержит код, зависящий одновременно от конкретной ОС и конкретного процессора.

  Имена файлов в src/hotspot/cpu/$CPU обычно оканчиваются на _$CPU.{hpp,cpp}. Аналогично имена файлов в src/hotspot/os/$OS и src/hotspot/os_cpu/$OS_$CPU обычно оканчиваются на *_$OS.{hpp,cpp} и *_$OS_$CPU.{hpp,cpp} соответственно.

• Набор каталогов src/$MODULE содержит исходный код отдельных модулей JDK. $MODULE — имя модуля (например, java.base).

  Каталог share содержит общий, кроссплатформенный код и связанные с ним файлы.

  Каталог $OS содержит код, специфичный для операционной системы, и связанные с ним файлы. $OS обозначает конкретную ОС или семейство ОС, например unix, windows и т. д. Обратите внимание, что по историческим причинам macos называется macosx.

  • src/$MODULE/{share,$OS}/classes содержит исходные файлы Java и файлы ресурсов, организованные в дерево каталогов, отражающее иерархию $PACKAGE их API.

  • src/$MODULE/{share,$OS}/native/include содержит заголовочные файлы C или C++, предназначенные для экспорта для внешнего использования (например, jni.h).

  • src/$MODULE/{share,$OS}/native/common содержит исходные или заголовочные файлы C или C++, общие для нескольких нативных библиотек или исполняемых файлов этого модуля.

  • src/$MODULE/{share,$OS}/native/lib$LIBRARY содержит исходные файлы C или C++, из которых будет собрана разделяемая библиотека или DLL с именем $LIBRARY. Например, файлы в src/java.base/share/native/libjava будут скомпилированы в java.dll, libjava.so или libjava.dylib в зависимости от платформы.

  • src/$MODULE/{share,$OS}/native/$EXECUTABLE содержит исходные файлы C или C++, из которых будет собран исполняемый двоичный файл с именем $EXECUTABLE или $EXECUTABLE.exe в зависимости от платформы.

  • Каталог man содержит man-страницы в формате nroff или Markdown.

  • Каталог legal содержит юридические уведомления для включённого кода 3-х сторон в формате Markdown.

  • Каталог data содержит файлы данных, необходимые для сборки модуля.

  • Каталог conf содержит конфигурационные файлы, предназначенные для редактирования конечными пользователями.

  • Каталог lib содержит конфигурационные файлы, не предназначенные для редактирования конечными пользователями.

• src/utils содержит автономные утилиты, призванные помогать разработчикам JDK. Каждая утилита находится в отдельном каталоге внутри src/utils, но структура отдельных утилит не определяется

Непосредственно в src могут присутствовать дополнительные унаследованные каталоги, но новые такие каталоги добавлять не следует.

Каталог test

Каталог test содержит код для запуска тестов JDK или файлы, необходимые для написания или запуска тестов.

Обзор структуры каталога test:

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

• test/hotspot/gtest содержит модульные тесты на основе GTest для кода в src/hotspot.

• test/hotspot/jtreg содержит тесты на основе JTReg для кода в src/hotspot.

• test/jdk и test/langtools содержат тесты на основе JTReg для кода в src/$MODULE. По историческим причинам тесты некоторых модулей находятся в test/langtools, а не в test/jdk.

• test/micro содержит микробенчмарки, т. е. тесты, предназначенные для проверки производительности одной чётко определённой задачи.

• test/make содержит тесты, проверяющие систему сборки.

• test/lib содержит различный код, помогающий писать или выполнять другие тесты.

• test/lib-test содержит тесты, проверяющие test/lib.

Каталог test также содержит несколько других каталогов для различных особых случаев тестирования. Прежде чем добавлять новые каталоги непосредственно в test, проявляйте большую сдержанность.

Каталог make

Каталог make содержит файлы, используемые системой сборки JDK или связанные с ней.

Обзор структуры каталога make:

make/conf/
       modules/$MODULE/

• make/conf содержит основную конфигурацию сборки JDK.

• Набор каталогов make/modules/$MODULE содержит фрагменты makefile для отдельных модулей, которым требуется особая обработка при сборке или которым нужно переопределить настройки сборки по умолчанию.

Остальные файлы и каталоги в make зависят от реализации системы сборки и могут меняться.

Каталог doc

Каталог doc содержит документацию, которая может быть полезна разработчикам JDK.

Документация помещается в каталог doc, если она соответствует следующим критериям:

• она не предназначена для поставки вместе с собранным JDK,

• она ориентирована на разработчиков JDK, а не на пользователей JDK, и

• её содержание привязано к конкретному выпуску или иным образом связано с текущим содержимым репозитория.

Документация в doc обычно предоставляется в двух форматах, Markdown и HTML, которые обновляются синхронно.

Каталог bin

Каталог bin содержит набор скриптов, которые могут помогать разработчикам JDK в различных задачах.

Права на выполнение не установлены ни для файлов в этом каталоге, ни для каких-либо других файлов в репозитории JDK.