The Laying out your project files for a Maven build page describes the overall layout of a maven project.
To compile IzPack using Maven, use the izpack-maven-plugin. There is good documentation at the izpack-maven-plugin page, but this page will describe how to use the most recent IzPack plugin.
Custom IzPack panels are supported and are discussed in the "Using Custom Panels" section.
Create a separate Maven project that will produce your izPack installer. You can refer to the IzPack Maven Plugin Reference section for details on the plug-in and the meaning of the configuration settings.
The basic strategy is as follows:
maven-antrun-plugin
to copy our izPack descriptor file and resources into this "staging" area. maven-dependency-plugin
to copy the jar with our custom panels, and any other jar dependencies that we want in our installer. Two different "executions" of the maven-dependency-plugin may be required
; one to copy our application jars into one location, and if there are custom panels, another to copy the custom panel jars into a separate location.izpack-maven-plugin
to point it to our staging area and our installer descriptor.pom
, so let's configure it as a <property>
to make things clearer. Also configure the izPack version.pom
file:<properties> <izpack.version>5.0.9</izpack.version> <izpack.staging>${project.build.directory}/staging</izpack.staging> </properties> |
Notes:
${project.build.directory}
references the compilation ./target/ directory of your module<jar src=
"@{izpack.staging
}/lib/appcore.jar"
/>
This only applies to properties defined in the compiling project.<dependencies> <dependency> <groupId>com.mycompany</groupId> <artifactId>myapplication</artifactId> <version>1.0-SNAPSHOT</version> </dependency> <dependency> <groupId>com.mycompany</groupId> <artifactId>myapplication-utilities</artifactId> <version>1.0-SNAPSHOT</version> </dependency> <dependency> <groupId>com.mycompany</groupId> <artifactId>mycustompanels</artifactId> <version>1.0-SNAPSHOT</version> </dependency> </dependencies> |
Use the maven-antrun-plugin
to copy the installer descriptor and installer resources (images, text files, etc.) into the "staging" area.
Put the installer descriptor and resources underneath src/izpack
in your module. In the pom's <build>
section, configure the maven-antrun-plugin
to copy this entire directory to the staging area:
<plugin> <artifactId>maven-antrun-plugin</artifactId> <executions> <execution> <id>create-staging-area</id> <phase>process-resources</phase> <goals> <goal>run</goal> </goals> <configuration> <tasks> <copy todir="${izpack.staging}"> <fileset dir="${basedir}/src/izpack"/> </copy> </tasks> </configuration> </execution> </executions> </plugin> |
Configure the maven-depenency-plugin
to copy the application's jars.
If there are custom panels, copy its jar as well.
Example with custom panels (see the inline XML comments for more details):
<plugin> <artifactId>maven-dependency-plugin</artifactId> <configuration> <excludeTransitive>false</excludeTransitive> <!-- reference our custom panels jar in our installer descriptor without its version --> <stripVersion>true</stripVersion> <overWriteReleases>true</overWriteReleases> <overWriteSnapshots>true</overWriteSnapshots> <overWriteIfNewer>true</overWriteIfNewer> </configuration> <executions> <execution> <!-- copy *application* jars to izpack staging lib --> <id>copy-product-dependencies</id> <phase>prepare-package</phase> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${izpack.staging}/lib</outputDirectory> <excludeScope>system</excludeScope> <!-- this excludes tools.jar, e.g. --> <excludeArtifactIds>mycustompanels</excludeArtifactIds> <!-- IMPORTANT: don't copy custom panels where our application jars live --> <excludeGroupIds>org.codehaus.izpack</excludeGroupIds> <!-- IMPORTANT: we don't want to copy the IzPack dependency where our application jars live --> </configuration> </execution> <execution> <!-- copy izpack custom (custom panels, etc.) jars to izpack staging custom --> <id>copy-izpack-dependencies</id> <phase>prepare-package</phase> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${izpack.staging}/custom</outputDirectory> <includeArtifactIds>mycustompanels</includeArtifactIds> <!-- IMPORTANT: this causes *only* our custom panels to be copied --> </configuration> </execution> </executions> </plugin> |
Some key points:
execution
section configures the copying of our application jars to the lib/
directory under our staging directory (i.e., target/staging/lib
). Note that we have to explicitly exclude the IzPack dependency as well as any custom panels dependency. We don't need these showing up in our installed application!execution
section configures the copying of our custom panels jar to the custom/
directory under our staging directory (i.e., target/staging/custom
). Note that we explicitly include our custom panels dependency so that no other jars are copied to custom/
. It wouldn't hurt anything if this happened, but why do unnecessary work?maven-dependency-plugin
is very configurable. You may need to customize some of this configuration for your own purposes.izpack-maven-plugin.
This is our staging area.<plugin> <groupId>org.codehaus.izpack</groupId> <artifactId>izpack-maven-plugin</artifactId> <version>${izpack.version}</version> <executions> <execution> <phase>package</phase> <goals><goal>izpack</goal></goals> <configuration> <!-- base for relative paths in izpack descriptor --> <baseDir>${izpack.staging}</baseDir> <installFile>${basedir}/src/izpack/install.xml</installFile> </configuration> </execution> </executions> <dependencies> <dependency> <groupId>org.codehaus.izpack</groupId> <artifactId>izpack-panel</artifactId> <version>${izpack.version}</version> </dependency> . . . </dependencies> </plugin> |
Your installer descriptor should reference resources and jars relative to the staging area. For example, here is a resources section in our installer descriptor (i.e., install.xml):
<resources> <res src="@{izpack.staging}/common_resources/img/install-sidebar.png" id="Installer.image"/> <res src="hello.html" id="HTMLHelloPanel.info"/> <res src="license.html" id="HTMLLicencePanel.licence"/> </resources> |
Note: these resources are originally under src/izpack
. They are copied from this directory to the staging area, where the IzPack compiler will look for them.
When finished, the entire build section of our pom should look something like this:
. . . <build> <plugins> <!-- copy izpack resources into izpack staging area, expected by izpack.xml --> <plugin> <artifactId>maven-antrun-plugin</artifactId> <executions> <execution> <id>create-staging-area</id> <phase>process-resources</phase> <goals> <goal>run</goal> </goals> <configuration> <tasks> <copy todir="${izpack.staging}"> <fileset dir="${basedir}/src/izpack"/> </copy> </tasks> </configuration> </execution> </executions> </plugin> <plugin> <artifactId>maven-dependency-plugin</artifactId> <configuration> <excludeTransitive>false</excludeTransitive> <stripVersion>true</stripVersion> <overWriteReleases>true</overWriteReleases> <overWriteSnapshots>true</overWriteSnapshots> <overWriteIfNewer>true</overWriteIfNewer> <excludeScope>system</excludeScope> </configuration> <executions> <execution> <!-- copy product jars to izpack staging lib --> <id>copy-product-dependencies</id> <phase>prepare-package</phase> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${izpack.staging}/lib</outputDirectory> <excludeScope>system</excludeScope> <!-- this excludes tools.jar, e.g. --> <excludeArtifactIds>mycustompanels</excludeArtifactIds> <excludeGroupIds>org.codehaus.izpack</excludeGroupIds> </configuration> </execution> <execution> <!-- copy izpack custom (custom panels, etc.) jars to izpack staging custom --> <id>copy-izpack-dependencies</id> <phase>prepare-package</phase> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${izpack.staging}/custom</outputDirectory> <includeArtifactIds>mycustompanels</includeArtifactIds> </configuration> </execution> </executions> </plugin> <plugin> <groupId>org.codehaus.izpack</groupId> <artifactId>izpack-maven-plugin</artifactId> <executions> <execution> <phase>package</phase> <goals> <goal>izpack</goal> </goals> <configuration> <!-- base for relative paths in izpack descriptor --> <baseDir>${izpack.staging}</baseDir> <installFile>${basedir}/src/izpack/install.xml</installFile> </configuration> </execution> </executions> <dependencies> <dependency> <groupId>org.codehaus.izpack</groupId> <artifactId>izpack-panel</artifactId> <version>${izpack.version}</version> </dependency> <dependency> <groupId>com.mycompany</groupId> <artifactId>mycustompanels</artifactId> <version>1.0-SNAPSHOT</version> </dependency> </dependencies> </plugin> </plugins> </build> . . . |
As mentioned at the start of this article, the dependencies of your application are project dependencies and need to be specified as normal Maven dependencies in the project's dependencies section.
. . . </build> <dependencies> <dependency> <groupId>com.mycompany</groupId> <artifactId>myapplication</artifactId> <version>1.0-SNAPSHOT</version> </dependency> <dependency> <groupId>com.mycompany</groupId> <artifactId>mycustompanels</artifactId> <version>1.0-SNAPSHOT</version> </dependency> </dependencies> </project> |
If you have custom panels, they should be developed in a separate Maven project. This is a standard Maven project, but you should include izPack as a provided dependency:
<dependencies> <dependency> <groupId>org.codehaus.izpack</groupId> <artifactId>izpack-compiler</artifactId> <version>${izpack.version}</version> <scope>provided</scope> </dependency> </dependencies> |
We use scope = provided because we only need Maven to use the IzPack dependency at compile time.
In this project, you can create your custom IzPack panels.
maven-dependency-plugin
to copy the custom panel jar to the staging area.This example include a section for custom panels which may be omitted if it does not apply.
<plugin> <groupId>org.codehaus.izpack</groupId> <artifactId>izpack-maven-plugin</artifactId> <version>${izpack.version}</version> <executions> <execution> <phase>package</phase> <goals><goal>izpack</goal></goals> <configuration> <!-- base for relative paths in izpack descriptor --> <baseDir>${izpack.staging}</baseDir> <installFile>${basedir}/src/izpack/install.xml</installFile> </configuration> </execution> </executions> <dependencies> <dependency> <groupId>org.codehaus.izpack</groupId> <artifactId>izpack-panel</artifactId> <version>${izpack.version}</version> </dependency> <dependency> <groupId>com.mycompany</groupId> <artifactId>mycustompanels</artifactId> <version>1.0-SNAPSHOT</version> </dependency> </dependencies> </plugin> |
execution
section to copying of the custom panels jar to the custom/
directory under our staging directory (i.e., target/staging/custom
). Note that we explicitly include our custom panels dependency so that no other jars are copied to custom/
. It wouldn't hurt anything if this happened, but why do unnecessary work.When finished, the entire build section of the pom should look something like this:
<?xml version="1.0"?> . . . <build> <plugins> <!-- copy IzPack resources into IzPack staging area, expected by izpack.xml --> <plugin> <artifactId>maven-antrun-plugin</artifactId> <executions> <execution> <id>create-staging-area</id> <phase>process-resources</phase> <goals> <goal>run</goal> </goals> <configuration> <tasks> <copy todir="${izpack.staging}"> <fileset dir="${basedir}/src/izpack"/> </copy> </tasks> </configuration> </execution> </executions> </plugin> <plugin> <artifactId>maven-dependency-plugin</artifactId> <configuration> <excludeTransitive>false</excludeTransitive> <stripVersion>true</stripVersion> <overWriteReleases>true</overWriteReleases> <overWriteSnapshots>true</overWriteSnapshots> <overWriteIfNewer>true</overWriteIfNewer> <excludeScope>system</excludeScope> </configuration> <executions> <execution> <!-- copy product jars to izpack staging lib --> <id>copy-product-dependencies</id> <phase>prepare-package</phase> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${izpack.staging}/lib</outputDirectory> <excludeScope>system</excludeScope> <!-- this excludes tools.jar, e.g. --> <excludeArtifactIds>mycustompanels</excludeArtifactIds> <excludeGroupIds>org.codehaus.izpack</excludeGroupIds> </configuration> </execution> <execution> <!-- copy izpack custom (custom panels, etc.) jars to izpack staging custom --> <id>copy-izpack-dependencies</id> <phase>prepare-package</phase> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${izpack.staging}/custom</outputDirectory> <includeArtifactIds>mycustompanels</includeArtifactIds> </configuration> </execution> </executions> </plugin> <plugin> <groupId>org.codehaus.izpack</groupId> <artifactId>izpack-maven-plugin</artifactId> <executions> <execution> <phase>package</phase> <goals> <goal>izpack</goal> </goals> <configuration> <!-- base for relative paths in izpack descriptor --> <baseDir>${izpack.staging}</baseDir> <installFile>${basedir}/src/izpack/install.xml</installFile> </configuration> </execution> </executions> <dependencies> <dependency> <groupId>org.codehaus.izpack</groupId> <artifactId>izpack-panel</artifactId> <version>${izpack.version}</version> </dependency> <dependency> <groupId>com.mycompany</groupId> <artifactId>mycustompanels</artifactId> <version>1.0</version> </dependency> </dependencies> </plugin> </plugins> </build> |
Also, don't forget to tell the IzPack compiler about your custom panels jar in the <resources>
element in your install.xml
file:
<jar src="custom/mycustompanels.jar"/>
You should see now why we use the |
Here's an example of referencing a custom panel. Again, in our installer descriptor:
<panels> <panel classname="com.mycompany.izpack.panel.MyHelloPanel"/> <panel ......../> <panel ......../> </panels> |
Note that we use the fully qualified name of the panel class.
There are a few simple things to check if your installer is not created properly.
[1] http://izpack.codehaus.org/izpack-maven-plugin/
[2] https://github.com/aspear/izpack5-example-installer