|
How To Create an Installer for your SatForms 6.x PocketPC Application
|   |
|
How To Create an Installer for your SatForms 6.x PocketPC Application
| |
Problem: How To Create an Installer for your SatForms 6.x PocketPC Application
Solution: There are several different approaches to creating an installer for your SatForms PocketPC application. This article presents an approach that generates a single exe file to install the Satellite Forms runtime engine and your compiled application to the PocketPC, providing a smooth user experience.
[NOTE: This article is applicable to Satellite Forms 6.x PocketPC applications, and to SatForms 7 applications that use the CDB database format. A new and improved installer creation method is described for Satellite Forms 7.x and 8.x PocketPC applications in the article How To Create an Installer for your SatForms 7 PocketPC Application]
This example describes all steps needed to create an installer for the PocketPC application "Work Order Sample.exe", based on the SF sample application "Work Order". Directories and program names can be modified to suit your own application by changing the references in the *.bat, *.inf, *.ini, and *.txt files described below. The process described herein will enable you to create a single-EXE installer file for your SatForms PocketPC application. NOTE: You will need to repeat this process with your PPC2002 and PPC2003 target builds, resulting in separate EXE installers for each. See the article How To use different platform targets for PocketPC applications for more information about PocketPC targets.
The overall approach is to create a PocketPC CAB file for your application, then combine the SatForms runtime engine CAB and your app CAB into a single EXE installer.
NOTE: Do not let the length of this article dissuade you from using this installer creation process. This article is quite long so as to ensure no steps are left out, but you will find it is a straightforward process to create you own app installers using this method, and the professional looking results are worth the investment of your time.
This installer creation method utilizes a free open source installer creation tool called Nullsoft Scriptable Install System (NSIS). NSIS is similar in function to other installer creation tools such as InstallShield, Wise Installer, and InnoSetup, but is completely free of charge for personal and commercial use.
Please download the WorkOrderInstallerSample.zip file here:
http://www.satelliteforms.net/support/WorkOrderInstallerSample.zip
A. What does the installer do?
It implements a complete install program for the your PocketPC application. The install program "WorkOrderInstall.exe" in this example does the following (note that the PPC must be connected to the desktop and ActiveSync must be running):
1. Displays a license agreement (EULA) which the user must accept to proceed (you supply the text).
2. Installs the Satellite Forms runtime engine.
3. Installs the application "Work Order Sample.exe" and all *.cdb files into the "\Program Files\Work Order" folder on the PPC.
4. Creates a shortcut for the program in "\Windows\Start Menu\Programs" on the PPC.
5. Registers the program and creates an "Unload" file on the PPC for future deletion of the application.
B. Files required to create the installer
1. Microsoft CABWiz files:
Cabwiz.exe, cabwiz.ddf, Makecab.exe
All of these files are available free of charge from Microsoft, in the Microsoft PocketPC 2002 SDK zip file. We have included them in the \Utils folder in the sample zip file.
2. Application files: Work Order Sample.exe (icon/executable for PPC), Work Order Sample.pda, all *.cdb files in the AppPkg folder (wrkLookup.cdb, wrkSites.cdb, wrkWorkItems.cdb). These are included in the sample zip file in the \WorkOrder folder, but you could also create them by compiling the PPC2003 target of the Work order sample project included with Satellite Forms.
3. Batch and configuration files for Cabwiz:
MakeCAB-WorkOrder.bat, WorkOrder.inf
4. Readme, EULA, installer icon files:
readme.txt, eula.txt, WorkOrderInstall.ico
Use these sample files as a template, and modify as needed for your application.
5. Satellite Forms Runtime Engine CAB file:
The Satellite Forms V6.1 RDK runtime engine installer CAB is provided in the \Satellite Forms 6.1\Redist\PocketPC\Runtime CABs\ folder:
SatFormsRuntimeRDK.Arm.CAB
6. Nullsoft Scriptable Install System:
Download the open source NSIS installer creation tool from http://nsis.sourceforge.net and install it to your development PC. Accept all of the default installation options.
C. Step By Step Process
C.1. Unzip the WorkOrderInstallerSample.zip to a folder on your desktop PC, for example C:\WorkOrderInstaller, (and make sure you allow the unzip process to create the subfolders within the archive).
C.2. Create the CAB files containing your app
Run the MakeCAB-WorkOrder.bat batch command. This will create a WorkOrderSample.Arm.cab file and other intermediate files in the C:\WorkOrderInstaller folder. [Note that this CAB file is also included in the sample zip file, so it will already exist in your folder.]
Note: you will likely get the error log file makecab.err created when you perform this step. It might look something like this:
Warning: Section [DefaultInstall] key "AddReg" - there are no section entries to process
Warning: Section [DestinationDirs] key "Shortcuts" is not using the string "%InstallDir%"
Warning: Section [DefaultInstall] key "AddReg" - there are no section entries to process
Those warnings are harmless. If you see other warning or error messages, then you will need to follow them up to resolve the problem.
C.3. Copy the SatForms RDK runtime engine CAB file from \Satellite Forms 6.1\Redist\PocketPC\Runtime CABs\ to the C:\WorkOrderInstaller folder.
C.4. Use NSIS to convert the CAB files to a single EXE installer
Right-click on the WorkOrderInstall.nsi file and select Compile NSIS Script. This will launch the graphical interface for NSIS and compile the CAB files into a single WorkOrderInstall.exe file. NSIS uses the configuration parameters in the WorkorderInstall.nsi file to define how it creates the installer.
That's it! The installer is created, and NSIS displays the creation details. You can test the newly created installer by clicking on the Test Installer button. [You need to have your PocketPC device connected to the PC at this point.] Follow the onscreen prompts on the PC and the handheld as needed.
That's it: the SatForms runtime engine and your application are installed!
To start the Work Order app on your PPC, tap on Start | Programs | Work Order
D. Modifying the sample to suit your application
In order to modify the sample installer files to suit your application, several files must be edited.
D.1. CAB creation INF file for your app
Make a copy of the WorkOrder.inf file and rename it to YourApp.inf. The name you choose for the INF file will determine the resulting CAB filename (eg. YourApp.Arm.CAB).
Edit the YourApp.inf file in a text editor to change references to Work Order and SampleCo to your app and company, and to change the files included in the application to your app files. The WorkOrder.inf file is marked up with the changes below. The sample entry is highlighted in grey, with the modified value highlighted in yellow. Notes are highlighted in blue:
--
[Version]
Signature="$Windows NT$"
CESignature="$Windows CE$"
Provider=%CompanyName%
[CEDevice]
BuildMax=0xE0000000
;this ensures that you do not get the "this app may not run on this version of windows Mobile" warning
[SourceDisksNames]
1=,"Application Files",, .\WorkOrder
1=,"Application Files",, .\YourApp
NOTE: This is the subfolder you must create. You need to copy your app EXE, PDA, and CDB files there from the AppPkg folder.
[DefaultInstall]
CopyFiles=Files.App
CEShortcuts=Shortcuts
[Shortcuts]
%AppName%,0,"Work Order Sample.exe"
%AppName%,0,"Your App.exe"
[CEStrings]
InstallDir=%CE1%\%AppName%
AppName="Work Order"
AppName="Your App"
[Strings]
CompanyName="SampleCo"
CompanyName="Your Company"
LinkFileName="Work Order"
LinkFileName="Your App"
[DestinationDirs]
Shortcuts =,%CE11% ; create shortcut in \Windows\Start Menu\Programs
Files.App = 0,%InstallDir% ; install app to %CE1%\%AppName% = \Program Files\Work Order
[SourceDisksFiles]
Work Order Sample.PDA = 1
Work Order Sample.exe = 1
wrkLookup.cdb = 1
wrkSites.cdb = 1
wrkWorkItems.cdb = 1
Your App.PDA = 1
Your App.exe = 1
YAtable1.cdb = 1
YAtable2.cdb = 1
YAtable3.cdb = 1
;note add your extension SFX files here too
[Files.App]
Work Order Sample.PDA
Work Order Sample.exe
wrkLookup.cdb
wrkSites.cdb
wrkWorkItems.cdb
Your App.PDA
Your App.exe
YAtable1.cdb
YAtable2.cdb
YAtable3.cdb
;note add your extension SFX files here too
--
D.2. MakeCAB batch command
Copy the MakeCAB-WorkOrder.bat file and rename it to MakeCAB-YourApp.bat. Edit the .bat file in a text editor and change the commandline from:
".\Utils\Cabwiz.exe" ".\WorkOrder.inf" /err makecab.err /cpu "Arm"
to
".\Utils\Cabwiz.exe" ".\YourApp.inf" /err makecab.err /cpu "Arm"
D.3. License and readme files
Edit the eula.txt and readme.txt files to your liking.
D.4. INI file
Copy the WorkOrder.ini file to YourApp.ini. Edit the YourApp.ini file in a text editor to change references to Work Order and SampleCo to your app and company. The WorkOrder.ini file is marked up with the changes below. The sample entry is highlighted in grey, with the modified value highlighted in yellow. Notes are highlighted in blue:
--
[CEAppManager]
Version = 1.0
Component = WorkOrder
Component = YourApp
[WorkOrder]
Description = Work Order application
Uninstall = WorkOrder
CabFiles = WorkOrder.ARM.cab
[YourApp]
Description = Your Application
Uninstall = YourApp
CabFiles = YourApp.ARM.cab
--
D.4. NSIS install script
Copy the WorkOrderInstall.nsi file and rename it to YourApp.nsi. Edit the YourApp.nsi file in a text editor to change references to Work Order and SampleCo to your app and company, and to change the files included in the application to your app files. The WorkOrder.inf file is marked up with the changes below. The sample entry is highlighted in grey, with the modified value highlighted in yellow. Notes are highlighted in blue:
; NOTE: this .NSI script is designed for NSIS v1.8+
;
; This is a setup script that installs both the SatForms runtime engine and the compiled application
; together as a single listed application using two CAB files (RDK runtime CAB plus your app CAB)
; Both the SatForms runtime and your app will be listed in the Remove Programs tool and both
; must be accepted during the install process
; Note that all files are also installed to the PC hard drive in the INSTDIR folder
Name "SampleCo Work Order"
Icon "WorkOrderInstall.ico" ;note this is not the same icon as the Work.ico used by SatForms
OutFile "WorkOrderInstall.exe"
Name "YourCompany Your App"
Icon "YourAppInstall.ico" ;note this is not the same icon as the YourApp.ico used by SatForms
OutFile "YourAppInstall.exe"
; Some default compiler settings (uncomment and change at will):
; SetCompress auto ; (can be off or force)
; SetDatablockOptimize on ; (can be off)
; CRCCheck on ; (can be off)
; AutoCloseWindow false ; (can be true for the window go away automatically at end)
; ShowInstDetails hide ; (can be show to have them shown, or nevershow to disable)
; SetDateSave off ; (can be on to have files restored to their orginal date)
; BrandingText " " ;hides the "NullSoft Install System" text if desired
LicenseText "You must agree to this license before installing."
LicenseData "eula.txt"
; Note: if you do not want to display a license dialog first just comment out the above two lines
; Note: this is the path on the PC (not the PDA) where the files will be installed
; The PDA install location is defined in the CAB file itself
InstallDir "$PROGRAMFILES\Work Order"
InstallDirRegKey HKEY_LOCAL_MACHINE "SOFTWARE\SampleCo\Work Order" ""
InstallDir "$PROGRAMFILES\Your App"
InstallDirRegKey HKEY_LOCAL_MACHINE "SOFTWARE\YourCompany\Your App" ""
ComponentText "NOTE: The first component installed is the Satellite Forms Runtime, and the second component is the Work Order application. You must install both components." "" "Application:"
ComponentText "NOTE: The first component installed is the Satellite Forms Runtime, and the second component is the YourApp application. You must install both components." "" "Application:"
Section "SampleCo Work Order" ; (default, required section)
Section "YourCompany Your App" ; (default, required section)
SetOutPath "$INSTDIR"
File eula.txt
File readme.txt
File WorkOrder.ini
File WorkOrder.Arm.CAB
File YourApp.ini
File YourApp.Arm.CAB
File SatFormsRuntimeRDK.ini
File SatFormsRuntimeRDK.Arm.CAB
; one-time initialization needed for InstallCAB subroutine
ReadRegStr $0 HKEY_LOCAL_MACHINE "software\Microsoft\Windows\CurrentVersion\App Paths\CEAppMgr.exe" ""
IfErrors Error
Goto End
Error:
MessageBox MB_OK|MB_ICONEXCLAMATION \
"Unable to find Application Manager for PocketPC applications. \
Please install ActiveSync and reinstall this application."
End:
StrCpy $1 "$INSTDIR\WorkOrder.ini"
StrCpy $1 "$INSTDIR\YourApp.ini"
StrCpy $2 "$INSTDIR\SatFormsRuntimeRDK.ini"
Call InstallCAB
SectionEnd ; end of default section
Section "-post" ; (post install section, happens last after any optional sections) ; add any commands that need to happen after any optional sections here
WriteRegStr HKEY_LOCAL_MACHINE "SOFTWARE\SampleCo\Work Order" "" "$INSTDIR"
WriteRegStr HKEY_LOCAL_MACHINE "Software\Microsoft\Windows\CurrentVersion\Uninstall\SampleCo Work Order" "DisplayName" "SampleCo Work Order (remove only)"
WriteRegStr HKEY_LOCAL_MACHINE "Software\Microsoft\Windows\CurrentVersion\Uninstall\SampleCo Work Order" "UninstallString"
WriteRegStr HKEY_LOCAL_MACHINE "SOFTWARE\YourCompany\Your App" "" "$INSTDIR"
WriteRegStr HKEY_LOCAL_MACHINE "Software\Microsoft\Windows\CurrentVersion\Uninstall\YourCompany Your App" "DisplayName" "YourCompany Your App (remove only)"
WriteRegStr HKEY_LOCAL_MACHINE "Software\Microsoft\Windows\CurrentVersion\Uninstall\YourCompany Your App" "UninstallString" '"$INSTDIR\uninst.exe"'
; write out uninstaller
WriteUninstaller "$INSTDIR\uninst.exe"
MessageBox MB_YESNO|MB_ICONQUESTION \
"Setup has completed. View readme file now?" \
IDNO NoReadme
ExecShell open '$INSTDIR\readme.txt'
NoReadme:
Quit
SectionEnd ; end of -post section
ShowInstDetails nevershow ;never show installation details
; begin uninstall settings/section
UninstallText "This will uninstall SampleCo Work Order from your system"
UninstallText "This will uninstall YourCompany Your App from your system"
Section Uninstall
; add delete commands to delete whatever files/registry keys/etc you installed here.
Delete "$INSTDIR\uninst.exe"
Delete "$INSTDIR\eula.txt"
Delete "$INSTDIR\readme.txt"
Delete "$INSTDIR\SatFormsRuntimeRDK.ini"
Delete "$INSTDIR\SatFormsRuntimeRDK.Arm.CAB"
Delete "$INSTDIR\WorkOrder.ini"
Delete "$INSTDIR\WorkOrder.Arm.CAB"
Delete "$INSTDIR\YourApp.ini"
Delete "$INSTDIR\YourApp.Arm.CAB"
DeleteRegKey HKEY_LOCAL_MACHINE "SOFTWARE\SampleCo\Work Order"
DeleteRegKey HKEY_LOCAL_MACHINE "SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\SampleCo Work Order"
DeleteRegKey HKEY_LOCAL_MACHINE "SOFTWARE\YourCompany\Your App"
DeleteRegKey HKEY_LOCAL_MACHINE "SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\YourCompany Your App"
RMDir "$INSTDIR"
SectionEnd ; end of uninstall section
; Installs a PocketPC cab-application
; The var $0 contains the path to the CeAppMgr tool
; It expects $1 and $2 to contain the absolute location of the ini files
; to be installed.
Function InstallCAB
ExecWait '"$0" "$1" "$2"'
FunctionEnd
; eof
--
Note that there are other options that can be adjusted in the NSIS script if desired -- see the NSIS documentation for details.
That is it, you do not need to modify any other files in order to customize the installer sample to suit your application. Once you have made the changes, repeat the step by step process (C.1. through C.4.) to create your own single-exe application installer.
Keywords: PocketPC, install, installer, NSIS, CAB, CABWiz, setup
KB ID: 10027
Updated: 2010-06-22
Satellite Forms KnowledgeBase Online