JEP draft: JDK Packaging and Installation Guidelines

Summary

Promote guidelines for creating JDK installers on Linux, Windows, and macOS to reduce risks of collisions between JDK installations by different JDK providers, and to promote a better experience when installing update releases of the JDK.

The guidelines include installation directory names, package names, and other elements of installers that can be in conflict.

Goals

• Promote recommendations for platform-specific JDK installers: deb and rpm on Linux; exe and msi on Windows; pkg and dmg on macOS
• Promote recommendations for creating JDK installers that avoid collisions with those of other providers
• Promote a stable installation directory within a feature release family to make it easier for applications to find the current update release
• Encourage adoption of the recommended changes while allowing providers to balance backward compatibility needs

Non-Goals

• Promote strict rules for JDK packaging
• Define a protocol by which a user can pick one preferred JDK installation from among many installations
• Promote recommendations for jlink-ed runtimes bundled with Java apps
• Promote recommendations for compressed/archive JDK bundles, such as zip or tar

Motivation

Multiple providers of JDK installers offer the same functionality, often in different ways. Currently, there are no established recommendations for installing the JDK. This has resulted in conflicts and clashes, and such conflicts are likely to happen again. On Linux, JDK packages register "java" and "javac" groups with the alternatives framework. If the contents of these groups are not consistent across providers, switching between JDKs from different providers can break internal data managed by the framework.

Promoting recommendations for key properties of JDK installers will reduce conflicts and improve application portability when switching between JDKs from different providers.

Some providers install each JDK update release into a unique directory that includes the update release number in the directory name. This results in no stable directory name that applications can use to find the latest release within a feature release.

Common guidelines will help avoid potential conflicts between JDK installers from current and future providers.

Description

We propose the following guidelines for creating JDK installers. Providers are not expected to adopt all of them, especially where they might break compatibility with that provider’s current installation of the JDK. Specifically, a provider might decide to retain some aspect of their existing installation that isn’t in conflict with other providers, to retain backward compatibility.

All platforms

Include the Java “feature” number, as defined in JEP 322, instead of the full version number (E.g.: 19, not 19.0.1) in the installation directory path. Having a single stable directory name for all update releases within a release family will make it easier to install JDK updates without disrupting applications.

Include a provider-specific name in the installation directory path to avoid conflicts between JDKs from different providers. When choosing a provider-specific name, use a company name or a distinctive brand name to distinguish between providers. Avoid generic terms that could also be adopted by other providers. A provider with an existing JDK installer might choose to retain their current naming convention to preserve backward compatibility.

In the examples below, the fictional provider Dukecorp will be used.

Windows MSI and EXE packaging

Installers should place the JDK image in the %ProgramFiles%/%PROVIDER_SPECIFIC_NAME%/jdk-%FEATURE% directory. E.g.: %ProgramFiles%/Dukecorp/jdk-19, %ProgramFiles%/Dukecorp/jdk-11

As Windows offers different installation root directories for different architectures (%ProgramFiles% and %ProgramFiles(x86)%), we don't propose adding the %PROCESSOR_ARCH% suffix to the JDK installation directory name.

macOS DMG packaging

Installers should place the JDK image in the /Library/Java/JavaVirtualMachines/jdk-${FEATURE}-${PROVIDER_SPECIFIC_NAME}.jdk directory. To comply with established practices, the JDK image directory name must end with .jdk suffix. E.g.: /Library/Java/JavaVirtualMachines/jdk-19-dukecorp.jdk

As macOS encourages the use of universal binaries when supporting multiple architectures, we don't propose including ${PROCESSOR_ARCH} in the JDK installation directory name.

Linux RPM and DEB packaging

Package name: Include ${FEATURE} and ${PROVIDER_SPECIFIC_NAME}. E.g.: jdk-19-dukecorp

Installation directory name: Installers should place the JDK image in the /usr/lib/jvm/jdk-${FEATURE}-${PROVIDER_SPECIFIC_NAME}-${PROCESSOR_ARCH} directory. E.g.: /usr/lib/jvm/jdk-19-dukecorp-x64

Alternative framework groups: For historical reasons, we propose two groups: "java" and "javac".

"java" is for commands used to run applications. The list of commands:

"javac" is used for all other commands. The list of commands:

The contents of the groups have been consistent for many years. Moving commands between groups would cause installations to fail because the alternative framework can't handle the same command being in different groups in different packages. E.g.: jar can't be in "java" group for jdk-8 and in "javac" for jdk-11 packages.

When a new command is added to the JDK, the CSR should specify in which alternatives group it should be added.

Alternative framework group priority: The JDK version number should be encoded in the priority value so that higher JDK versions have a higher priority. For example, JDK 19 might be encoded as "1900000" and JDK 19.0.1 as "1900100".