envelope

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

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


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

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

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