# Using install4j with Gradle

You can execute the install4j compiler from [gradle](https://gradle.org) 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 can specify defaults for task properties that are applied to all install4j tasks, for example, the optional install4j installation directory, if no auto-provisioning is desired:

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

### Task parameters

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

| Attribute | Description | Required | Global |
| --- | --- | --- | --- |
| installDir | The install4j installation directory. If this parameter is omitted, an install4j installation with the same version as the used plugin will be auto-provisioned. Auto-provisioned install4j distributions will be saved under `<Gradle use home>/install4j/dist`.   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. | No | Yes |
| autoProvisioningCacheDir | If the installDir parameter is omitted, a matching distribution of install4j will be auto-provisioned. By default, the auto-provisioned install4j distributions will be saved to `<Gradle use home>/install4j/dist`.   To override the cache directory, specify this property. | No | Yes |
| projectFile | The install4j project file that should be built. | Yes | No |
| variableFiles | Corresponds to the --var-file command-line option. Specify the list of variable files with variable definitions. | No | No |
| variables | A map of variable definitions. These definitions override [compiler variables](../concepts/variables.md) 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]. | No | No |
| 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. | No | No |
| destination | Corresponds to the --destination command-line option. Enter a directory where the generated media files should be placed. | No | No |
| 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]. | No | No |
| 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.   Note that you can also set the environment variable INSTALL4J_LICENSE_KEY to set the license key just for the current invocation. | 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. | No | Yes |
| preserve | Corresponds to the --preserve command-line option. Either true or false. | No | Yes |
| faster | Corresponds to the --faster command-line option. Either true or false. | No | Yes |
| disableSigning | Corresponds to the --disable-signing command-line option. Either true or false. | No | Yes |
| disableBundling | Corresponds to the --disable-bundling command-line option. Either true or false. | No | Yes |
| winKeystorePassword | Corresponds to the --win-keystore-password command-line option. | No | Yes |
| macKeystorePassword | Corresponds to the --mac-keystore-password command-line option. | No | Yes |
| disableNotarization | Corresponds to the --disable-notarization command-line option. | No | Yes |
| buildSelected | Corresponds to the --build-selected command-line option. Either true or false. | No | Yes |
| 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`. | No | Yes |
| 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. | No | Yes |

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 set up 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.

### Configuration cache

By default, the install4j tasks in the install4j Gradle plugin are never up to date and will run on every execution. This is because the task would have to perform a dry run to get a list of input files.

However, once you add file inputs to the install4j task, regular up-to-date checking will be done. File inputs are specified with method calls on the `inputs` property of a task:

```
task media(type: com.install4j.gradle.Install4jTask) {
  inputs.dir(stagingDir)
  inputs.files(file1, file2)
  ...
}
```

Then the task will be up to date if the inputs of its properties and your custom inputs are up to date with respect to the last task execution. In this way you can use the Gradle configuration cache which is otherwise supported by the install4j task.

### 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](createBundle.md) in the install4j installation and has the following properties:

| Attribute | Description | Required |
| --- | --- | --- |
| javaHome | The home directory of the JRE that should be bundled | Yes |
| 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"]
}
```
