The Gradle ClassWorlds Assembly Plugin is a simple Gradle plugin that generates a runnable distribution of your project, using Classworlds as application launcher.
Extract the archive(s) and it’s ready to go!
This plugin is an alternative to the Gradle application plugin for the Archive generation part. You can reuse the JavaExec task to actually test the execution of your application prior to generating a runnable distribution.
In terms of transparency, launching and assembly capabilities, you can perform arbitrary actions with the staging directory via a configuration closure.
Sometimes it is easier to ship your application as a simple zip or tar archive instead of bothering with a sophisticated software installer.
The generated assembly name follows the pattern <project-name>-<project-version>.<assemblyformat>.
Below is the standard folder structure of assemblies generated by the plugin.
ApplicationFolder : (projectName-ProjectVersion) | --- boot: Contains the application launcher bootstrap jars | --- etc : Contains the launcher configuration | --- lib : Contains the application dependencies and build artifacts | --- bin : Contains the application launcher scripts (run.bat and run.sh)
Note: A configuration closure(discussed later) allows you to perform arbitrary actions with the staging folder.
Simplicity is exactly what this Gradle plugin provides:
- You have an application that is launched via a main class.
- Your application has a set of dependencies.
- Launching the application is just a matter of having all the dependencies in the classpath and running the main method of your application entry point.
- Compress files into an archive and ship it!
- Note: This plugin is now available on a hosted Maven repository!
- Requirements: Gradle 1.6+ and JDK 1.6+
Clone the project from GitHub and run gradlew install, to install the plugin into your local Maven cache.
The first step consists into configuring the buildscript closure at the top of your Gradle build file.
After that, you can apply the classworlds plugin.
buildscript {
repositories {
maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
}
dependencies {
classpath 'com.rimerosolutions.gradle.plugins:gradle-classworlds-plugin:0.0.1-SNAPSHOT'
}
}
apply plugin: 'classworlds'
The plugin has only one required input which is the main class name of your application.
The main class name configuration is provided via the appMainClassName variable in a configuration block.
Configuration parameters are to be specified inside a classworlds block in your Gradle build file.
classworlds {
// mandatory inputs
appMainClassName = 'com.Main'
// optional inputs
appHome='MY_APPLICATION_HOME_IF_YOU_NEED_IT' // Set as system property
assemblyFileName="application_default_is_project_name_and_version"
assemblyFormats = ['zip', 'tar'] // only zip by default
jvmOptions = '-Xms512m -Xmx1g' // default is -Xmx128m -Xmx512m
doWithStagingDir = { stagingFolder ->
println 'Customizations, other actions here if needed'
}
}
Note: Gradle task names seem to be case insensitive.
The plugin provides one main task called classWorlds of type GradleBuild aggregating some nested tasks:
The sub-tasks of the classWorlds task are responsible for copying files around and generating launcher related files or folders.
Tasks aggregation makes the code more readable as well as more testable. classworlds sub-tasks are not meant to be used directly, unless you really need fine-grained control due to some lack of flexibility.
The classWorlds task generates a zip and/or tar assembly of your project with UNIX and Windows application launchers.
Running the classworlds task will also trigger the build task to generate all the project artifacts.
gradle classworlds
Extract the generated archive located inside your build folder, to the location of your choice.
APPLICATION_LOCATION/bin/run.sh
APPLICATION_LOCATION/bin/run.bat
- Add classpath customizations to prepend folders/files to the classpath.
- Avoid marking all files as executable when creating the archive(s).