install4j Help - Maven plugin

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
projectFile	The install4j project file that should be built. User property of type `java.io.File`: install4j.projectFile	Yes
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 for macOS media files. 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
installDir	The location of the install4j installation. If not specified, an install4j distribution with the same version as this plugin will be auto-provisioned. Auto-provisioned install4j distributions will be saved under `$HOME/.install4jDist`. User property of type `java.io.File`: install4j.home	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 the 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>11.0.1</version>
      <executions>
        <execution>
          <id>compile-installers</id>
          <phase>package</phase>
          <goals>
            <goal>compile</goal>
          </goals>
          <configuration>
            <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

If you do not wish to auto-provision an install4j installation, 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 recommended 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.

Note that you can also set the environment variable INSTALL4J_LICENSE_KEY to set the license key just for the current invocation.

<profiles>
  <profile>
    <id>development</id>
    <properties>
      <install4j.license>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 "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 file 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
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
installDir	The location of the install4j installation. If not specified, an install4j distribution with the same version as this plugin will be auto-provisioned. Auto-provisioned install4j distributions will be saved under `$HOME/.install4jDist`. User property of type `java.io.File`: install4j.home	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 a 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: