install4j Help

Using Install4j With Ant


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 not possible to copy the ant.jar archive to the lib folder of your ant distribution. You have to reference a full installation of install4j in the task definition.

Task parameters

The install4j task supports the following parameters:

AttributeDescriptionRequired
projectFileThe install4j project file that should be build.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.
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. 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
appleIdPassword Corresponds to the --apple-id-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:

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

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

     
    AttributeDescriptionRequired
    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 setup 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:

 
AttributeDescriptionRequired
javaHomeThe home directory of the JRE that should be bundledYes
outputDirectoryCorresponds 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:

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