A common question we see in the newsgroups is "Where do I get the free version of InstallShield," or something along those lines. The truth is that deploying PowerBuilder applications is so easy (in most cases) that a full-blown, large commercial tool like InstallShield is overkill (especially when coupled with a behemoth of complexity such as Windows Installer).

Unbeknownst to many, there are a few open-source and freeware installation tools available that are quite capable of creating a setup/installer program for a typical PowerBuilder application. We'll look at my favorite of these, NSIS (Nullsoft Install System), brought to you by the same folks responsible for creating WinAmp, the most popular MP3 player on Windows. They created NSIS internally as a tool to distribute WinAmp and its plug-ins, but made it powerful and flexible enough to be usable for a wide range of applications and also placed it under an open-source license, which resulted in other developers writing custom extensions for it.

One of the biggest strengths of NSIS is its built-in scripting language as well as its extremely low overhead (depending on the options, it adds only about 20-40KB overhead to an installation program versus around 2MB for InstallShield). That's why companies as large as Sun Microsystems have used it to deploy some of their products (Java WebStart). Since WinAmp is one of the most popular programs in the Windows world, I suspect many of you have already seen NSIS in action when you installed WinAmp on your PC.

Where to Get NSIS and What It Can Do
NSIS is available for download from www.nullsoft.com/free/nsis/. At the time of writing it was at version 1.98, and this is the one we'll be discussing. Simply install the NSIS compiler on your PC. On the Nullsoft Web site you can get the complete list of features as well as detailed documentation, but in essence NSIS's most important capabilities are:

• File extraction (of course)
• File/directory copying/renaming/deletion
• Built-in scripting language
• Shortcut creation
• Registry key reading/writing/creating
• INI file reading/writing

NSIS is distributed only as a standalone compiler (makensis.exe) that you use to compile installation scripts (ending with the *.nsi extension). There are some GUIs available for it, but to be honest I find working directly with the installation scripts in any decent text editor much faster (JEdit 4.0 is my favorite, due to its built-in scripting capabilities). Once you have a script completed, just compile it from the command line (see Figure 1):

makensis.exe myscript.nsi

That's all that's necessary to create a standalone installer. If you selected to install the NSIS shell extensions (which are enabled by default), then you also have the option of right-clicking on an *.nsi file; the Windows context menu should show a "Compile NSI" right-click option for you.

Admittedly, the built-in scripting language of NSIS is a bit more low-level than the C-based syntax of InstallShield (Nullsoft describes it as a mix between assembler and PHP), but it really isn't that complicated and any programmer with experience should be able to master it in a day or so. However, its small size and flexibility are ample reward for that extra learning curve at the beginning.

Basic Command Syntax
NSIS commands are formatted according to the following:

command parameter1 parameter2 parameter3 ...etc...

The command comes first and the parameters are separated by spaces, for example:

CreateShortCut "$SMPROGRAMS\NSIS\ZIP2EXE project workspace.lnk"
"$INSTDIR\source\zip
2exe\zip2exe.dsw"

I recommend you read through the documentation that comes with NSIS (available online at www.nullsoft.com/free/nsis/makensis.htm) to get a better idea of all the NSIS commands.

To demonstrate NSIS capabilities in an example we can all relate to, we'll create an installation script for the PFC Examples application that comes with PowerBuilder 8. As most of us have it installed on our PCs, we should be able to test the script against it.

Built-in Variables
NSIS comes with a whole set of variables that enables you to access the location of many crucial system directories on the user's PC, such as the "Program Files" directory and the Windows and Windows System directory.

The complete list is available in the NSIS documentation but the most important ones are:

• $INSTDIR: The main installation directory, that is, the location where the user wants to install your application, e.g., "C:\Program Files\PowerBuilder\PFC Examples"
• $PROGRAMFILES: The program files directory, usually "C:\Program Files" on most PCs
• $DESKTOP: The desktop directory, usually "C:\windows\desktop"
• $WINDIR: The Windows directory, usually "C:\windows"
• $SYSDIR: The Windows system directory, usually "C:\windows\system"
• $STARTMENU: The start menu folder required for adding shortcuts
• $SMPROGRAMS: The start menu programs folder required for adding shortcuts
• $SMSTARTUP: The start menu programs/startup folder
• $QUICKLAUNCH: The quick launch folder

