install4j Help

Using Install4j With Maven


You can execute the install4j compiler from maven with the install4j Maven plugin.

The install4j maven plugin is available from the following repository:

<pluginRepositories>
  <pluginRepository>
    <id>ej-technologies</id>
    <url>https://maven.ej-technologies.com/repository</url>
  </pluginRepository>
</pluginRepositories>

Compile Mojo parameters

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

 
Parameter Description Required
installDir The location of the install4j installation.

User property of type java.io.File: install4j.home

Yes
projectFile The install4j project file that should be build.

User property of type java.io.File: install4j.projectFile

Yes
appleIdPassword Set the app-specific password for notarizing macOS media files. This only has an effect when run on a macOS machine.

Corresponds to the --apple-id-password command line option.

User property of type java.lang.String: install4j.appleIdPassword

No
attach Attach generated installers. Uses the media file ID as the classifier.

User property of type boolean: install4j.attach

No
buildIds Only build the media files with the specified IDs, separated by commas.

Corresponds to the --build-ids command line option.

User property of type java.lang.String: install4j.buildIds

No
buildSelected Only build the media files which have been selected in the install4j IDE.

Corresponds to the --build-selected command line option.

User property of type boolean: install4j.buildSelected

No
debug Create additional debug installers for each media file.

Corresponds to the --debug command line option.

User property of type boolean: install4j.debug

No
destination The output directory for the generated media files. By default this is set to ${project.build.directory}/media, so this flag is always passed to the install4j compiler.

Corresponds to the --destination command line option.

User property of type java.io.File: install4j.destination

No
disableBundling Disable JRE bundling.

Corresponds to the --disable-bundling command line option.

User property of type boolean: install4j.disableBundling

No
disableNotarization Disable Notarization on macOS.

Corresponds to the --disable-notarization command line option.

User property of type boolean: install4j.disableNotarization

No
disableSigning Disable code signing.

Corresponds to the --disable-signing command line option.

User property of type boolean: install4j.disableSigning

No
failOnWarning If a warning is printed and this option is specified, the build will fail at the end.

Corresponds to the --fail-on-warning command line option.

User property of type boolean: install4j.failOnWarning

No
faster Disable LZMA and Pack200 compression.

Corresponds to the --faster command line option.

User property of type boolean: install4j.faster

No
incremental Enables incremental test execution. The parameters "test" and "incremental" cannot both be true.

Corresponds to the --incremental command line option.

User property of type boolean: install4j.incremental

No
jvmArguments Pass JVM arguments to the install4j command line compiler. No
license install4j license key. If the license has not been configured yet, you can set the license key with this attribute.

Corresponds to the --license command line option.

User property of type java.lang.String: install4j.license

No
macKeystorePassword Set the macOS keystore password for the private key that is configured for code signing.

Corresponds to the --mac-keystore-password command line option.

User property of type java.lang.String: install4j.macKeystorePassword

No
mediaTypes Only build media files of the specified types, separated by commas.

Corresponds to the --build-ids command line option.

User property of type java.lang.String: install4j.mediaTypes

No
preserve Preserve temporary staging directory.

Corresponds to the --preserve command line option.

User property of type boolean: install4j.preserve

No
quiet Enables quiet mode. The parameters "verbose" and "quiet" cannot both be true.

Corresponds to the --quiet command line option.

User property of type boolean: install4j.quiet

No
release Override the application version. By default this is set to ${project.version}, so this flag is always passed to the install4j compiler unless you set it to the special string #project.

Corresponds to the --release command line option.

User property of type java.lang.String: install4j.release

No
skip Skip execution.

User property of type boolean: install4j.skip

No
test Enables test mode. In test mode, no media files will be generated in the media file directory. The parameters "test" and "incremental" cannot both be true.

Corresponds to the --test command line option.

User property of type boolean: install4j.test

No
variableFiles Load variable definitions from files.

Corresponds to the --var-file command line option.

No
variables Override compiler variables with different values.

Corresponds to the -D command line option.

No
verbose Enables verbose mode. The parameters "verbose" and "quiet" cannot both be true.

Corresponds to the --verbose command line option.

User property of type boolean: install4j.verbose

No
winKeystorePassword Set the Windows keystore password for the private key that is configured for code signing.

Corresponds to the --win-keystore-password command line option.

User property of type java.lang.String: install4j.winKeystorePassword

No

Example

A minimal example is:

<build>
  <plugins>
    <plugin>
      <groupId>com.install4j</groupId>
      <artifactId>install4j-maven</artifactId>
      <version>9.0.5</version>
      <executions>
        <execution>
          <id>compile-installers</id>
          <phase>package</phase>
          <goals>
            <goal>compile</goal>
          </goals>
          <configuration>
            <installDir>/path/to/install4j</installDir>
            <projectFile>${project.basedir}/src/main/installer/myProject.install4j</projectFile>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Compilation can be skipped by setting the install4j.skip property on the command line:

mvn -Dinstall4j.skip

Using profiles for configuring parameters

Instead of using the installDir parameter, it is recommended to configure the installation location in settings.xml with the install4j.home user property:

<profiles>
  <profile>
    <id>development</id>
    <properties>
      <install4j.home>/path/to/install4j</install4j.home>
    </properties>
  </profile>
</profiles>

<activeProfiles>
  <activeProfile>development</activeProfile>
</activeProfiles>

Further parameters that are recommend to be configured in settings.xml are the license key and the passwords for code signing. The license key configuration is only required if it was not configured manually in advance for the user that is running the build.

<profiles>
  <profile>
    <id>development</id>
    <properties>
      <install4j.licenseKey>CHANGEME</install4j.licenseKey>
      <install4j.winKeystorePassword>SECRET</install4j.winKeystorePassword>
      <install4j.macKeystorePassword>SECRET</install4j.macKeystorePassword>
    </properties>
  </profile>
</profiles>

<activeProfiles>
  <activeProfile>development</activeProfile>
</activeProfiles>

Passing the build class path to the project

A common use case is the need to add all dependency JAR files from the build class path to the distribution tree. To do that, you first have to execute the "build-classpath" goal of the the "maven-dependency-plugin" to set a property with the class path:

<plugin>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>3.1.2</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>build-classpath</goal>
      </goals>
      <configuration>
        <outputProperty>my.classpath</outputProperty>
      </configuration>
    </execution>
  </executions>
</plugin>

In the configuration of the install4j plugin, you then pass this property as a compiler variable:

<configuration>
  ...
  <variables>
    <externalClassPath>${my.classpath}</externalClassPath>
  </variables>
</configuration>

On the "Files->Define distribution tree" step in the install4j step, you can add entries of type "Compiler variable". This type of entry will split the variable value with a configurable path separator and add all contained files. Continuing the above example, you have to add a compiler variable entry with the compiler variable name "externalClassPath" and the default path list separator ${compiler:sys.pathlistSeparator} to add all the dependency JAR files to the selected location in the distribution tree.

Attaching media files

Media files compiled by install4j can be attached to the Maven project when the attach parameter is set to true.

Attached files will be installed into the local repository and will also be deployed. The classifier for each deployed media files is the media file ID.

Creating JRE bundles

To create a JRE bundle from your Maven build, use the createbundle Mojo and set its javaHome property to the JRE that you want to create a bundle for.

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

 
Parameter Description Required
installDir The location of the install4j installation.

User property of type java.io.File: install4j.home

Yes
javaHome The home directory of the JRE that should be bundled.

User property of type java.io.File: install4j.bundleJavaHome

Yes
addModuleSet Add a set of modules to the JRE bundle, one of "MIN", "JRE", "ALL", "NONE". Corresponds to the --add-module-set command line option.

User property of type com.install4j.buildtools.ModuleSet: install4j.addModuleSet

No
addModules Comma-separated list of modules to be added to the JRE bundle. Corresponds to the --add-modules command line option.

User property of type java.lang.String: install4j.addModules

No
id Optional custom ID for the bundle. Corresponds to the --id command line option.

User property of type java.lang.String: install4j.bundleId

No
jdkProviderId JDK provider ID for the JDK that is specified with jdkRelease. Corresponds to the --jdk-provider-id command line option.

User property of type java.lang.String: install4j.jdkProviderId

No
jdkRelease Release of a JDK that provides the JDK tools. Required only if the bundled JRE does not contain the jlink tool. Corresponds to the --jdk-release command line option.

User property of type java.lang.String: install4j.jdkRelease

No
jmodDirs Directories with JMOD files to be added to the JRE bundle. Corresponds to the --add-jmod-dir command line option. No
jmodFiles JMOD files to be added to the JRE bundle. Corresponds to the --add-jmod command line option. No
jvmArguments Pass JVM arguments to the install4j command line compiler. No
outputDirectory Output directory for the bundle. Corresponds to the --output command line option.

User property of type java.io.File: install4j.bundleOutputDir

No
skip Skip execution.

User property of type boolean: install4j.skip

No
unpacked Create bundle with unpacked JAR files, required for macOS single bundle archives. Corresponds to the --unpacked command line option.

User property of type boolean: install4j.bundleUnpacked

No
version JRE version to be used, if different from the detected version. Corresponds to the --version command line option.

User property of type java.lang.String: install4j.bundleVersion

No

An example that shows the usage of this Mojo is:

<build>
  <plugins>
    <plugin>
      <groupId>com.install4j</groupId>
      <artifactId>install4j-maven</artifactId>
      <version>9.0.5</version>
      <executions>
        <execution>
          <id>create-jre-bundle</id>
          <phase>package</phase>
          <goals>
            <goal>createbundle</goal>
          </goals>
          <configuration>
            <installDir>/path/to/install4j</installDir>
            <javaHome>/usr/lib/jvm/jre-11/jre</javaHome>
            <outputDirectory>/home/build/projects/myProject/jreBundles</outputDirectory>
            <jmodFiles>
              <param>one.jmod</<param>
              <param>two.jmod</<param>
            </jmodFiles>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>