123 lines
3.7 KiB
Markdown
123 lines
3.7 KiB
Markdown
## Overview
|
|
Envelope is a simple Gradle plugin that allows you to create an executable jar file
|
|
that includes all runtime dependencies and can be executed with a simple
|
|
|
|
```bash
|
|
java -jar my-app.jar
|
|
```
|
|
It supports JPMS, embedded system properties, Java agents, extra folders to be added to classpath.
|
|
|
|
### Usage
|
|
|
|
Declare the plugin in your build's `settings.gradle` like this
|
|
```groovy
|
|
|
|
pluginManagement {
|
|
repositories {
|
|
maven {
|
|
url = 'https://gitea.woggioni.net/api/packages/woggioni/maven'
|
|
}
|
|
}
|
|
|
|
plugins {
|
|
id "net.woggioni.gradle.envelope" version "2025.01.21"
|
|
}
|
|
}
|
|
```
|
|
|
|
Then add it to a project's `build.gradle`
|
|
|
|
```groovy
|
|
plugins {
|
|
id 'net.woggioni.gradle.envelope'
|
|
}
|
|
|
|
envelopeJar {
|
|
mainClass = 'your.main.Class'
|
|
}
|
|
```
|
|
|
|
The plugin adds 2 tasks to your project:
|
|
|
|
- `envelopeJar` of type `net.woggioni.gradle.envelope.EnvelopeJarTask` that creates the executable jar in the project's libraries folder
|
|
- `envelopeRun` of type `org.gradle.api.tasks.JavaExec` which launches the jar created by the `envelopeJar` task
|
|
|
|
### Configuration
|
|
|
|
`EnvelopeJarTask` has several properties useful for configuration purposes:
|
|
|
|
###### mainClass
|
|
|
|
This string property sets the class that will be searched for the `main` method to start the application
|
|
|
|
###### mainModule
|
|
|
|
When this string property is set, the jar file will be started in JPMS mode (if running on Java 9+) and
|
|
this module will be searched for the main class, if the `mainClass` is not set the main class specified
|
|
in the module descriptor will be loaded instead
|
|
|
|
###### systemProperties
|
|
|
|
This is a map that contains Java system properties that will be set before your application starts
|
|
|
|
###### extraClasspath
|
|
|
|
This is a list of strings representing filesystem paths that will be added to the classpath (if running in classpath mode)
|
|
or to the module path (if running in JPMS mode) when the application starts.
|
|
|
|
Relative paths and interpolation with Java System properties and environmental variables are supported:
|
|
|
|
e.g.
|
|
|
|
This looks for a `plugin` folder in the user's home directory
|
|
```
|
|
${env:HOME}/plugins
|
|
```
|
|
|
|
Same using Java system properties instead
|
|
```
|
|
${sys:user.home}/plugins
|
|
```
|
|
|
|
###### javaAgent
|
|
This is a method accepting 2 strings, the first is the Java agent class name and the second one is the java agent arguments.
|
|
It can be invoked multiple times to setup multiple java agents for the same JAR file.
|
|
All the java agents will be invoked before the application startup.
|
|
|
|
Java agents configured in this way will always run together with the application and cannot be disabled.
|
|
|
|
### Example
|
|
|
|
```groovy
|
|
plugins {
|
|
id 'net.woggioni.gradle.envelope'
|
|
}
|
|
|
|
envelopeJar {
|
|
mainClass = 'your.main.Class'
|
|
mainModule = 'your.main.module'
|
|
|
|
systemProperties = [
|
|
'some.property' : 'Some value'
|
|
]
|
|
|
|
extraClasspath = ["plugins"]
|
|
|
|
javaAgent('your.java.agent.Class', 'optional agent arguments')
|
|
}
|
|
```
|
|
|
|
### Limitations
|
|
|
|
- This plugin requires Gradle >= 6.0 and Java >=0 8 to build the executable jar file.
|
|
The assembled envelope jar requires and Java >= 8 to run, if only `mainClass` is specified,
|
|
if both `mainModule` and `mainClass` are specified the generated jar file will (try to) run in classpath mode on Java 8
|
|
and in JPMS mode on Java > 8.
|
|
|
|
- When running in JPMS mode (when the `mainModule` property is set), command line arguments like
|
|
`--add-opens`, `--add-exports`, `--add-reads` won't work as JPMS is initialized after application startup
|
|
|
|
- When running in JPMS mode custom stream handler need to added installed using `URL.setURLStreamHandlerFactory`,
|
|
setting the `java.protocol.handler.pkgs` system property does not work as it tries to load
|
|
the respective handler using the system classloader which, in an envelope application, can only load envelope own classes
|