# Using install4j With Ant

To integrate install4j with your [Ant script](https://ant.apache.org) use the Install4JTask that is provided in `$INSTALL4J_HOME/bin/ant.jar` and set theCreateBundleTask projectFile parameter to the install4j project file that you want to build.

To make the install4j task available to Ant, you must first insert a taskdef element that tells Ant where to find the task definition. Here is an example of using the task in an Ant build file:

```
<taskdef name="install4j"
         classname="com.install4j.Install4JTask"
         classpath="C:\Program Files\install4j\bin\ant.jar"/>

<target name="media">
  <install4j projectFile="myapp.install4j"/>
</target>
```

On macOS, the `ant.jar` file is inside the application bundle, for the default application directory the full path is `/Applications/install4j.app/Contents/Resources/app/bin/ant.jar`

The taskdef definition must occur only once per Ant build file and can appear anywhere on the top level below the project element.

Note that it is possible to copy the `ant.jar` archive to a location outside the install4j installation directory. In that case, an install4j installation with the same version as the ant.jar file will be auto-provisioned. Auto-provisioned install4j distributions will be saved under `$HOME/.install4jDist`.

### Task parameters

The install4j task supports the following parameters:

| Attribute | Description | Required |
| --- | --- | --- |
| projectFile | The install4j project file that should be built. | Yes |
| autoProvisioningCacheDir | If the ant.jar that is referenced in the taskdef is not contained in an install4j installation, a matching distribution of install4j will be auto-provisioned.   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. | No |
| verbose | Corresponds to the --verbose command-line option. Either true or false. | No, verbose and quiet cannot **both** be true |
| quiet | Corresponds to the --quiet command-line option. Either true or false. |
| failOnWarning | Corresponds to the --fail-on-warning command-line option. Either true or false. |
| 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 |
| incremental | Corresponds to the --incremental command-line option. Either true or false. |
| debug | Corresponds to the --debug command-line option. Either true or false. | No |
| preserve | Corresponds to the --preserve command-line option. Either true or false. | No |
| faster | Corresponds to the --faster command-line option. Either true or false. | No |
| disableSigning | Corresponds to the --disable-signing command-line option. Either true or false. | No |
| winKeystorePassword | Corresponds to the --win-keystore-password command-line option. | No |
| macKeystorePassword | Corresponds to the --mac-keystore-password command-line option. | No |
| disableNotarization | Corresponds to the --disable-notarization command-line option. | 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 |
| destination | Corresponds to the --destination command-line option. Enter a directory where the generated media files should be placed. | No |
| buildSelected | Corresponds to the --build-selected command-line option. Either true or false. | 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. | No |
| 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 |

### Contained elements

- The Install4JTask can contain variable elements. These elements 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 variablefile parameter.   The variable element supports the following parameters:      Attribute Description Required   name  The name of the variable. This must be the name of a variable that has been defined on the "General Settings->Compiler Variables" step.  Yes   value  The value for the variable. The value may be empty.  Yes   mediaFileId  The ID of the media file for which the variable should be overridden. The IDs for media files can be shown in the install4j IDE by choosing **Project → Show IDs** from the main menu.  No    Example:
- The install4j task can contain variablefile elements. These elements read text files containing compiler variables definitions. They correspond to the --var-file command-line option   The variablefile element supports the following parameters:      Attribute Description Required   file  The path of the variable file.  Yes
- The install4j task can contain vmParameter elements. These elements set VM parameters for the install4j command line compiler process.   The vmParameter element supports the following parameters:      Attribute Description Required   value  The value of the VM parameter.  Yes    Example for setting an HTTP proxy (an internet connection is required for Windows code signing):

### Complete example

The "hello" sample project includes an Ant 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

```
ant media
```

to start the build. If you have not defined install4jHomeDir in `build.xml`, the build will fail with a corresponding error message.

### Creating JRE bundles

To create a JRE bundle from your Ant build script, use the CreateBundleTask that is provided in `$INSTALL4J_HOME/bin/ant.jar` and set the javaHome parameter 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. Just like for the Install4JTask above, a taskdef element is required:

```
<taskdef name="createbundle"
         classname="com.install4j.CreateBundleTask"
         classpath="C:\Program Files\install4j\bin\ant.jar"/>

<target name="media">
  <createbundle javaHome="c:\Program Files\Java\jre"/>
</target>
```

The CreateBundleTask task supports the following parameters:

| 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 |

The CreateBundleTask task can contain vmParameter elements like the Install4JTask as well as jmod elements with the following parameters:

| Attribute | Description | Required |
| --- | --- | --- |
| file | Corresponds to the --add-jmod command-line option. | Either file or dir must be set, but not both |
| dir | Corresponds to the --add-jmod-dir command-line option. |

Example:

```
<createbundle javaHome="/usr/lib/jvm/jre-11/jre"
              outputDirectory="/home/build/projects/myProject/jreBundles"
              version="11"
              id="j3d">
    <jmod dir="/home/build/projects/myProject/jmods">
    <jmod file="/home/build/projects/myProject/otherJmods/one.jmod">
    <jmod file="/home/build/projects/myProject/otherJmods/two.jmod">
</createbundle>
```
