Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

2    Installing Palm OS Emulator

Using Palm OS® Emulator

Palm OS Developer Suite

This chapter describes what you need to do to get Palm OS® Emulator installed and ready to use on your desktop machine.

Prerequisites ^TOP^

This section describes the software you need to use Palm OS Emulator.

Palm OS Emulator Runtime Requirements ^TOP^

Palm OS Emulator requires one of the following runtime environments:

  • A 32-bit Windows platform: either Windows 95, Windows 98, Windows NT, Windows ME, Windows 2000, or Windows XP. Emulator is a multi-threaded 32-bit program. It does not run on Windows 3.1, even with Win32s installed.
  • MacOS 8.6 or later with Carbon 1.2.5 or later
  • Unix: some versions, including Linux

Using ROM Images ^TOP^

To run Palm OS Emulator, you need to transfer a ROM image to it. The ROM image contains all of the code used for a specific version of the Palm OS. You can obtain ROM images for different Palm OS versions from the Palm OS Resource Pavilion, or you can tell Palm OS Emulator to download the ROM from a handheld that has been placed in the handheld cradle and connected to the desktop computer. For more information about transferring a ROM image to Palm OS Emulator, see "Loading ROM Images."

When you download ROM images from the Palm OS Resource Pavilion, you can also obtain debug ROM images. Debug ROM images contain additional error checking and reporting functions that can help you debug Palm OS applications.

For more information about testing and debugging applications with Palm OS Emulator, see "Testing Applications Using Palm OS Emulator."

Downloading Palm OS Emulator ^TOP^

The most recent released version of Palm OS Emulator for Macintosh, Windows, and Unix is always posted on the Internet in the PalmSource developer zone:

http://www.palmos.com/dev

Follow the links from the developer zone main page to the Emulator page to retrieve the released version of Emulator. If you want to test-drive the version of Palm OS Emulator that is currently under development, follow links from the developer zone page to the Emulator seed page.

The Palm OS Emulator package that you download includes the files shown in Table 2.1.

Note: For the Unix version of Palm OS Emulator, the source code is provided rather than the executables listed in the table below.

Table 2.1 Files Included in the Palm OS Emulator Package 

File name

Description

  • Emulator.exe (Windows)
  • Palm OS Emulator (Macintosh)

Main Palm OS Emulator executable

  • Emulator_Profile.exe (Windows)
  • Palm OS Emulator - Profile (Macintosh)

Palm OS Emulator with added profiling facilities

Docs (directory)

Palm OS Emulator documents, including:

  • _ReadMe.txt, which describes the files in the Docs directory
  • _News.txt, which describes changes in the most recent version
  • _OldNews.txt, which describes previous version changes
  • _Building.txt, which describes how to build Emulator executables
  • ROM Transfer.prc (Windows, Macintosh)
  • ROM_Transfer.prc (Unix)

Palm OS application used to transfer the ROM image from your handheld to your desktop.

HostControl.h

C/C++ header file declaring functions that can be used to control Palm OS Emulator.

For more information about the Host Control API, see Chapter 8, "Host Control API Reference."

Versions of Palm OS Emulator ^TOP^

Each released version of Palm OS Emulator has a version number that uses the following scheme:

<majorVers>.<minorVers>

Each field has the following semantics:

majorVers The major version number.
minorVers The minor version number.

Profile Versions ^TOP^

Palm OS Emulator includes a profile version, which has the word profile appended to the program name. The profile version adds the ability to perform selective profiling of your program's execution, and to save the results to a file.

The code required to add profiling capability slows down your application, even when you are not using profiling. That means that you are better off using the non-profiling version of Palm OS Emulator if you don't expect to use the profiling capabilities.

For more information about profiling with Palm OS Emulator, see "Profiling Your Code".

Loading ROM Images ^TOP^

Because Palm OS Emulator emulates the Palm Powered hardware, all components of the hardware must be present. This includes a ROM image file, which is not shipped with the Emulator. There are two ways to obtain a ROM image:

  • download a ROM image from the Palm OS Resource Pavilion
  • transfer a ROM image from a handheld

Downloading a ROM Image Obtained from PalmSource ^TOP^

To download a debug ROM image from PalmSource, see:

http://www.palmos.com/dev

The ROM image files are found in the Resource Pavilion.

The Resource Pavilion is an area for developers who have registered as members of the Palm OS Developer Program. You can find instructions for joining the Palm OS Developer Program at the developer site.

Transferring a ROM Image from a Handheld ^TOP^

