Date:	04-02-2003
	Title:	EZSetup configuration &  EZSetup Problem resolution
	Author:	Gene Ostrowski

Summary

The creation of this document serves two purposes:

1) It explains how to install and configure EZSetup, a nice, free utility that helps you build automatic installation packages for your PocketPC applications. It's not entirely obvious how to get it up and running properly, so hopefully this will assist those who are struggling with it.

2) There are a few gotchas that I encountered during my configuration that I'm sure other users may have experienced. It took me quite some time to figure out what was going on and there was little information on the Web to assist me. This document will at least be a reference guide to anyone who has experienced the same  issues.  It wasn't easy to resolve these problems, so maybe I'll be helping someone out.

The two specific issues that this article addresses are:

A) An error message "Error copying XXXXXX.tmp to YYYYYYY.exe!" during install.
B) An error message "Application Manager cannot install this application on your mobile device due to an invalid setup file. Reinstall and try again."

Product Affected

EZSetup version 1.1, probably other versions as well.

Background

Creating an automatic installation program for your newly completed application can be a daunting task. There are several programs on the market, some free, some not, that assist in this process. Up until the release of EZSetup, most of them were either too expensive or too difficult to configure.

When all you need is a simple installation program, with a ReadMe file, an end-user license agreement (EULA) and a way to launch the Add/Remove Programs subsystem of Application Manager, EZSetup is your answer.

EZSetup is a simple but very useful tool created by Scott Ludwig. The latest version can presently (April 2003) be located at his website.  It's command-line driven, so don't try to just double-click the exe to launch it, expecting a GUI interface for it. (There is a Windows GUI front-end to EZSetup available from spb Software House, but I have not used it enough to report on it at this time).

After running EZSetup to build an installation program for your application, the end result is a single, self-extracting file that contains the complete installation executable for your application. With it, the end-user gets a step-by-step installation  walkthrough, complete with a dialog box showing the readme file, a confirmation of the EULA, and an automatic launch of the Application Manager.  Although it's not as fancy as an installation created by, say, InstallShield, it gets the job done.

Let's get started!

Requirements

Before using EZSetup, you need to have the following files completed:

• A CAB file containing your application - This would have been created by using cabwiz.exe and a .INF file for your program. The creation of the .CAB file using cabwiz is beyond the scope of this article. Information on creating this can be found in this technical article.  Come back after you've got the CAB file(s) created.

• A ReadMe file - Just an ordinary text file containing the usual readme stuff that you want to distribute to the end-user with your application.

• An End User License Agreement file - Gotta have one of these in today's world. It's also just an ordinary text file.

• A Setup.ini file - This is a configuration file that the installer program uses to automatically install the application. EZSetup uses this file to create its self-extracting file that launches (and sets the parameters for) the Application Manager.

If you don't have one of these yet, you can copy the text below into a new file (call it Setup.ini) and you are done. This setup.ini is from Jewels, one of my games, so I know it works (shameless plug alert). 

[CEAppManager]
Version = 1.0
Component = Jewels

[Jewels]
Description = Jewels for the PocketPC
Uninstall = Jewels
IconFile = Jewels.ico
IconIndex = 0
DeviceFile = JewelsCE.exe
CabFiles = JewelsArm1100.cab

Now that we have all the files together, it's time to build our installation program.

I like to create a new directory for each version of the application that I create install packages for, so I can always install ANY version of the program that I've released to the public. It's good practice to have all these older versions available, so you should get into the habit of doing so.

Here's an example of a directory structure that I create for the new installation:

Procedure

Using EZSetup is a breeze. Start a Command Prompt and change to the directory where all the files are located. 

Run the following command:

ezsetup -l english -i setup.ini -r readme.txt -e license.txt -o JewelsCE.exe

The options are very straightforward:

• -l english <-- This sets the language to english.

• -r readme.txt <-- The FULL name of the readme file, with extension

• -e license.txt <-- The FULL name of the license.txt file, with extension

• -o JewelsCE.exe <-- The self-extracting installation file you want to create (in my example, the name of the install program will be JewelsCE.exe)

Again, although it is not necessary, I prefer to create a Rebuild.BAT batch file and include the above command so that I don't have to type this long command every time I want to build and test the installation program. It's your choice.

After the program churns for awhile and crunches your data, you should see your newly created .exe file which can be distributed to your customers.

Issues

When everything goes well, things are wonderful. However, sometimes things go wrong during the execution of the EZSetup program and you need to fix it. Usually it's a syntax error in the setup.ini file. Unfortunately, EZSetup does not have very useful error reporting-- it basically works or it doesn't. When it does not work, it does not give you too much information about where to look, so you need to check your setup.ini file with a fine-tooth comb to ensure that everything is in the proper place.

There were two specific errors that I was receiving that had me pulling out my hair for a while before I figured them out.

"Error copying XXXXXX.tmp to YYYYYYY.exe!" at the end of the compression stage.

Everything seemed to go fine, but this error popped up and aborted the creation of the self-extracting file. There were also a few straggler .tmp files leftover in the directory.

Solution: I had to disable my eTrust EZArmor Real-Time Virus Scanner. I assume since it is compressing and manipulating an .EXE file in memory, the real-time scanner is assuming that it is a virus trying to attach to a valid .exe file. Temporarily disabling the real-time scanner solved this problem. I'm pretty sure other virus scanners with this ability will also be affected by this problem.

"Application Manager cannot install this application on your mobile device due to an invalid setup file. Reinstall and try again."

This issue surfaced after the self-extracting file was successfully created and I went to test the installation process using this new file. The error message came from Application Manager.

Solution: It appears to be a bug in either EZSetup or App Manager, I'm not sure which one just yet. The problem is that I was trying to use a version number such as 0.1 or 0.35 instead of 1.0 or 1.1 in the setup.ini!

It seems to have issues with version numbers that start with 0. It's odd, but changing the "Version=" line in the setup.ini to a value like 1.0 fixes the problem. It's not a permanent solution but it does provide a workaround.

Update: Richard Pialat emailed in (09/23/03) to inform me of another situation where this error message may appear.  According to Richard, the error message will also appear if you attempt to provide a path to the .cab file (i.e., it  is not in the same directory that ezsetup resides).  As I have always put a copy of ezsetup into each installation directory that I work with, I have not had an encounter with this one.  Thanks Richard for the update!

Conclusion

Hopefully this article helped explain how to get EZSetup installed and configured to ease the creation of your installation packages. Also, if you had received any of the odd error messages that I did, and couldn't find any information anywhere else, hopefully this technical article provided the solution.

If this article helped you at all, please drop me a note at gene@baysidestudios.com and let me know. It's nice to hear that I was able to help out.

Regards,

Gene Ostrowski