A quick start demo application is provided for those who don't like reading documentation
The example application is in the demo directory and installs a "hello world" application to a user selected directory. Look at the
file to see how the installer UI is configured and the
file should be familiar to users of Ant.
Run the installer with the start script and look at the
file to see how the properties have been collected from the user and look at the
to see the results of the install. N.B. passwords do not appear in the properties file but are passed to Ant at runtime. If the properties cannot be written to the curent directory it will silently be ommited this is to facilitate installing from read-only media. To view the properties file for debug purposes ensure you have write permissions to the current directory.
You should then look at the
file to see how to create a self-extracting jar.
N.B. You could build the self extracting jar for your installer with any jar tool but using Ant is highly recommended. There is an Ant task to create your installer jar called
There are three methods for running AntInstaller, the demo uses the SelfExtractor.
- SelfExtractor - a single Jar file that is extracted into a temporary directory before the UI is shown.
- NonExtractor - a single Jar file which runs the UI, during the Ant phase resoureces can be extracted from the Jar with the unjar Ant task.
- Scripted Installs - a directory structure is delivered, for example a CD, the installer is launched with a script.
Order of events
AntInstall takes the following steps to run an install.
- If installing from the self-extracting jar, the first thing is to extract the whole Jar to a temporary directory. The NonExtractor mode runs straight from the Jar leaving extracting resources to the Ant stage.
- AntInstaller then checks to see if graphical user interface can be run or if it should use the text/console UI
- Either the Swing GUI or text UI is launched, the user fills in the required properties and/or selects from the options. Properties will be collected and a list of Ant targets to run will be made.
- AntInstaller writes out the properties selected in file in the current directory (or the temporary directory if loading from the self extracting jar)
- Ant is launched and looks for the build.xml file. The properties are passed to Ant.
- The Ant targets selected are then run in order, potentially re-running tasks if you have depends attributes in the build.xml script. (not recommended)
- The Progress page allows users in the GUI to view or ignore the Ant output. The text console will have all the ant output shown.
- Assuming no exceptions, the installer can then be exited.
There is a wizard to help generate the files for your installer.
The tool assumes you have a standard Java project structure with a root directory for your projects and a base directory for each project. For example, if you use Eclipse the projects root directory is your workspace and the project directory would be the module name in CVS. The directory structure is not imposed but it sets some defaults.
Run the wizard script and enter the projects root (workspace) and short name which is the name of the subdirectory under projects root where the resources for the project exist.
If you don't have a specific license for your project leave the default.
Click next, and select the components for the installer. For each box checked you will be asked for a directory.
When you have selected the directories in the subsequent pages, click the Create Project button and the wizard creates the files listed below.
- antinstall-config.xml - basic configuration for the UI
- build.xml - the build file to be run during the installation
- create-installer.xml - an Ant build script to build the installer
- [Project short name]-installer.jar - the installer jar (if you selected the create installer box)
- build-self-extractor.sh - linux build script in case you dont have Ant installed (nothing complex if you need to convert this to windows)
It is not expected that the installer created by this wizard will be the installer of your dreams
Presumably you chose AntInstaller for its infinite flexibility, so now you customise and configure the installer to meet your needs.
The wizard gives you a starting point. From here you will probably want to copy sections of
into your own Ant build, add user properties and targets to
and develop the
that is run during the install.
For a detailed guide to the features of AntInstaller the manual
as a reference for the
file and the Ant documentation