Tech Note 31: Creating An Installer With e-PocketSetup Express

April 19, 2008

Copyright 2008 NS BASIC Corporation

e-PocketSetup is probably the best tool to create installers for Windows CE currently available. It's powerful, it has unique features for NS Basic users and is continually improving. It also works well for desktop apps: the NS Basic/CE installer is built using it. e-PocketSetup is a commercial product.

ePocketSetup Express is sufficient for most NS Basic/CE applications. e-PocketSetup Express is an simple and quick tool to create, manage and deploy single-platform setup projects for Windows Mobile. Easy to use, it was designed for all developers that want to create modern and sophisticated setups without needing to distribute all-packages-in-one setup programs or customize the interface and setup actions.

For more information on e-PocketExpress, visit the e-PocketSetup website.

There is a special price of $29.95 USD for NS Basic/CE users. To get the discount, order "e-PocketSetup 4 Express (Single User)" from the online store and use coupon code EPS4NSBSPECIAL. A demo is also available. It is fully functional, but puts up a nag message when it is run.

In this Tech Note, we will give you the information you need to set up an installer for a typical NS Basic project. e-PocketSetup has many additional features: please consult the documentation of the product for more information.

To save space, we'll refer to e-PocketSetup Express as ePSX from now on.

1. Getting Started

Start by making a list of all the files you want to install. It will be easier if you put them into a single directory or directory structure. Make sure you include any dll or ocx controls you have added to your project. If you are distributing the control to other people, you should also have a text file with your licence agreement.

Start ePSX. You'll see this screen:

2. Project Settings

Choose Main Information, under Project Settings.

Software Name: give the name of your program.
Company Name: The name of your company. Keep this short: it needs to fit in the Remove Programs screen. For example, use "NSB" instead of "NS Basic Corporation". If the company name is too long, ActiveSync will actually have problems (the exact limit is unknown.)
Software Version: The version number of the current build. You'll have change this when you do a new version.
Description: A description. This is mostly for documentation purposes - it will not appear to the user except during installation.
Installation Directory: Usually the default is correct here.
Licence Agreement: The path to the text file with your License Agreement.

You can further customize your installer by going into Setup Messages, Setup Appearance and Setup Dialogs. For a simple installer, there is no need to do so.

3. NSBasic Settings

Next, choose "NSBasic Settings" under Setup. It will guide you through filling in the rest of the information needed to create your installer. After you are done, you can edit the selections you made by using the other options under Setup, such as "Windows Mobile Settings", or select "Next" in the toolbar at the top of the screen.

Compiled File: The name of your .nsb file. It will contain all the modules, so you don't need to add them to the project separately.
Custom Icon: Use this if you want to have a custom icon. It needs to be a .ico file. It needs to have a 16x16 and a 32x32 image. The images can be 16 bit or 32 bit: both images need to have the same bit depth.
NSBasic Version: What version of NS Basic/CE are you using? This is usually the latest version you have installed on your system. ePSX comes with several versions of the NS Basic runtime files. However, there could be a newer version. ePSX uses the standard NS Basic/CE Runtime CAB files, saved in the folder \program files\e-PocketSetup Express 4\Data\NSBasic\. If you want to use a newer runtime, copy its cab file to this folder.
NSBasic Platform: What devices are you targetting? The most common settings is "Pocket PC 2003 (or later)", which will work on all Pocket PC 2003 and Windows Mobile 5 Pocket PC devices. If you want to create a single installer that will work on multiple platforms, or need to support a device type not listed here, you will need to use the full version of e-PocketSetup.
Use the Custom Icon with NSBasic compiled file: Check this if you want e-PocketSetup to use your custom icon for your app. This feature is different than using NS Basic/CE's EXE file feature, which lets you create an exe file with an icon.
Install NSBasic Runtimes: This will normally be checked. If it is, ePSX will include the NS Basic runtime files into the installer. Otherwise, the appropriate runtime will have to installed to the device as well.
e-PocketSetup Express comes with a copy of the NS Basic runtime installer which is put into \Program Files\e-PocketSetup Express\Data\NSBasic\(rev)\(filename).Cab. If you are using the current version of NS Basic/CE, it is likely that a newer version of the runtimes exist. You need to copy these into this folder.
To get the CAB files out of the latest version of Runtime.ppc.exe (or other installer), run it. This will unpack the CAB files and put them into \Program Files\Microsoft ActiveSync\Runtime (or the name of other installer). Copy these files over the ones in e-PocketSetup.
The runtime that is installed the same as Runtime.ppc.exe: it does not install any additional controls your program may use. You can add these in Step 5.

4. Windows Mobile Settings

In this screen, we tell ePSX which CPU types we will be targetting. You only need to set up information for the Platform you specified in NSBasic Settings. If your Platform is "Pocket PC 2003 (or later)", you do not need to do anything in this panel: the default is to create the installer for ARM processors. Do not check off X86 (Emulator). It is not used by NS Basic/CE.

5. Additional Files

Use this panel to tell eEPX about other files you need to install. It automatically adds your application to the Installation Directory you specified. If you are not installing any other files, you can click on Next to go to the next step.

If your app has additional files, such a group of images, you can right click on %InstallDir% and add a subfolder. Add your files to this subfolder.

If you have controls (.dll or .ocx) files you need to install, put them in \Windows. After you have added them, right click on the filename and select File Properties. You'll see this window:

Source File: The pathname to the control.
File Name: The name of the file on the device. This will default to the filename,
Copy Type: "Copy Newer" will copy the control to the device if it does not exist already, or if it is newer than what is currently installed.
Shared File: Normally checked for controls. Other apps may be using the same control.
ActiveX File: Normally checked for controls. This will automatically register the control so it can be used by NS Basic/CE programs.

6. Additional Packages

Use this panel to add additional CAB files. This won't be necessary for most projects.

7. Runtimes

Skip this window - nothing needs to be entered here.

8. Shortcuts

Your application will be installed to the directory \Program Files\%InstallationDirectory%\appname on your device. To make it easy to access from the Start menu, we need to put a shortcut to it. ePSX sets up this shortcut automatically.

9. Registry Entries

This window lets you set up registry entries for your application. Once again, most NS Basic/CE apps will not need to do anything here.

10. Build Information

We're almost done. Just a bit more information to enter about how the installer will be built.

Output Directory: What directory should the installer that gets created be placed in?
Build Mode: The default, "(generates the CAB files and the setup program)" is the normal choice here: it will create an exe program that does the installation.
Delete files after calling ActiveSync: When the setup runs, it unpacks the CAB files and puts them in a folder in \Program Files\ActiveSync. If you would like the files deleted after the installation, check this.
Include Uninstaller: This is a good idea - it makes sure the installer also installs an uninstaller.

11. Generate Setup

We're done! Click on Generate Setup and the setup file is created. The file EPS Demo.exe is our installer. It has also created EPS Demo_WM5_StrongArm.cab, which is only needed for installing without ActiveSync (for example, from a card).

12. Test the Setup

To run the installer you have just created, click on the .exe file that was created and follow the instructions on the screen. You can now go back and tweak any of the settings and recreate the installer until it is just right.

Additional Notes

From Mike Trainor: "The wizard only allows for one shortcut, but if another is needed, simply create the shortcut on your Pocket PC. Copy the file from \windows\start menu folder to your desktop. Then add it to the list of files to be installed by epocketsetup with the destintation being \windows\start menu."