To transfer a ROM image from a handheld, follow these steps:

  1. Install the Palm OS application named ROM Transfer.prc on your handheld. You can use the Install program in the Palm Desktop organizer software and then synchronize with the handheld to install this program.
  2. Place the handheld in the HotSync® cradle that is connected to your desktop computer.
  3. Follow the steps in the appropriate section below.

Transferring a ROM File in Windows ^TOP^

This section describes how to transfer a ROM image from a handheld on a Windows-based desktop computer. Before proceeding, you must have the ROM Transfer.prc program installed on the handheld, as described in the previous section.

If you are running the program for the first time, Palm OS Emulator presents the Startup dialog box shown in Figure 2.1. Click Download to begin the transfer of a ROM image from a handheld.

Figure 2.1  Palm OS Emulator Startup Dialog Box

If you are not running Palm OS Emulator for the first time, it usually restarts the session that you most recently ran, as described in "Palm OS Emulator Start Up."

To transfer a new ROM image for Palm OS Emulator to use, you can right-click on the Palm OS Emulator display (the Palm Powered handheld image) and select Transfer ROM.

Palm OS Emulator opens a Transfer ROM dialog box that will guide you through the process.

Transferring a ROM File on a Macintosh ^TOP^

This section describes how to transfer a ROM image from a handheld on a Macintosh desktop computer. Before proceeding, you must have the ROM Transfer.prc program installed on the handheld, as described in the previous section.

If you are running the program for the first time, Palm OS Emulator presents the dialog box shown in Figure 2.2.

Figure 2.2  Running Palm OS Emulator for the First Time on a Macintosh System

You can dismiss this dialog box and choose Transfer ROM from the File menu.

If you are not running Palm OS Emulator for the first time, it usually restarts the session that you most recently ran. To transfer a new ROM image for Palm OS Emulator to use, select Transfer ROM from the File menu.

Palm OS Emulator opens a Transfer ROM dialog box that will guide you through the process.

Transferring a ROM File on a Unix System ^TOP^

This section describes how to transfer a ROM image from a handheld on a Unix-based desktop computer. Before proceeding, you must have the ROM Transfer.prc program installed on the handheld, as described in the previous section.

When running the program on a Unix system, Palm OS Emulator presents the dialog box shown in Figure 2.3.

Figure 2.3  Running Palm OS Emulator for the First Time on a Unix System

You can dismiss this dialog box and choose Transfer ROM from the File menu to begin the transfer of a ROM image from a handheld.

If you are not running Palm OS Emulator for the first time, it usually restarts the session that you most recently ran. To transfer a new ROM image for Palm OS Emulator to use, select Transfer ROM from the File menu.

Palm OS Emulator opens a Transfer ROM dialog box that will guide you through the process.

Transferring a ROM Image over a USB Connection ^TOP^

Palm OS Emulator supports transferring ROM images over a USB connection. To use a USB connection, Palm OS Emulator needs the USB driver support provided by the Palm Desktop software.

On Windows, you need to have Palm Desktop 4.0.1 or later installed to get the USB driver. You must make the library for the USB driver (the file USBPort.dll) available to Emulator. Either copy this file from the Palm Desktop software's directory to the Emulator directory, or move it into the Windows system directory.

On Macintosh, you need to have Palm Desktop 2.6.3 or later installed to get the USB driver.

Using a ROM Image in Palm OS Emulator ^TOP^

Once you have transferred a ROM image to disk, you need to create a new session that is based on the image. To initiate the new session, you select New from the popup menu. Table 2.2 shows the first step in creating a new session for each transfer method.

Table 2.2 Initiating a New Session after Transferring a ROM Image 

Method Used to Initiate ROM Transfer

New Session Method

Clicked Download initial dialog box in Windows

Click New in the dialog box.

Selected Transfer ROM in Windows

Select either New or Close from the File menu.

Selected Transfer ROM on a Macintosh

Select New from the File menu.

Selected Transfer ROM on Unix

Select New from the File menu.

After you initiate the session, Palm OS Emulator presents the new session dialog box, which is described in "Configuring a New Session". The Windows version of this dialog box is shown in Figure 2.4.

Figure 2.4  New Session Dialog Box

After you select your parameters and click OK, Palm OS Emulator begins an emulation session.

Dragging and Dropping a ROM Image ^TOP^

You can use drag and drop to start a new Emulator session in either of two ways:

  • Drag and drop a ROM image file onto the Emulator screen to start a new session.
  • Drag and drop a ROM image file onto the Emulator executable or shortcut (alias) to start the Palm OS Emulator program.

You can also drag and drop other file types, as described in "Dragging and Dropping Files".