What's it all for?



Most Java developers are familiar with the power of Ant for writing build scripts, deployment scripts and sundry other tasks. Antigen wraps up an Ant script as an executable jar file and combines it with a user-friendly GUI.

The most obvious application is to use Antigen to create Installers. You write an Ant script to install your application, using the <input> task to prompt the user for configuration settings such as installation location, write a small properties file setting up window titles, icons etc and then run Antigen to wrap the whole lot up as an executable jar file.

When you're finished, you have a GUI based installer such as the one on the right. The end-user does not need Ant on their machine to use it, just Java.



Using Antigen

Antigen can be used to wrap your Ant script in two ways. The quickest way to get started is to use the Antigen tool (see QuickStart). Alternatively, you can include the Antigen jar file (known as Antibody) in your build process - this is particularly easy to do if you're using Maven to build your application.

Quick Start

If you have your Ant build.xml ready, this will take a few seconds.
  1. Debug your Ant script first! It's a lot quicker doing this on the commandline than when it's already wrapped up in Antigen
  2. Download and execute Antigen. While you are waiting...
  3. Place the build.xml and any files the Ant script needs (such as property files) into a folder (e.g. called ant)
  4. Optional: create a configuration file called config.properties in another folder (e.g. called resources)
    • For a very simple installer, config.properties can be empty. To jazz it up a bit, see Configuration options
  5. Antigen will pop up an info screen, and then ask you to select the tasks you wish to run. If you have prepared a custom config.properties file, then check the "Customize your Installer" box.
  6. The Antigen app will prompt you for the name of your project, and the name of the installer you wish to create
  7. Since Antigen wraps up Ant and various other libraries, the resulting installer can get quite large. Antigen will give you the option to remove stuff you don't use. If you're not using any of the optional Ant tasks, or you don't have intro or outtro pages (see Intro Pages, you can cut the size of the installer in half by telling Antigen to omit the irrelevant libraries.
  8. Finally Antigen will prompt your for the names of the folder(s) you created earlier
If all goes well, it should have created an executable jar for you. Unless you changed the config double-clicking on this jar file should execute your script's default target.

Problems

Debugging

The easiest way to debug is to run your installer from the commandline - debug information will be echoed to the console. For extra debug information use the -d switch.

More advanced...

Configuration options

Trying to keep pace with the number of options is probably futile, so here is a link to the latest config.properties file in cvs, which should be documented well enough to work things out.

The main things to note are:

Location of logos and other resources

Logos and other resources should be placed under the folder containing the config.properties file. Thus, to set the top right logo and the intro text you place entries in the config.properties file of

antigen.logo.right=img/logo.jpg

antigen.intro.template=velocitytemplates/hello.html

and have a directory structure 


  
<>
Setting the Ant target(s) you wish to execute







    

      
 
By default (!) the default target in your build file is executed.
Alternatively, you can specify the target(s) in the config.properties
file.
If you specify more than one target (as a comma-separated list), then
the user will be presented with with a list of check boxes to determine
which targets to run. You can configure some checkboxes to be unchecked
by default.
Antigen will run the targets in the order they are listed, and ant
properties are inherited from one to the next. This is useful
since users will not be prompted twice for the same input property.

      

  





Intro and Outtro pages and Velocity Templates

 You can specify text to be shown to the user
before and after the installation process. This is quite handy for
warning him or her what is about to happen! You can either specify the
text in the property file, or provide a reference to a text file (see Location of logos and other resources). In both
cases the text supplied should be html formatted. In the latter case,
the text is always processed by Velocity (and therefore
the velocity library must not be excluded from the installer if this
feature is used!). This is very powerful, and allows you to interpolate
ant properties in your text, and show text conditionally based in
property settings. Note, that velocity does not allow properties to
include a period as part of their name, so these are replaced with
underscores in the velocity engine. Thus if your ant file includes a
task


<input addproperty="your.name">Enter your name</input>


then in your outtro text you can do things like: 

    
        Goodbye $your_name!    


  

Prompting the user for input

 Any <input/> tags in your buildfile will cause a
dialog box to be opened to prompt the user for input. The exact form of
this dialog depends on a number of things. If the validargs
attribute has been set to restrict the user input, then the dialog will
have radio buttons for the user to select. If you wish the user to
enter a file name or dir name, then it is possible to configure antigen
to recognise certain property suffices such as .file or .dir
as representing files and directories, and the dialog box will include
a browse button to allow the user to select the file from their file
system. In all cases the dialog boxes are prepopulated with the
contents of the defaultvalue attribute, if present. As is
standard practice in Ant 1.6+, if a property is already set, then the
input task will be skipped.

Command-line options
 Antigen has a number of options that can be specified on the
commandline. To view them type

java -jar myinstaller.jar -h
 These options include increasing the debug logging output for when
your installer isn't working as it ought to, and running the installer
in a text-only environment.

Using Antibody as part of a Maven build

Coming soon....in the meantime, you should be able to work out how to
do it from looking at the build of Antigen itself....Antigen
was built with Antigen.  You can install the entire source tree on
your machine by downloading and running the Source Code
Installer.  Like everything else, this was created from an Ant
script wrapped by Antigen.


Adding optional Ant Tasks to the installer

By default the installer will include


though the option is given to remove these last two when you build your
installer in order to reduce its size.




If you feel strongly that other tasks should be included by default
please get in touch.




If you wish to include more jars in your installer then you have two
options:

    
  
  • If using Maven to build
your installer add the jars to the <dependencies> section of your
project.xml file
    • 
  
  • If using Antigen to build the installer, you can enter additional
jars if you check the 'Bundle additional jars into Installer' box. You
will then be prompted to locate a directory containing these jars when
the installer is built.
    •