https://github.com/gradlex-org/java-module-packaging
A Gradle plugin to package stand-alone Java applications for multiple operating systems and architectures with 'jpackage'.
https://github.com/gradlex-org/java-module-packaging
gradle-plugin java java-modules jpackage jpms
Last synced: 22 days ago
JSON representation
A Gradle plugin to package stand-alone Java applications for multiple operating systems and architectures with 'jpackage'.
- Host: GitHub
- URL: https://github.com/gradlex-org/java-module-packaging
- Owner: gradlex-org
- License: apache-2.0
- Created: 2024-01-22T13:12:22.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-04T07:47:16.000Z (29 days ago)
- Last Synced: 2025-04-04T08:31:02.838Z (29 days ago)
- Topics: gradle-plugin, java, java-modules, jpackage, jpms
- Language: Java
- Homepage:
- Size: 190 KB
- Stars: 13
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Java Module Packaging Gradle plugin
[](https://actions-badge.atrox.dev/gradlex-org/java-module-packaging/goto?ref=main)
[](https://plugins.gradle.org/plugin/org.gradlex.java-module-packaging)
A Gradle plugin to package modular Java application as standalone bundles/installers for Windows, macOS and Linux with [jpackage](https://docs.oracle.com/en/java/javase/21/docs/specs/man/jpackage.html).
This [GradleX](https://gradlex.org) plugin is maintained by me, [Jendrik Johannes](https://github.com/jjohannes).
I offer consulting and training for Gradle and/or the Java Module System - please [reach out](mailto:[email protected]) if you are interested.
There is also my [YouTube channel](https://www.youtube.com/playlist?list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE) on Gradle topics.
If you have a suggestion or a question, please [open an issue](https://github.com/gradlex-org/java-module-packaging/issues/new).
# Java Modules with Gradle
If you plan to build Java Modules with Gradle, you should consider using these plugins on top of Gradle core:
- [`id("org.gradlex.java-module-dependencies")`](https://github.com/gradlex-org/java-module-dependencies)
Avoid duplicated dependency definitions and get your Module Path under control
- [`id("org.gradlex.jvm-dependency-conflict-resolution")`](https://github.com/gradlex-org/jvm-dependency-conflict-resolution)
Additional metadata for widely-used modules and patching facilities to add missing metadata
- [`id("org.gradlex.java-module-testing")`](https://github.com/gradlex-org/java-module-testing)
Proper test setup for Java Modules
- [`id("org.gradlex.extra-java-module-info")`](https://github.com/gradlex-org/extra-java-module-info)
Only if your (existing) project cannot avoid using non-module legacy Jars
- [`id("org.gradlex.java-module-packaging")`](https://github.com/gradlex-org/java-module-packaging)
Package standalone applications for Windows, macOS and Linux
[In episodes 31, 32, 33 of Understanding Gradle](https://github.com/jjohannes/understanding-gradle) I explain what these plugins do and why they are needed.
[
](https://www.youtube.com/watch?v=X9u1taDwLSA&list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE)
[
](https://www.youtube.com/watch?v=T9U0BOlVc-c&list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE)
[
](https://www.youtube.com/watch?v=6rFEDcP8Noc&list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE)
[Full Java Module System Project Setup](https://github.com/jjohannes/gradle-project-setup-howto/tree/java_module_system) is a full-fledged Java Module System project setup using these plugins.
[
](https://www.youtube.com/watch?v=uRieSnovlVc&list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE)
# How to use?
Working example projects to inspect:
- [java-module-system](https://github.com/jjohannes/java-module-system) contains a compact sample and further documentation
- [gradle-project-setup-howto](https://github.com/jjohannes/gradle-project-setup-howto/tree/java_module_system) is a full-fledged Java Module System project setup
For general information about how to structure Gradle builds and apply community plugins like this one to all subprojects
you can check out my [Understanding Gradle video series](https://www.youtube.com/playlist?list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE).
## Plugin dependency
Add this to the build file of your convention plugin's build
(e.g. `build-logic/build.gradle(.kts)` or `buildSrc/build.gradle(.kts)`).
```
dependencies {
implementation("org.gradlex:java-module-packaging:1.0")
}
```
## Apply and use the plugin
In your convention plugin, apply the plugin and configure the _targets_.
```
plugins {
id("org.gradlex.java-module-packaging")
}
javaModulePackaging {
target("ubuntu-22.04") {
operatingSystem = OperatingSystemFamily.LINUX
architecture = MachineArchitecture.X86_64
}
target("macos-13") {
operatingSystem = OperatingSystemFamily.MACOS
architecture = MachineArchitecture.X86_64
}
target("macos-14") {
operatingSystem = OperatingSystemFamily.MACOS
architecture = MachineArchitecture.ARM64
}
target("windows-2022") {
operatingSystem = OperatingSystemFamily.WINDOWS
architecture = MachineArchitecture.X86_64
}
primaryTarget(target("macos-14"))
}
```
You can now run _target-specific_ builds:
```
./gradlew assembleWindows
```
```
./gradlew runWindows
```
There are some additional configuration options that can be used:
```
javaModulePackaging {
applicationName();
applicationVersion();
applicationDescription = ""
vendor = "My Company"
copyright = "(c) My Company"
jpackageResources.setFrom(...);
resources.from(...)
}
```
## Using target specific variants of libraries (like JavaFX)
The plugin uses Gradle's [variant-aware dependency management](https://docs.gradle.org/current/userguide/variant_model.html)
to select target-specific Jars based on the configured [targets](#apply-and-use-the-plugin).
For this, such a library needs to be published with [Gradle Module Metadata](https://docs.gradle.org/current/userguide/publishing_gradle_module_metadata.html)
and contain the necessary information about the available target-specific Jars.
If the metadata is missing or incomplete, you should use the [org.gradlex.jvm-dependency-conflict-resolution](https://github.com/gradlex-org/jvm-dependency-conflict-resolution)
plugin to add the missing information via [addTargetPlatformVariant](https://gradlex.org/jvm-dependency-conflict-resolution/#patch-dsl-block).
For example, for JavaFX it may look like this:
```
jvmDependencyConflicts.patch {
listOf("base", "graphics", "controls").forEach { jfxModule ->
module("org.openjfx:javafx-$jfxModule") {
addTargetPlatformVariant("linux", OperatingSystemFamily.LINUX, MachineArchitecture.X86_64)
addTargetPlatformVariant("linux-aarch64", OperatingSystemFamily.LINUX, MachineArchitecture.ARM64)
addTargetPlatformVariant("mac", OperatingSystemFamily.MACOS, MachineArchitecture.X86_64)
addTargetPlatformVariant("mac-aarch64", OperatingSystemFamily.MACOS, MachineArchitecture.ARM64)
addTargetPlatformVariant("win", OperatingSystemFamily.WINDOWS, MachineArchitecture.X86_64)
}
}
}
```
## Testing against multiple targets
> [!WARNING]
> Currently, the following only works in combination with [Blackbox Test Suites configured by the _org.gradlex.java-module-testing_ plugin](https://github.com/gradlex-org/java-module-testing?tab=readme-ov-file#blackbox-test-suites).
Tests run against the _primary_ target, which is either the local machine you run the build on, or what is configured via `javaModulePackaging.primaryTarget(...)`.
If you want to run the test multiple times against each target you configured, you can configure this as follows:
```
javaModulePackaging {
multiTargetTestSuite(testing.suites["test"])
}
```
Then, there will be a test task available for each target, such as `testWindows-2022` or `testMacos-14`.
## Running on GitHub Actions
Target-specific _tasks_ such as `assembleWindows-2022` or `assembleMacos-14` only run on the fitting operating system and architecture.
If you want to build your software for multiple targets and have GitHub actions available, you can use different
runners to create packages for the different targets. A setup for this can look like this
(assuming your targets are named: `ubuntu-22.04`, `windows-2022`, `macos-13`, `macos-14`):
```
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version-file: ./gradle/java-version.txt
- uses: gradle/actions/setup-gradle@v3
- run: "./gradlew check"
package:
needs: check
strategy:
matrix:
os: [ubuntu-22.04, windows-2022, macos-13, macos-14]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version-file: ./gradle/java-version.txt
- uses: gradle/actions/setup-gradle@v3
- run: "./gradlew assemble${{ matrix.os }}"
- uses: actions/upload-artifact@v4
with:
name: Application Package ${{ matrix.os }}
path: build/app/packages/*/*
```
To avoid re-compilation of the Java code on each of the runners, you can run a
[Gradle remote cache node](https://docs.gradle.com/build-cache-node).
The [java-module-system](https://github.com/jjohannes/java-module-system) project is an example that
uses GitHub actions with a Gradle remote build cache.
# Disclaimer
Gradle and the Gradle logo are trademarks of Gradle, Inc.
The GradleX project is not endorsed by, affiliated with, or associated with Gradle or Gradle, Inc. in any way.