First Things First
Let's start off the script by defining the basic aspects of the installation - the name of the application and the installation file, the default program files directory, as well as the default folder for shortcuts (see Figure 2).

Name "PFC Examples for PowerBuilder 8.01"
OutFile "setup_pfc_examples_pb801.exe"
InstallDir "$PROGRAMFILES\PowerBuilder\PFC Examples"
DirText "Select the directory to install PowerBuilder PFC Examples in:"

Defining Which Files Get Included As Part of the Installation
Next, define a "section" that in NSIS is a way to logically group a set of related file operations together (as well as potentially control which set of files gets installed depending on different installation types, e.g., Full, Custom, Minimal, etc.). One of the biggest advantages of the NSIS "File" command (that defines which files are included in the setup) is that it allows wild cards, which is perfect for PowerBuilder applications that consist mostly of one EXE and a large number of PBDs (no need to define each PBD by hand). Also, please note that comments in NSIS start off with ";" versus the PB "//".

File "C:\Program Files\Sybase\PowerBuilder 8.0\PFC\demoapp\peat.exe"
File "C:\Program Files\Sybase\PowerBuilder 8.0\PFC\demoapp\peat.pbd"
File "C:\Program Files\Sybase\PowerBuilder 8.0\PFC\*.pbd"

Creating Shortcuts
The first step in creating a shortcut is making the folder where it will be located. Without that, creating the shortcut will fail (unless the folder existed before). This is nearly identical to the way InstallShield works as well.

CreateDirectory "$SMPROGRAMS\PowerBuilder"
CreateShortCut "$SMPROGRAMS\PowerBuilder\PFC Examples.lnk" "$INSTDIR\peat.exe"

This code creates a folder called "PowerBuilder" in the Start -> Programs menu and then creates a link called "PFC Examples" that points to the application's main executable. Listing 1 provides a basic no-frills installation script that prompts the user for the installation directory, copies all the files, and creates the Start Menu -> Programs shortcut.

Uninstallation Support
The way uninstall works in NSIS is somewhat different compared to a program like InstallShield, where each of the included files has a property attached to it that controls whether it's supposed to be uninstalled or not and the uninstallation logic is then automatically generated for you. The benefit of NSIS is its flexibility and small overhead, but the drawback is that there's nothing automatic about it and you have to write all your uninstallation logic manually. However, it's not as hard as it looks.

First, we need to "register" the application in the registry so it shows in the "Add/Remove Programs" window of the Control Panel. The registry entry should point to the uninstallation EXE (usually "uninst.exe" situated in the same directory where you installed your application, as shown in Figure 3).

WriteRegStr HKEY_LOCAL_MACHINE "Software\Microsoft\Windows\CurrentVersion\
Uninstall\PowerBuilder" "DisplayName" "PowerBuilder PFC Examples (remove only)" WriteRegStr HKEY_LOCAL_MACHINE "Software\Microsoft\Windows\CurrentVersion\ Uninstall\PowerBuilder"
"UninstallString" '"$INSTDIR\uninst.exe"'
WriteUninstaller "$INSTDIR\uninst.exe"

Next, we need to create a special section defined as "Uninstall" (usually at the end of the program) that contains the uninstallation logic. In it you would usually delete all the files, remove the directory, delete the shortcuts, and remove the registry entries previously created to "register" the application with Windows. The UninstallText command is required to define which message users will see when they decide to uninstall your application via Add/Remove Programs (see Figures 4 and 5).

; begin uninstall settings/section UninstallText "This will uninstall PowerBuilder PFC Examples from your system"
Section Uninstall
Delete "$INSTDIR\uninst.exe"
Delete "$INSTDIR\*.*"
DeleteRegKey HKEY_LOCAL_MACHINE "SOFTWARE\Microsoft\Windows\CurrentVersion\
Uninstall\PowerBuilder"
RMDir "$INSTDIR"
Delete "$SMPROGRAMS\PowerBuilder\PFC Examples.lnk"
RMDir "$SMPROGRAMS\PowerBuilder"
SectionEnd ; end of uninstall section

