Caching auto-provisioned install4j distributions in CI pipelines

Starting with install4j 11.0, integrating install4j into your build system has become much easier: The Gradle, Maven, and Ant plugins can now auto-provision the install4j distribution. This means the plugins will download and cache the appropriate install4j version automatically, so you no longer need to install install4j manually.

Since 11.0.3, the distribution is cached in OS-specific locations using sensible defaults for each build system:

• Gradle caches to the Gradle user home (e.g. ~/.gradle)
• Maven and Ant cache to OS-specific locations: %LOCALAPPDATA%/install4jDist on Windows, $HOME/Library/Caches/install4jDist on macOS, and either $XDG_CACHE_HOME/install4jDist or $HOME/.cache/install4jDist on Linux.

While this works well for local development, it’s less ideal for CI environments where you often want full control over the caching location to speed up builds and avoid redundant downloads. That’s why in the upcoming install4j 11.0.4 release, we're introducing the optional autoProvisioningCacheDir property.

Quick plugin usage examples

Gradle (Kotlin DSL)

plugins {
  id("com.install4j.gradle") version "11.0.4"
}

install4j {
    // New optional global and task-level property in 11.0.4+
    autoProvisioningCacheDir = layout.buildDirectory.dir("custom-install4j-dist-cache").get().asFile
}

register<Install4jTask>("install4j") {
    projectFile = file("resources/main/installer/myProject.install4j")
}

Maven

<plugin>
  <groupId>com.install4j</groupId>
  <artifactId>install4j-maven-plugin</artifactId>
  <version>11.0.4</version>
  <executions>
      <execution>
        <id>compile-installers</id>
        <phase>package</phase>
        <goals>
          <goal>compile</goal>
        </goals>
        <configuration>
          <!-- New optional property in 11.0.4+ -->
          <autoProvisioningCacheDir>${project.build.directory}/custom-install4j-dist-cache</autoProvisioningCacheDir>
          <projectFile>${project.basedir}/resources/main/installer/myProject.install4j</projectFile>
        </configuration>
      </execution>
  </executions>
</plugin>

Ant

<taskdef name="install4j"
         classname="com.install4j.Install4JTask"
         classpath="ant.jar"/>

<target name="media">
  <!-- New optional task property in 11.0.4+ -->
  <install4j projectFile="myProject.install4j"
         autoProvisioningCacheDir="${basedir}/custom-install4j-dist-cache"/>
</target>

Caching in GitHub Actions

If you're using GitHub Actions for CI, you can ensure that the downloaded install4j distribution is cached across runs. Here's a simple example with a Gradle build using the default cache location:

name: Build with install4j

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Cache install4j distribution
        uses: actions/cache@v4
        with:
          path: ~/.gradle/install4jDist
          key: install4j-${{ runner.os }}-${{ hashFiles('**/build.gradle.kts') }}

      - name: Build
        run: ./gradlew build

To use a custom cache directory, define it as an environment variable:

env:
  INSTALL4J_CACHE_DIR: ${{ runner.temp }}/install4j-cache

...

- name: Cache install4j distribution
  uses: actions/cache@v4
  with:
    path: ${{ env.INSTALL4J_CACHE_DIR }}
    key: install4j-${{ runner.os }}-${{ hashFiles('**/build.gradle.kts') }}

And reference it in your Gradle build script:

install4j {
  autoProvisioningCacheDir = file(System.getenv("INSTALL4J_CACHE_DIR"))
}

This setup not only speeds up GitHub Actions builds, but also applies to any CI system where you can persist directories between runs, such as GitLab CI, Jenkins, or CircleCI.

Summary

While the auto-provisioning feature simplifies local development, the new autoProvisioningCacheDir option gives you full control in CI pipelines. With the 11.0.4 release, you’ll be able to manage where your install4j distributions are cached across all three supported build systems. This provides consistent and efficient builds across both developer and CI environments.