ative Windows installers offer unparalleled integration with the operating system, as well as a familiar installation process for your users?they just double-click on the installer, click Next a few times, and then click Finish. In this 10-Minute Solution, you will learn how to build a native Windows installer for an SWT application using open source tools. The primary advantage of open source tools like the Nullsoft Scriptable Install System (NSIS) relative to commercial tools like InstallShield is the purchase price?free.
This article assumes that an SWT application has already been built and runs fine on the developer’s machine. The sample application included in the downloadable code is a simple text editor named?what else??SimpleText (see Listing 1). This discussion follows a step-by-step procedure that generates an executable Windows installer (see Figure 1) that can install SimpleText in the client’s
Program Files directory, add Start Menu shortcuts, and uninstall the application.
|Figure 1. A Screenshot of the SimpleText Installer|
Most of the steps described below are relevant to any Java developer looking to create a Windows installer for his or her application. However, the specific build environment for SimpleText is JDK 5.0 (a.k.a. 1.5) and Eclipse 3.1.
You want to create a Windows installer for your Java SWT application.
Create an executable JAR, then use free, open source tools like NSIS and png2ico to create an executable installer for Windows.
Step 1: Organize Your Libraries
The proper placement and referencing of libraries is critical for Java SWT applications. My sample application, SimpleText, depends on the SWT Win32 JAR,
org.eclipse.swt.win32.win32.x86_3.1.0.jar, as well as the SWT Win32 DLL,
swt-win32-3138.dll. Note that in newer versions of Eclipse, the DLL is actually archived in the SWT Win32 JAR. The following steps prepare the JAR and DLL for export and installation:
|Figure 2. Java Build Path for SimpleText|
- Create a
/libdirectory under the project root directory.
- Place a copy of
- To let Eclipse know about the JAR, open the project’s properties, then select Java Build Path | Add JARs…, and browse for the
.jarfile in the project’s
/libdirectory (see Figure 2).
- Extract the Windows-specific DLL from the SWT Win32 JAR, using the following command-line:
jar xf org.eclipse.swt.win32.win32.x86_3.1.0.jar swt-win32-3138.dll
swt-win32-3138.dllin the root of the project directory. Note that while it is possible to load the DLL at runtime and thereby avoid extracting it from the JAR, that approach is not covered here. Also note that you do not need to worry about extracting the other DLL’s from the SWT Win32 JAR.
Step 2: Create a Manifest
The JAR manifest,
MANIFEST.MF, identifies the application’s main class as well as the JARs upon which the application depends:
- In Eclipse, create a text file called
MANIFEST.MF, for the project.
- Add the manifest version, main class, and classpath to it as shown below:
Manifest-Version: 1.0Main-Class: com.cogitoresearch.simpletext.MainWindowClass-Path: lib/org.eclipse.swt.win32.win32.x86_3.1.0.jar
Step 3: Create an Executable JAR
An executable JAR contains your Java .class files, the manifest, and resources (such as images) that your application needs. To create one in Eclipse, follow these steps:
- Right-click on the project and select Export… | JAR file.
- In the JAR Package Specification, check only the source directories and individual resource files your application needs. For example, SimpleText uses an image resource file,
SimpleText16x16.gif, for its SWT shell icon, so that GIF is included in the JAR (see Figure 3).
Figure 3. SimpleText’s JAR Package Specification
- Set the JAR file field to the desired path and filename. The path should be the same as the path for the SWT Win32 DLL. This is important because the executable JAR’s directory is our application startup directory, and the application startup directory is one of the places that Windows will automatically search when looking for DLLs.
- Click Next and then Next again to get to the JAR Manifest Selection page. Select “Use existing manifest from workspace,” and browse to the
MANIFEST.MFfile created in Step 2.
- Click Finish to have Eclipse create the JAR.
- In Windows Explorer, double-click the JAR to verify that the program runs as expected.
Step 4: Create Icons and Images
Now we need to create two icons (
.ico) and a bitmap (
.bmp). One icon is for display in the Windows Start Menu and one is for the installer application itself. The bitmap will be used to display a logo during installation:
- Create an
/imagessubdirectory under the project root.
- Create an icon for the program and put it in the
.icofiles can contain multiple icons of different sizes (16×16, 32×32, and 48×48 are typical). If you do not have a tool that creates Windows
.icofiles directly, you can create
.pngfiles first, then merge them into an
.icofile with png2ico.
- Create an
/installersubdirectory under the project.
- Create a small (say 150×70)
.bmpimage for the application logo, and put it in the
- Create or find a 16×16
.icofile for the installer executable and put it in the
setup.ico, which is included with the downloadable samples for this article, is a standard Windows setup icon.
Step 5: Create an NSIS Installer Script
NSIS is an open-source tool for the development of professional-grade Windows installers. It sports standard features such as install, shortcut creation, and uninstall, as well as many advanced features such as custom dialogs, system reboots, and DLL/ActiveX control registration. A complete discussion of NSIS usage is beyond the scope of this article, so I will simply focus on what changes would need to be made to
SimpleTextInstaller.nsi (see Listing 2) to get it to work for your own application:
- Download and install NSIS.
SimpleTextInstaller.nsi, the NSIS script, into the
- Search for
SimpleTextand replace it with the name of your application.
Figure 4. SimpleText: Up and Running
- Search for
Cogito Researchand replace it with the name of your organization or company.
- Search for
C: empSimpleTextinstallerand replace it with the path to your
/installer/License.txtas appropriate for your application.
;Files to be installed, list all files that are to be transferred to the end user’s computer. For SimpleText, the
;Files to be installedare:
SetOutPath "$INSTDIR"File "C: empSimpleTextSimpleText_1.0.jar"File "C: empSimpleTextimagesSimpleText.ico"File "C: empSimpleTextswt-win32-3138.dll"SetOutPath "$INSTDIRlib"File "C: empSimpleTextliborg.eclipse.swt.win32.win32.x86_3.1.0.jar"SetOutPath "$INSTDIR"
$INSTDIRequates to the end user's
Program FilesCompanyNameApplicationNamedirectory and that the script uses the
SetOutPathinstruction to deploy files to different subdirectories.
- Have a look at the section in Listing 2 labeled
"Start Menu Shortcuts."It contains entries to create a SimpleText folder in the Windows Start Menu (under All Programs). The last line in the section,
CreateShortCut "$SMPROGRAMSSimpleTextSimpleText.lnk" "$INSTDIRSimpleText_1.0.jar" "" "$INSTDIRSimpleText.ico"
is the instruction that creates the start menu launcher for the application. It assumes that the required JRE is already installed on the system.
- In the Windows Explorer, right-click on your
.nsiscript, and select Compile NSIS Script. Assuming that there are no NSIS compile errors, this action should place a Windows installer in your
- Be sure to test the installer on both the development machine and at least one end user machine. When installed and running, SimpleText appears as shown in Figure 4.