Creating the Demo Application Executable Installer

Introduction

The Windows installer is made using the NSIS compiler, which packages an executable from an installation script. During the installation process, the libraries, batch files, .dlls and compiled jar files need to copied over, a key needs to be generated, the media token drivers need to be registered on the system, and the paths in org.sharedrecords.properties, org.sharedrecords.demo.properties and launch.bat need to be set to the user's choice of installation directory.

Requirements

There are several third party utilities you will need to install in order to build the installer:

Utility	URL	Description
NSIS	http://nsis.sourceforge.net/Main_Page	used to create the install file
Launch4j	http://launch4j.sourceforge.net/index.html	used to create a wrapper for the executable once installed.
(_Optional_) Emma	http://emma.sourceforge.net/	used to test all unit tests prior to creation of the installer.
Magic ISO	http://www.magiciso.com/download.htm	used to create the ISO image of the install disk. NOTE: this program is shareware but can be used an unlimited number of times with images smaller that 300MB. The current installer is 29MB.

Files

There are several files in sharedrecords/ that pertain to packaging the installer.

File	Description
./install/sra-installer.nsi	the installation script that the MakeNSIS utility follows to package the installer. Any changes to the installation process should be made here.
./install/sra-data-installer.nsi	a bare-bones installation script that creates several necessary directories and does other minimal system setup, but does not install the Java application.
./install/PathSetup.class	a java class to be run in the middle of setup. It modifies the `org.sharedrecords` property files to properly reflect where the user has chosen to install the SRA Application, and is deleted before the installation process is over.
./install/PathSetup.java	the source code for the previous file. Every time path-specific lines are added to either of the properties files, it may be necessary to update PathSetup as well.
./install/SharedRecordsInstaller.exe	the resultant installer. It is a Windows executable that, when run by the user, installs the SRA Application hassle-free.
./SharedRecordsDemo.iso	a CD image that contains an autorunning installer.

Building

We have moved to using Apache Ant as an installer build system. It still uses the underlying NSIS compiler, but does so on the command line. The ant script lives in source:trunk/etc/build-install.xml, and has the following tasks:

• clean. This wipes any jars from the system that need to be rebuilt before the installer is compiled.
• create-jars. This repackages (as of present writing) lib/srcapi.jar, the library that contains the Shared Records Consortium API that is used at runtime. Every time there is a change to the internal codebase, srcapi.jar needs to be rebuilt to reflect this. This task also repackaged install/srcdemo.jar, the library that contains the GUI files of the Demo and the most recent results of the SWT port. Every time there is a change to the Demo application, srcdemo.jar should be rebuilt.
• create-keys. This generates a public/private key pair and places it in the correct location for the installer.
• nsis-compile. This task makes a system call that compiles the installation script into an executable. You need to have the makensis.exe binary in your PATH for this to work.

The last task contains the first three by default, so to rebuild the installer, you can do one of the following:

• From Eclipse: Right click on etc/build-install.xml, and select Run As -> Ant Build
• On the command line: Navigate to the etc/ directory, and execute

ant -buildfile build-install.xml nsis-compile

To keep the installer up to date, this should be done when any of the source files have been modified.

TroubleShooting

The most common errors when building the installer are listed below:

• Build fails because Java can not find JUnit, or Java cannot find Emma:

This is a known problem with the ANT classloader, as of the most recent version of ANT. You need to find ant-junit.jar (or emma-ant.jar) and remove it from your ANT_HOME directory. ant-junit.jar needs to be in the same folder as junit.jar, and emma-ant.jar needs to be in the same folder as emma.jar. Another note about Emma: Emma is used for development purposes to track how well the unit tests cover the code base. You do not need Emma or JUnit if you are not a developer and do not need to run the unit tests. build-install.xml no longer automatically runs the unit tests.