install4j Help - Ant task

To integrate install4j with your Ant script 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
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`.	No, verbose and quiet cannot both be `true`
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`.	No, test and incremental cannot both be `true`
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 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:

<install4j projectFile="myapp.install4j">
  <variable name="MY_VARIABLE" value="15"/>
  <variable name="OTHER_VARIABLE" value="test" mediaFileId="8"/>
</install4j>

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

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

<install4j projectFile="myapp.install4j" winKeystorePassword="Kajjs7sgLg22">
  <vmParameter value="-DproxySet=true"/>
  <vmParameter value="-DproxyHost=myproxy"/>
  <vmParameter value="-DproxyPort=1234"/>
  <vmParameter value="-DproxyAuth=true"/>
  <vmParameter value="-DproxyAuthUser=buildServer"/>
  <vmParameter value="-DproxyAuthPassword=iq4zexwb8et"/>
</install4j>

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 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.	Either file or dir must be set, but not both

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>

Using Install4j With Ant

Task parameters

Contained elements

Complete example

Creating JRE bundles