# Using install4j with Maven

You can execute the install4j compiler from [maven](https://maven.apache.org/) with the install4j Maven plugin.

The install4j maven plugin is available from the Maven Central repository.

### Compile Mojo parameters

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

| 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 |
| autoProvisioningCacheDir | The location where auto-provisioned distributions of install4j will be stored. This is only used if the installDir is not set.  By default, the auto-provisioned install4j distributions will be saved to the OS-specific cache directory which is   `$LOCALAPPDATA%/install4jDist` on Windows `%HOME/Library/Caches` on macOS `$XDG_CACHE_HOME/install4jDist` or `$HOME/.cache/install4jDist` on Linux   To override the cache directory, specify this property.  User property of type `java.io.File`: install4j.autoProvisioningCacheDir | 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 in an OS-specific cache directory. See the autoProvisioningCacheDir property for more details. User property of type `java.io.File`: install4j.home | No |
| jvmArguments | Pass JVM arguments to the install4j command line compiler. The expected syntax in the POM is | 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. The expected syntax in the POM is   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>13.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.license>
      <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"](../concepts/files.md). 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](compiler.md).

| 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 |
| autoProvisioningCacheDir | The location where auto-provisioned distributions of install4j will be stored. This is only used if the installDir is not set.  By default, the auto-provisioned install4j distributions will be saved to the OS-specific cache directory which is   `$LOCALAPPDATA%/install4jDist` on Windows `%HOME/Library/Caches` on macOS `$XDG_CACHE_HOME/install4jDist` or `$HOME/.cache/install4jDist` on Linux   To override the cache directory, specify this property.  User property of type `java.io.File`: install4j.autoProvisioningCacheDir | 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 in an OS-specific cache directory. See the autoProvisioningCacheDir property for more details. 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.The expected syntax in the POM is  Corresponds to the `--add-jmod-dir` command-line option. | No |
| jmodFiles | JMOD files to be added to the JRE bundle. The expected syntax in the POM is  Corresponds to the `--add-jmod` command-line option. | No |
| jvmArguments | Pass JVM arguments to the install4j command line compiler. The expected syntax in the POM is | 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:

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