install4j Help

Using Install4j With Gradle


You can execute the install4j compiler from gradle with the install4j Gradle plugin. To make the Gradle plugin available to your build script, you have to apply the install4j Gradle plugin:

plugins {
    id "com.install4j.gradle" version "X.Y.Z"
}

If you do not want to use the Gradle plugin repository for this purpose, the Gradle plugin is distributed in the file bin/gradle.jar.

The plugin has two parts: The global configuration with the top-level install4j {...} configuration block and tasks of type com.install4j.gradle.Install4jTask.

The global configuration block must specify the install4j installation directory:

install4j {
    installDir = file("/path/to/install4j_home")
}

On macOS, the installation directory is the path of the application bundle, for example /Applications/install4j.app. The actual command line compiler is located under /Applications/install4j.app/Contents/Resources/app/bin/install4j in that case.

In addition, the global configuration block can set defaults for the install4j tasks.

Task parameters

The install4j task supports the following parameters, many of which are explained in greater detail for the command line compiler.

 
AttributeDescriptionRequiredGlobal
projectFileThe install4j project file that should be build.YesNo
variableFiles Corresponds to the --var-file command line option. Specify the list of variable files with variable definitions. NoNo
variables

A map of variable definitions. These definitions override compiler variables in the project and correspond to the -D command line option. Definitions with variable elements take precedence before definitions in the variable file referenced by the variableFiles parameter.

The names of the variables must have been defined on the "General Settings->Compiler Variables" step. The values can be of any type, toString() will be called on each value to convert the value to a java.lang.String. For example: [variableOne: "One", variableTwo: 2].

NoNo
release Corresponds to the --release command line option. Enter a version number like "3.1.2". Version number components can be alphanumeric and should be separated by dots, dashes or underscores. NoNo
destination Corresponds to the --destination command line option. Enter a directory where the generated media files should be placed. NoNo
buildIds Corresponds to the --build-ids command line option. Enter a list of media file ids. The IDs for media files can be shown in the install4j IDE by choosing Project->Show IDs from the main menu. For example: [12, 24, 36]. NoNo
verbose Corresponds to the --verbose command line option. Either true or false. No, verbose and quiet cannot both be true Yes
quiet Corresponds to the --quiet command line option. Either true or false. Yes
license Corresponds to the --license command line option. If the license has not been configured yet, you can set the license key with this attribute. Yes
test Corresponds to the --test command line option. Either true or false. No, test and incremental cannot both be true Yes
incremental Corresponds to the --incremental command line option. Either true or false. Yes
debug Corresponds to the --debug command line option. Either true or false. NoYes
preserve Corresponds to the --preserve command line option. Either true or false. NoYes
faster Corresponds to the --faster command line option. Either true or false. NoYes
disableSigning Corresponds to the --disable-signing command line option. Either true or false. NoYes
disableBundling Corresponds to the --disable-bundling command line option. Either true or false. NoYes
winKeystorePassword Corresponds to the --win-keystore-password command line option. NoYes
macKeystorePassword Corresponds to the --mac-keystore-password command line option. NoYes
appleIdPassword Corresponds to the --apple-id-password command line option. NoYes
disableNotarization Corresponds to the --disable-notarization command line option. NoYes
buildSelected Corresponds to the --build-selected command line option. Either true or false. NoYes
mediaTypes Corresponds to the --media-types command line option. Enter a list of media types. To see the list of supported media types, execute install4jc --list-media-types. NoYes
vmParameters A list of VM parameters for the install4j command line compiler process. For example: ["-DproxySet=true", "-DproxyHost=myproxy", "-DproxyPort=1234", "-DproxyAuth=true", "-DproxyAuthUser=buildServer", "-DproxyAuthPassword=iq4zexwb8et"] sets an HTTP proxy that is required for code signing. NoYes

The "Global" column shows if a parameter can also be specified in the global install4j {...} configuration block. Definitions in the task override global definitions.

Examples

Simple example:

install4j {
    installDir = file("/opt/install4j")
}
task media(type: com.install4j.gradle.Install4jTask) {
    projectFile = file("myProject.install4j")
}

More complex example:

if (!hasProperty("install4jHomeDir")) {
    File propertiesFile = file("${System.getProperty("user.home")}/.gradle/gradle.properties")
    throw new RuntimeException("Specify install4jHomeDir in $propertiesFile")
}

boolean dev = hasProperty("dev")

install4j {
    installDir = file(install4jHomeDir)
    faster = dev
    disableSigning = dev
    winKeystorePassword = "supersecretWin"
    macKeystorePassword = "supersecretMac"

    if (dev) {
        mediaTypes = ["windows"]
    }
}

task media(type: com.install4j.gradle.Install4jTask) {
    dependsOn "dist" // example task that prepares the distribution for install4j

    projectFile = "myProject.install4j"
    variables = [majorVersion: version.substring(0, 1), build: 1234]
    variableFiles = ["var1.txt", "var2.txt"]
}

The "hello" sample project includes a Gradle build script that shows how to setup the install4j task. To install the sample projects, invoke Project->Open Sample Project from the install4j IDE. When you do this for the first time, the sample projects are copied to the "Documents" folder in your home directory.

In the samples/hello directory, execute

gradle media

to start the build. If you have not defined install4jHomeDir in gradle.properties next to build.gradle, the build will fail with a corresponding error message.

Creating JRE bundles

To create a JRE bundle from your Gradle build script, use the com.install4j.gradle.CreateBundleTask and and set its javaHome property to the JRE that you want to create a bundle for.

The CreateBundleTask invokes the createbundle command line executable in the install4j installation and has the following properties:

 
AttributeDescriptionRequired
javaHomeThe home directory of the JRE that should be bundledYes
outputDirectory Corresponds to the --output command line option. No
version Corresponds to the --version command line option. No
id Corresponds to the --id command line option. No
unpacked Corresponds to the --unpacked command line option. No
jdkRelease Corresponds to the --jdk-release command line option. No
jdkProviderId Corresponds to the --jdk-provider-id command line option. No
addModules Corresponds to the --add-modules command line option. No
addModuleSet Corresponds to the --add-module-set command line option. No
jmodFiles Corresponds to the --add-jmod command line option. No
jmodDirs Corresponds to the --add-jmod-dir command line option. No
vmParameters Like the vmParameters property of the Install4jTask No

Example:

task createBundle(type: com.install4j.gradle.CreateBundleTask) {
    javaHome = "/usr/lib/jvm/jre-11/jre"
    outputDirectory = "/home/build/projects/myProject/jreBundles"
    version = "11"
    id="j3d"
    jmodDirs = ["jmods"]
    jmodFiles = ["one.jmod", "two.jmod"]
}