Alternate Compression Algorithms
The NSIS compiler comes in two flavors: makensis.exe, which uses regular ZIP compression (based on the ZLIB library), and makensis-bz2.exe, which uses the BZIP2 algorithm that in many cases can improve compression noticeably. In one test I did it reduced an installation program that was almost 16MB to less than 13MB. However, it did it at the expense of a slower compilation and extraction time, as well as requiring more memory at runtime. Test your installation script with both compilers and choose which one suits you better. If your application is deployed on a CD, the regular compile is preferred. However, if you're distributing your application via the Internet and are concerned with minimizing download time, maybe using BZIP2 compression is a better option. To compile with BZIP2 compression you need to simply compile your script using a command like this:

makensis-bz2.exe myscript.nsi

Securing Your Installation Against Corruption and Viruses
If you're planning to distribute your application via the Internet, add optional CRC-based self-verification to your installation program. All you need to do is add the following command to the top of your script:

CRCCheck on

This tells NSIS to perform a self-check every time a user starts the installation program to verify that it has not been modified since it was compiled, and also that it was fully downloaded.

Advanced NSIS
One thing I like about NSIS is that its philosophy is similar to PowerBuilder's: you need to know only a small subset of commands to get the basic job done. However, if you need something more complex, usually in NSIS (as in PowerBuilder) it turns out there are additional commands you can use if you require something more complicated. For example, if you need to create an installer with multiple setup types (e.g., "Full," "Minimal,""Custom"), look at the InstType and SectionIn commands that will allow you to easily accomplish such a task.

If you want to change the look-and-feel of the installer (icons, bitmaps, foreground and background colors, etc.), I recommend reading up on commands such as Icon, WindowIcon, BGGradient, EnabledBitmap, and DisabledBitmap. However, be warned that there's an alpha version of NSIS 2.0 available right now that changes many of these particular commands in order to allow more control over the way the installer looks, so you may need to modify your scripts once you move to NSIS 2.0.

In addition, there's a whole set of extensions for NSIS that you may include (if you wish). They're not part of the default NSIS compiler, since they would increase its overhead and NSIS's creators decided to make them external programs that are used only if actually needed. This keeps the design of NSIS small, extensible, modular, and suitable for distributing extremely small programs (like a WinAmp plugin) as well as complex enterprise applications (such as your typical PowerBuilder project).

For example, if you want to display a splash screen, then you should look at "splash.exe" (the documentation for it is in the "C:\Program Files\NSIS\Contrib\Splash" directory). If you want to create custom dialogs with labels, single line edits, radio buttons, check boxes, etc., to prompt the user for extra information, look at the "InstallOptions.dll" (the documentation for it is in "C:\Program Files\NSIS\Contrib\InstallOptions").

It's also worthwhile to look at the numerous example *.nsi scripts distributed with NSIS that show many of its different features (including the ability to automatically download a program via HTTP from a Web server).

Where to Meet NSIS Users and Programmers
The official Web forum for NSIS users is located at http://forums.winamp.com/. The "NSIS discussion" Web forum is located in the "Developer Center" of the WinAmp forums. There you might do defect reports, enhancement requests, or just ask for help from other NSIS users. You can also download any alpha or beta builds of NSIS from that area as well.

I hope your experience with NSIS will be pleasant and that its "small is beautiful" philosophy will make your PowerBuilder application installation efforts much smoother. It really can do almost everything a larger program like InstallShield can and, in most cases, do it faster, smaller, and not cost you a bundle. My congratulations to Nullsoft for creating such a small, yet flexible and useful utility and for making it freely available (together with source code) for everyone.

The complete source code for our example installation script ("pfc_examples.nsi") can be downloaded from www.sys-con.com/pbdj/sourcec.cfm.

• Figure 1
• Figure 2
• Figure 3
• Figure 4
• Figure 5
• Source Code