How to Create a Windows Installer for an SWT Application

How to Create a Windows Installer for an SWT Application

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.

Click to enlarge  
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:

Click to enlarge  
Figure 2. Java Build Path for SimpleText
  1. Create a /lib directory under the project root directory.
  2. Place a copy of org.eclipse.swt.win32.win32.x86_3.1.0.jar in the /lib directory.
  3. To let Eclipse know about the JAR, open the project’s properties, then select Java Build Path | Add JARs…, and browse for the .jar file in the project’s /lib directory (see Figure 2).
  4. 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
  5. Place swt-win32-3138.dll in 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:

  1. In Eclipse, create a text file called MANIFEST.MF, for the project.
  2. 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:

  1. Right-click on the project and select Export… | JAR file.
  2. 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).
    Click to enlarge  
    Figure 3. SimpleText’s JAR Package Specification
  3. 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.
  4. 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.MF file created in Step 2.
  5. Click Finish to have Eclipse create the JAR.
  6. 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:

  1. Create an /images subdirectory under the project root.
  2. Create an icon for the program and put it in the /images directory. Windows .ico files 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 .ico files directly, you can create .png files first, then merge them into an .ico file with png2ico.
  3. Create an /installer subdirectory under the project.
  4. Create a small (say 150×70) .bmp image for the application logo, and put it in the /installer directory.
  5. Create or find a 16×16 .ico file for the installer executable and put it in the /installer directory. 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:

  1. Download and install NSIS.
  2. Copy SimpleTextInstaller.nsi, the NSIS script, into the /installer directory.
  3. Search for SimpleText and replace it with the name of your application.
    Click to enlarge  
    Figure 4. SimpleText: Up and Running
  4. Search for Cogito Research and replace it with the name of your organization or company.
  5. Search for C: empSimpleTextinstaller and replace it with the path to your /installer directory.
  6. Modify /installer/License.txt as appropriate for your application.
  7. Under ;Files to be installed, list all files that are to be transferred to the end user’s computer. For SimpleText, the ;Files to be installed are:
    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"

    Note that $INSTDIR equates to the end user's Program FilesCompanyNameApplicationName directory and that the script uses the SetOutPath instruction to deploy files to different subdirectories.

  8. 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.

  9. In the Windows Explorer, right-click on your .nsi script, and select Compile NSIS Script. Assuming that there are no NSIS compile errors, this action should place a Windows installer in your /installer directory.
  10. 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.


Share the Post: