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

2    Eclipse Workbench Integration

Introduction to Palm OS® Developer Suite

Palm OS® Developer Suite

This chapter describes how to use the Palm OS tools in the Eclipse Workbench integrated development environment.

Using the Eclipse Workbench, you create a new project using a wizard, edit source files using the code and text editors, and build applications from the standard development environment menu. You can even launch Palm OS Resource Editor and the Palm OS Simulators from the development environment.

Using the Palm OS C/C++ Development Perspective ^TOP^

Developer Suite uses the Eclipse Workbench as its integration platform. The Eclipse Workbench uses perspectives to define many of the attributes and functions available in the Workbench window. For example, perspectives determine the initial layout of windows, what functions appear in certain menus and toolbars, and what editors and tools are integrated.

The functions provided by Developer Suite are provided by the Palm OS C/C++ Development perspective. The Palm OS C/C++ Development perspective gives you access to all of the components described in Chapter 1, "Palm OS Developer Suite Overview."

Setting the Workbench Perspective ^TOP^

When you first install Developer Suite, the perspective is set to Palm OS C/C++ Development perspective for you. To ensure that this perspective is the selected perspective, select Window > Open Perspective > Palm OS C/C++ Development as shown in Figure 2.1.

Figure 2.1  Palm OS C/C++ Development perspective

Setting Workbench Preferences ^TOP^

Before starting your development work, you may want to start by reviewing the default Workbench preferences. Select Window > Preferences and click Workbench to view the Workbench preferences, as shown in Figure 2.2.

Figure 2.2  Workbench Preferences

Build automatically
By default, the option Build automatically is selected, which means that every time you save a source file or a resource file, the build system is automatically invoked to build the project. If you like to save your files frequently and do not want the build system invoked every time you save, you may prefer to turn this setting off.
Save automatically before build

In most cases, you want to turn this setting on. The build system builds the most recently saved versions of the source. If you have this setting turned off and invoke the build system without saving your source files, then the build system does not include the changes you have made since the last save.

Using Projects to Manage Application Development ^TOP^

Developer Suite uses projects to manage most aspects of application development, including source file creation and application building, running, and debugging.

Using Workspaces ^TOP^

By default, the Eclipse Workbench stores project files (projects, folders, and files) in a subdirectory of the location of where you installed the Workbench. This sub-directory is called the "workspace" subdirectory.

When you create a project, you can select a different directory. However, the Eclipse Workbench assumes that the directory you specify is an Eclipse-generated directory. It is recommended that you use the default location as your workspace. Specifically, it is recommended that you do not create projects on the desktop.

Rather than changing the project's workspace directory, you should accept the default location and import your files into the project, which moves them to the workspace location.

Using Makefiles ^TOP^

Developer Suite projects rely on make files. Either use Managed Make, which generates makefiles, or use Standard Make, which requires you to write makefiles yourself or to modify the makefiles generated when a Palm OS Standard Make project is created. For more information about makefiles, see "Select Standard Make or Managed Make."

Creating a New Project ^TOP^

To create a new project, follow these steps:

Select an Application Type ^TOP^

Before you create a project, you first consider which type of application you want to create.

Palm OS 68K Application

If your goal is to create applications that run on all Palm OS devices and on all supported Palm OS versions, then you want to create Palm OS 68K applications.

The 68K API is the set of functions that spans all Palm OS releases. The 68K functions allow application code compiled for Dragonball processors to access the capabilities of Palm OS. The 68K API is the native API for Palm OS 4 and earlier Palm OS versions. The 68K API operates in PACE (the Palm OS Application Compatibility Environment) on Palm OS Garnet and Palm OS Cobalt.

Palm OS 68K Application with PACE Native Objects

If you are an experienced developer accustomed to working with the 68K API but you want to take advantage of the ARM CPUs that power Palm OS Garnet and Palm OS Cobalt handhelds, then you can create PACE native objects.

A PACE native object (PNO) is an ARM-native subroutine that your 68K application calls using the PceNativeCall() function.

Palm OS Protein Application

If you want to take advantage of the Palm OS Protein API functions and the features emerging on new Palm OS Cobalt handhelds, you want to create Palm OS Protein applications.

Palm OS Protein applications can be multithreaded, can access schema and extended databases, and can employ Palm OS Cobalt's multimedia framework. However, Palm OS Protein applications only run on Palm OS Cobalt and later.

Select Standard Make or Managed Make ^TOP^

Next, decide whether you want to use standard make or managed make to build your application.

Standard Make

In the standard make project wizards, Developer Suite provides a generic set of makefiles that you can modify and tailor for your specific application build. The standard make makefiles are user-defined and user-controlled. You have to manually update when you make changes to your project (adding files, removing files, changing the output, etc.). Developer Suite essentially invokes make to build the standard make projects.

You also have the option of not using the Developer Suite supplied makefiles, but the you must modify your makefiles to meet certain Developer Suite requirements. Developer Suite requires that the following variables be defined in the makefile:

ARTIFACT_NAME
Represents the root name of the target of the build, without any extensions. For example, if you are building the application sample.prc, then ARTIFACT_NAME must have a value sample.
DEBUG_OR_RELEASE
The valid values for this variable are Debug or Release.
This variable indicates whether the current build is a debug build or a release build.
TARGET_PLATFORM
The valid values for this variable are Device or Simulator.
Standard make projects build applications, shared libraries, and static libraries for two targets: device and simulator. To select the target for your project build, edit the make file provided with the project and change the TARGET_PLATFORM variable to either Device (actual hardware device or emulator), or Simulator (Palm OS Garnet or Cobalt Simulator).
Device builds and Simulator builds produce output in different files and in different formats; Developer Suite must be able to differentiate the two.
DEBUG_DEVICE_OUTPUT_DIR
Indicates the directory relative to the project's directory that contains the final output for a debug build targeting a device platform.
RELEASE_DEVICE_OUTPUT_DIR
Indicates the directory relative to the project's directory that contains the final output for a release build targeting a device platform.
DEBUG_SIMULATOR_OUTPUT_DIR
Indicates the directory relative to the project's directory that contains the final output for a debug build targeting a simulator platform.
RELEASE_SIMULATOR_OUTPUT_DIR
Indicates the directory relative to the project's directory that contains the final output for a release build targeting a simulator platform.
SDK_LOCATION
Specifies the location of the Palm OS SDK used for this project.
TOOLS_DIR
Specifies the location of the Palm OS tools used for this project.
Whenever you build a project, the Palm OS C/C++ Development perspective dynamically determines the location of the Palm OS SDKs and tools used for the project build. These locations are included in the generated file called auto-generated.mk, which is placed in the project's root directory. This auto-generated.mk file is used by the default makefiles generated with Palm OS projects. You may include this file in your own make files if you want to determine the values of SDK_LOCATION and TOOLS_DIR at compile time.

The variables in makefiles must be direct assignments of values with no variable substitution. For example,

ARTIFACT_NAME = a
ARTIFACT_NAME := b

are valid in a Developer Suite makefile, but

ARTIFACT_NAME = $(SOME_OTHER_VARIABLE)

is not valid.

You can review the sample code produced by Developer Suite's wizards for more examples of these variables in makefiles.

Managed Make

Managed Make dynamically generates your makefile based on the contents of your project folders. Managed make "watches" your project and automatically updates the makefile when you add files or remove files in your project. To make additional project updates, you use the provided preference panels.

To select build targets (Device or Simulator targets) for managed make projects, select a project and select Project > Properties. In the Properties dialog box, select the C/C++ Build settings group, and change the Active configuration setting appropriately.

Use the New Project Wizard to Create a Project ^TOP^

To create a new Palm OS project in the Workbench, select File > New and the application type you want to create, as shown in Figure 2.3.

Figure 2.3  Creating a new project

  • Standard Make 68K C/C++ Project

    This is a project for a Palm OS 68K application, written in
    C/C++, that use a Standard Make makefile.

  • Managed Make 68K C/C++ Project

    This is a project for a Palm OS 68K application, written in
    C/C++, that uses a Managed Make makefile.

  • Standard Make 68K PNO C/C++ Project

    This is a project for a Palm OS 68K application with an ARM-based PNO, written in C/C++, that uses a Standard Make makefile.

  • Managed Make 68K PNO C/C++ Project

    This is a project for a Palm OS 68K application with an ARM-based PNO, written in C/C++, that uses a Managed Make makefile.

  • Standard Make Protein C/C++ Project

    This is a project for a Palm OS Protein application, written in C/C++, that uses a Standard Make makefile.

  • Managed Make Protein C/C++ Project

    This is a project for a Palm OS Protein application, written in C/C++, that uses a Managed Make makefile.

Enter Project Name and Location

When you select your application type, the New Project wizard opens, as shown in Figure 2.4.

Enter a project name and select the location for your project files. (As described in "Using Workspaces," it is recommended that you accept the default location.)

For each page of the wizard, click Next to move to the next page.

Figure 2.4  New Project wizard project name and location

Enter Palm OS Settings

Enter Palm OS settings, as shown in Figure 2.5.

Figure 2.5  New Project wizard Palm OS settings

Project Output Type
Select the output type for the project.
Application - A Palm OS application. For information, see Exploring Palm OS: Programming Basics.
Shared Library - An executable module that is compiled and linked separately. For more information, see Exploring Palm OS: System Management, Chapter 6 "Shared Libraries."
Static Library - A collection of object files that you can link into another Palm OS application.
Database (pdb) - A PDB is a record database generally used to store data for an application. For information, see Exploring Palm OS: Palm OS File Formats.
According to the normal Eclipse build paradigm, a project produces only one output file. Creating Database projects gives you a way to add PDB files to an application's debug session by using the Files to install field in the Debug dialog box for the Palm OS Application configuration.
Note that the Database (pdb) selection is supported for standard make projects only.
Output Name without extension
The name for your project and related output files. This field is set to the project name entered in the Name field shown in Figure 2.4.
Database Type
For Palm OS applications (PRC databases), this field has the value appl.
For Palm OS shared libraries, this field has the value libr.
Database Version
The application-specific version of the database layout.
Database Name
The database name stored in the PRC database header. This is normally the name of the application.
Creator ID
Each Palm OS application is uniquely identified by a combination of its name and a four-byte creator ID. Enter the creator ID that you have registered with PalmSource. For information on creator IDs, see Exploring Palm OS: Programming Basics.
Database Settings
Select how you want the database attribute constants set for your database. See Palm OS Programmer's API Reference for more information on the database attribute constants described.
Allow Backup on Sync - Select to set the dmHdrAttrBackup constant.
Hidden - Select to set the dmHdrAttrHidden constant.
Bundle its Databases - Select to set the dmHdrAttrBundle constant.
Prevent Copy - Select to set the dmHdrAttrCopyPrevention constant.
Reset on Install - Select to set the dmHdrAttrResetAfterInstall constant.

Project Code Generation

Select what code you want generated for your project, as shown in Figure 2.6.

Figure 2.6  New Project wizard code generation


NOTE: The code generation template items listed are dependent on the type of project you are creating.
Source File Import Project
Provides meta-data files, such as a makefile and make-engine.mk file, that you can use as a base for your project. This template is useful for importing existing source files.
Make File Import Project
Creates an empty project without the meta-data files. This selection is useful for importing and modifying existing Palm OS makefile based projects such as PRC-tools projects, when you don't want a new makefile created.
PilotMain Starter
Provides a single source file with the required PilotMain() function.
Simple
Provides a simple Hello World application with PilotMain(), a frame, and event loop handling.
Sample
Provides a fully functioning sample application, a Puzzle game.

Additional Project Settings

For managed make, you can choose to reference an existing project, as shown in Figure 2.7. These are inherited from the CDT component, though they have additional values from the Palm OS C/C++ Perspective. For information on the CDT settings, see the C/C++ Development Toolkit (CDT) documentation.

If you don't want to change the build settings, you can click Finish to take the default build settings.

Figure 2.7  New Project wizard build settings

PACE Native Object Projects ^TOP^

In this version of Developer Suite, the PNO projects require a very specific directory structure, as created by the PNO project wizards. You should not alter the directory structure that the New Project wizard creates.

In addition, Developer Suite does not support PACE Native Objects with global data. If you attempt to use global data in a PNO, you receive a warning message from the Palm OS post linker, and the execution of the PNO can have unpredictable results.

Changing Project Settings for PNO Resources ^TOP^

By default, a resource type of ARMC is used for PNO resources. The default IDs of PNO resources start at hex value 1000. These values are the normal convention for PNOs and are used as the defaults for project creation.

For device target builds, you can change the PNO resource type and IDs. (For simulator target builds, the PNO code is compiled into a DLL, so this change is not pertinent to simulator target builds.)

Standard Make

For PNO standard make projects and makefiles provided by Palm OS Developer Suite, you change the resource type and ID specified in the makefile. See the makefile for instructions on how to specify the PNO resource values in the appropriate sections.

Managed Make

For PNO managed make projects, change the resource type and ID through project properties.

Changing the resource type

To change the resource type, make two modifications:

  1. Rename the directory name containing the PNO resource code to the new resource type. By default, the directory is named NativeCode/ARMC1000.

    For example, to change to a resource type of WXYZ, rename the directory to NativeCode/WXYZ1000.

  2. Change the project properties for the Palm OS Elf Post Linker by doing the following:
    • Open the Properties dialog box by selecting the project and then selecting Project > Properties. The Properties dialog box opens, as shown in Figure 2.8.

Figure 2.8  Managed make PNO Properties dialog box

    • Select C/C++ Build.
    • For Platform, select Palm OS 68K PNO Application (Device target).
    • In the Configuration Settings, expand Palm OS ELF Post Linker and select Miscellaneous.
    • Change the setting for -code to match the new resource type. By default, this setting is this:
   -code ARMC

For example, to change the resource type to WXYZ, change the setting to this:

   -code WXYZ
  • Change the setting for -data to match the new resource type. By default, this setting is this:
   -data ARMD

For example, to change the resource type to WXYD, change this setting to this:

   -data WXYD
  • Change the -rsrc option to match the new resource type. By default, this setting is
   -rsrc 0x$(subst ARMC,,$*)
  • For example, to change the resource type to WXYZ, change this setting to this:
   -rsrc 0x$(subst WXYZ,,$*) 
Changing the resource ID

To change the resource ID, simply rename the directory name containing the PNO resource code to the new resource ID. For example, to change to a resource ID of hex 2000, rename the directory to NativeCode/ARMC2000.

Shared Library Projects ^TOP^

Creating a shared library project is similar to creating an application project. However, in the New Project wizard:

  • In the second page of the wizard, select Shared Library for the Project output setting.
  • In the third page of the wizard, select Shared Library Starter. For 68K shared libraries, this ensures that the DEF file gets created; for Palm OS Protein shared libraries, this ensures that the SLD file gets created.

When you create a project that uses a shared library, you define your shared library's project as a Project Reference for your application.

Importing Files into a Project ^TOP^

If you have existing C/C++ application code, you can create a new project and import your code into the project. Developer Suite uses the Workbench's import support to allow you to add files to a project. This means that you can add files to a project by:

  • dragging and dropping from the file system into the Navigator view, or
  • copying and pasting from the file system into the Navigator view, or
  • using the Import wizard.

The Palm OS C/C++ Development perspective inherits the Workbench-implemented support for importing existing projects, files from the file system, team project sets, and zip files. The Palm OS C/C++ Development perspective adds a wizard for importing Palm OS resource files.

Importing 68K Source Files ^TOP^

Importing source code from either CodeWarrior projects or from PRC-Tools is relatively straightforward.

Figure 2.9  Import Wizard

  • Select File System and then click Next to open the File system Import dialog box, shown in Figure 2.10.

Figure 2.10  File system Import

  • Click Browse to select the folder where the existing application source files are located. Click the check boxes to select which files you want to import.
  • Review the Import Options. For most projects, the default option Create selected folders only shown be correct.

Do not import any resource files or resource definition files; follow the instructions in section "Importing Palm OS Resource Files" for these types of files.

Fixing Line Delimiters ^TOP^

Text files come with three varieties of end-of-line character sequences: Windows, Mac OS X/UNIX/Linux, and Classic Mac OS). You may not be aware of which line delimiters your source files have, because most development environments automatically handle (and preserve) these values. However, the gcc tool chain on Windows requires that all source files end with Windows line delimiters (CRLF), and as a result can generate errors when compiling otherwise valid code.

Many sample code projects, CodeWarrior stationery projects, and book samples were created on Macintosh systems. As a result, some of the files in your old projects might have non-Windows line delimiters.

To convert sources to Windows line delimiters:
  • Double-click the source file's icon in the C/C++ Projects view to open it in the editor view.
  • Make sure the file's editor view is selected and choose Convert Line Delimiters To -> (CRLF) Windows. If you see that the file has been changed (there will be an asterisk next to the file's name in its editor tab), the Workbench has changed the delimiters to the proper value.
  • Save the file.
  • Repeat for each file in your project.

Importing Palm OS Resource Files ^TOP^

To import a Palm OS resource file, select File > Import to open the Import wizard, as shown in Figure 2.9.

Select Palm OS Resource File and then click Next. The Import Palm OS Resource File wizard, shown in Figure 2.11, opens.

Figure 2.11  Import Palm OS Resource File wizard

  • Select the PRC, RSRC, or XRD file that you want to import.
  • Enter a name for the XRD file that you want added to your project. (If your input file is a PRC or a RSRC file, this file is the XRD file that will be generated from your input file.)
  • Select the project folder into which you want this XRD file to be imported.
  • Set additional options for the GenerateXRD tool, if you are importing from a PRC or RSRC file.

    GenerateXRD options:

    • Target

      Specifies the text encoding of the input resources.

    • Locale

      Specifies the locale used to tag output resources with a LOCALE attribute.

    • Convert unknown resource

      Specifies that resource types that are not recognized are included in the output XRD file.

    • Generate resources as raw data

      Specifies that all resources that are output to the XRD are output as RAW_RESOURCE elements that preserve the binary input data exactly.

    • Generate database header

      This option is for importing PRC files. It specifies that the attributes of the input PRC database header will be stored as a DATABASE_HEADER element in the output XRD file.

    • Generate code resources

      This option is for testing and debugging. It specifies that executable code resources or support resources are output to the XRD file, usually as RAW_RESOURCE elements.

    • Save resource data as external files

      This option determines whether binary data should be included as inline binary data or as an external file reference.

Click Finish to import the resource file. Developer Suite calls the GenerateXRD tool to convert your PRC or RSRC file, if necessary, and updates your make file if you are using a managed make file.

For more information about GenerateXRD, see Palm OS Resource Tools Guide.

Importing Palm OS Sample Applications ^TOP^

Each SDK sample already includes a Developer Suite project. To build the samples from the SDK, first import the project into your workspace. Select File > Import > Existing Project into Workspace, and select the folder for the sample application. Then build the project within Eclipse.


NOTE: You can also use the command line to build the sample applications. In order to build the applications, invoke the make utility with the "-f" parameter by passing the name of the makefile. The makefile builds not only the target application but also all the dependent libraries. For example, to build the Address Book sample application, use the command make -f makeaddr at the command prompt.

When you import a project using Import > Existing Project into Workspace, Eclipse does not move your files but rather references the files in their existing location. If you want to retain an unchanged version of an existing project, you should make a copy of the project before importing it.

Editing Project Source Files ^TOP^

Developer Suite uses the Workbench's support of unique editors associated with different types of files.

  • You edit C/C++ source files, header files, and shared library definition (SLD) files with the text editor. Simply double-click on a filename in the Navigator view, and the text editor opens the file in the editor view.
  • You edit XML resource definition (XRD) files with Palm OS Resource Editor. Double-click on an XRD filename to open Palm OS Resource Editor.

Building a Project ^TOP^

The process for building a project is dependent on the type of project. See the appropriate section for your project:

Building a Standard Make Project ^TOP^

A standard make project uses the generated makefile to build the project. To change the settings for your standard make project, you edit this generated makefile.

For example, to specify whether you want a Debug build or a Release build of a standard make project, you edit this line in the makefile:

DEBUG_OR_RELEASE=Debug

To specify your run target for a standard make project, you edit this line in the makefile:

TARGET_PLATFORM=Device

After making any necessary changes to the project's makefile, you can build the standard make project by selecting Project > Rebuild All.

Building a Managed Make Project ^TOP^

Before you build your project, check the project's properties by selecting Project > Properties, which opens the Properties dialog box, as shown in Figure 2.12.

Figure 2.12  Properties dialog box for managed make projects

From the Properties dialog box, you can view the current project properties, and change specific settings before building the project.

Active Configuration Settings

The Active Configuration setting is a combination of the Platform setting and the Configuration setting. Developer Suite supports the following active configuration settings.

  • Palm OS 68K Application with Debug configuration

    Builds the 68K application for execution on Palm OS Emulator, Palm OS Simulator, or a device, with the compiler's debug level set to the default debug level, -g.

    This build uses the Cygwin compiler for 68K-based Palm OS devices (m68K-palmos-gcc) to build the application.

  • Palm OS 68K Application with Release configuration

    Builds the 68K application for execution on Palm OS Emulator, Palm OS Simulator, or a device, with the compiler's debug level set to None.

    This build uses the Cygwin compiler for 68K-based Palm OS devices (m68K-palmos-gcc) to build the application.

  • Palm OS 68K PNO Application (Device target) with DebugDevice configuration

    Builds the 68K application with a PNO for execution on a Palm Powered device with additional debugging settings specified.

    This build uses the Cygwin compiler for 68K-based Palm OS devices (m68K-palmos-gcc) to build the 68K application, and uses Palm OS Protein C/C++ Compiler to build the PNO component.

  • Palm OS 68K PNO Application (Device target) with ReleaseDevice configuration

    Builds the 68K application with a PNO for execution on a Palm Powered device.

    This build uses the Cygwin compiler for 68K-based Palm OS devices (m68K-palmos-gcc) to build the 68K application, and uses Palm OS Protein C/C++ Compiler to build the PNO component.

  • Palm OS 68K PNO Application (Simulator target) with DebugSim configuration

    Builds the 68K application with a PNO for execution on Palm OS Simulator with additional debugging settings specified.

    This build uses the Cygwin compiler for 68K-based Palm OS devices (m68K-palmos-gcc) to build the 68K application, and uses the Cygwin C/C++ compiler for Windows (i686-pc-cygwin-gcc-3.3.1) to build the PNO component.

  • Palm OS 68K PNO Application (Simulator target) with ReleaseSim configuration

    Builds the 68K application with a PNO for execution on Palm OS Simulator.

    This build uses the Cygwin compiler for 68K-based Palm OS devices (m68K-palmos-gcc) to build the 68K application, and uses the Cygwin C/C++ compiler for Windows (i686-pc-cygwin-gcc-3.3.1) to build the PNO component.

  • Palm OS Protein Application (Device target) with DebugDevice configuration

    Builds the Palm OS Protein application for execution on a Palm Powered device with additional debugging settings specified.

    This build uses Palm OS Protein C/C++ Compiler to build the application to run on an ARM-based device.

  • Palm OS Protein Application (Device target) with ReleaseDevice configuration

    Builds the Palm OS Protein application for execution on a Palm Powered device.

    This build uses Palm OS Protein C/C++ Compiler to build the application to run on an ARM-based device.

  • Palm OS Protein Application (Simulator target) with DebugSim configuration

    Builds the Palm OS Protein application for execution on Palm OS Simulator with additional debugging settings specified.

    This build uses the Cygwin C/C++ compiler for Windows (i686-pc-cygwin-gcc-3.3.1) to build the application.

  • Palm OS Protein Application (Simulator target) with ReleaseSim configuration

    Builds the Palm OS Protein application for execution on Palm OS Simulator.

    This build uses the Cygwin C/C++ compiler for Windows (i686-pc-cygwin-gcc-3.3.1) to build the application.

Once you have set the build configuration settings, to build a project, select the project in the C/C++ Projects pane. Then select Project > Build Project.

Modifying Tool Properties ^TOP^

To modify the properties for the compilers, resource tools, and target environment settings, you use the Palm OS Development Preferences dialog box, shown in Figure 2.13.

Figure 2.13  Preferences dialog box

To open the Preferences dialog box, select Window > Preferences. Then select Palm OS Development.

GNU Compiler Preferences ^TOP^

Use this pane to set preferences for the GNU compilers.

  • Select the 68K tab to change preferences for the Cygwin compiler for 68K-based Palm OS devices (m68K-palmos-gcc). This is the compiler used to build 68K applications.
  • Select the x86 tab to change the preferences for the Cygwin C/C++ compiler for Windows (i686-pc-cygwin-gcc-3.3.1). This is the compiler used to build applications targeted for Palm OS Simulator.

For information about GNU compiler options, see the documentation at the PRC-Tools web site (http://prc-tools.sourceforge.net/doc/).

Palm OS Protein Compiler Preference ^TOP^

Use this pane to set preferences for the Palm OS Protein C/C++ Compiler's associated compiler tools: pacc, palink, and palib.

  • Select the Palm OS C/C++ Compiler tab to set options for pacc.
  • Select the Palm OS Linker tab to set options for palink.
  • Select the Palm OS Librarian tab to set options for palib.

For more information about the compiler tools, see the book Palm OS Protein C/C++ Compiler Tools Guide.

Palm OS Resources Preferences ^TOP^

Use this pane to set preferences for the Palm OS resource tools.

  • Select the Resource Compiler tab to set options for PalmRC.
  • Select the PRCMerge tab to set options for PRCMerge.

For more information about the resource tools, see the book Palm OS Resource Tools Guide.

Target Environment Settings Preferences ^TOP^

Use this pane to set preference for the execution targets used for running and debugging applications.

  • Select Device to set preferences for using Palm Powered devices as run targets.
  • Select Emulator to set preferences for using Palm OS Emulator as a run target. Palm OS Developer Suite comes with one Emulator target pre-defined. You can change this target's settings, or create additional Emulator targets.
    • Use the Browse button to select a different Emulator executable.
    • Use the Options entry field to specify command line arguments for Emulator.
    • To add a new Emulator target, use the New button.

      For more information about Palm OS Emulator settings, see the book Using Palm OS Emulator.

  • Select Simulator to set preferences for using Palm OS Garnet Simulator and Palm OS Cobalt Simulator as run targets. Palm OS Developer Suite comes with one Palm OS Garnet Simulator target pre-defined, and with one Palm OS Cobalt Simulator target pre-defined. You can change these targets' settings, or create additional Simulator targets.
    • Use the Browse button to select a different Simulator executable.
    • Use the Options entry field to specify command line arguments for Simulator.

      For example, Palm OS Cobalt Simulator skips the Language Picker application at startup if you specify the -preferredLocale setting as a command line argument.

    • To add a new Simulator target, use the New button.

      For information about Palm OS Garnet Simulator, see the book Testing with Palm OS Garnet Simulator. For information about Palm OS Cobalt Simulator, see the book Palm OS Cobalt Simulator Guide.

Launching Other Palm OS Tools ^TOP^

You can launch the following standalone tools from Developer Suite:

Palm OS Garnet Simulator ^TOP^

In general, you launch Palm OS Garnet Simulator as a run target, using the Run menu. For information on using Palm OS Garnet Simulator as a run target, see "Using Palm OS Simulator."

In addition, you can launch Palm OS Garnet Simulator directly by selecting Start > Programs > PalmSource > Palm OS Garnet SDK Tools > Palm OS Garnet Simulator.

For more information about Palm OS Garnet Simulator, see Testing with Palm OS Garnet Simulator.

Palm OS Cobalt Simulator ^TOP^

In general, you launch Palm OS Cobalt Simulator as a run target, using the Run menu. For information on using Palm OS Cobalt Simulator as a run target, see "Using Palm OS Simulator."

In addition, you can launch Palm OS Cobalt Simulator editor directly by selecting Start > Programs > PalmSource > Palm OS Cobalt SDK Tools > Palm OS Cobalt Simulator.

For more information about Palm OS Cobalt Simulator, see Palm OS Cobalt Simulator Guide.

Palm OS Virtual Phone ^TOP^

There are two versions of Virtual Phone included in the Developer Suite package: one included from the Palm OS Garnet SDK and one include from the Palm OS Cobalt SDK. You can launch Palm OS Virtual Phone directly by selecting either:

  • Start > Programs > PalmSource > Palm OS Cobalt SDK Tools > Palm OS Virtual Phone
  • Start > Programs > PalmSource > Palm OS Garnet SDK Tools > Palm OS Virtual Phone

For additional information on Virtual Phone, see Palm OS Virtual Phone Guide.

Palm OS Debugger ^TOP^

Palm OS Debugger is integrated into the Palm OS C/C++ Development perspective. To launch Palm OS Debugger from Developer Suite, select Run > Palm OS Debugger.

In addition, you can launch Palm OS Debugger directly by selecting Start > Programs > PalmSource > Tools > Palm OS Debugger.

For additional information on Palm OS Debugger, see Palm OS Debugger Guide.

Palm OS Emulator ^TOP^

In general, you launch Palm OS Emulator as a run target, using the Run menu. For information on using Palm OS Emulator as a run target, see "Using Palm OS Emulator."

In addition, you can launch Palm OS Emulator directly by selecting Start > Programs > PalmSource > Tools > Palm OS Emulator.

For additional information about Palm OS Emulator, see Using Palm OS Emulator.

Palm OS Reporter ^TOP^

To autostart Reporter with Palm OS Simulator, edit the PalmSim.ini file and set the value of the AutoStartReporter option:

AutoStartReporter=1 

In addition, you can launch Palm OS Reporter directly by selecting Start > Programs > PalmSource > Tools > Palm OS Reporter.

Palm OS Resource Editor ^TOP^

To launch Palm OS Resource Editor from Developer Suite, double-clicking an XRD source file in your project. Palm OS Resource Editor starts and loads the selected XRD file.

In addition, you can launch Palm OS Resource editor directly by selecting Start > Programs > PalmSource > Tools > Palm OS Resource Editor.

Updating Palm OS Developer Suite ^TOP^

The Eclipse Workbench offers a simple mechanism for discovering, downloading, and installing upgrades to Palm OS Developer Suite. You can obtain new components and install them without exiting your development environment.

The Update Manager provides this functionality by means of a wizard that connects to update sites, displays a list of available updates, and then automatically downloads and installs the ones you select.

Features ^TOP^

Eclipse-based products such as Palm OS Developer Suite have a modular architecture, made up of many functional components called plug-ins. Related plug-ins are organized into features. A feature is the smallest package of code that can be downloaded and installed as a unit. Using features, you can upgrade Palm OS Developer Suite without the cost in time and bandwidth of downloading an entirely new version.

Palm OS Developer Suite consists of the following features:

  • Palm OS Developer Suite
  • Cygwin/PRC-Tools for Palm OS Developer Suite
  • Palm OS Developer Suite—Japanese Simulator ROMs
  • Palm OS Developer Suite—Chinese Simulator ROMs.

Some of these features contain sub-features. For instance, Palm OS Developer Suite has sub-features as indicated below:

  • Palm OS Developer Suite
    • Cygwin/PRC-Tools Modified Components
    • Eclipse C/C++ Development Tools (patched)

The entire feature, however, must be downloaded, installed, uninstalled, or reverted as a unit.

New and Updated Features

The Update Manager wizard lists only features that are new or have later version numbers than those already installed on your computer. Plug-ins with version numbers that have not changed do not appear on the list. If you accidentally damage some components of Palm OS Developer Suite, you should download a fresh distribution of the version of Palm OS Developer Suite you are using and re-install it.

Prerequisites ^TOP^

Make sure you have Palm OS Developer Suite 1.2 installed before trying to use the Update Manager. Currently, the updating functionality does not work with earlier versions of Palm OS Developer Suite or with a generic version of Eclipse.

Verifying Features ^TOP^

You can check what features you have installed and identifying information about them at any time. Select Help > About Palm OS Developer Suite, and then click the Feature Details button. A table is displayed, each row listing installed features and their subfeatures: columns display the name of the feature, the organization providing it, the feature's current version number, and the feature ID.

Obtaining New Features ^TOP^

To obtain a new feature, select Help > Software Updates > Find and Install. The Find and Install wizard opens.

  • In the Feature Updates panel, select Search for new features to install.
  • In the Update sites to visit panel of the wizard, select Palm OS Developer Suite Update Site by clicking on the white box next to the name.
    • If you click on the plus-sign, you will see a list of categories of content available on the update site. On a larger site, you can select individual categories of content. This choice determines which feature names appear on the next panel.
  • In the Password Required dialog, enter the user name and password you registered at the Palm OS Developer Pavilion. If you don't have an account, go to the following web site and create one:

    https://www.developerpavilion.com

  • In the Search Results panel, select the features you wish to download by clicking on the white box next to each one. Then click Finish.

Obtaining Updates to Existing Features ^TOP^

You can obtain updates to features that are already installed on your computer. Select Help > Software Updates > Find and Install. The Find and Install wizard opens. Then proceed as described in "Obtaining New Features."

  • In the Feature Updates panel, select Search for updates of the currently installed features.
  • In the Update sites to visit panel of the wizard, select Palm OS Developer Suite Update Site by clicking on the white box next to the name.
    • If you click on the plus-sign, you will see a list of categories of content available on the update site. On a larger site, you can select individual categories of content. This choice determines which feature names appear on the next panel.
  • In the Password Required dialog, enter the user name and password you registered at the Palm OS Developer Pavilion. If you don't have an account, go to the following web site and create one:

    https://www.developerpavilion.com

  • In the Search Results panel, select the Palm OS Developer Suite feature. Then click Finish.

Managing Features ^TOP^

You can use the Managing Configuration panel to manage your features—either individually or globally.

Managing Individual Features

You can disable individual features and then enable them again. You can revert to a previous version of the feature, or completely uninstall a feature. To do these tasks,

  1. Select Help > Software Updates > Manage Configuration,
  2. Open the tree to the appropriate level, and click on the feature.
  3. In the right-hand panel, click one of the following:

    Replace with Another Version: The Replace with Another Version dialog box appears. Select the version you desire to make active.

    Enable or disable, depending on the current state of this version of the feature: This link toggles between the two states of the version.

    Uninstall: Removes this version of the feature from you computer.

    Show Properties: Displays properties of this version of the feature.

Managing Features as a Configuration

You can also operate globally, returning all installed features to their state at a particular moment in the past. To do so, you choose from a list of past configurations. A configuration is the state of all features at the moment when a particular activity was completed. Activities can include downloading/installing updates or managing installed features by disabling, re-enabling, or reverting them. A configuration is identified by the date and time of the last activity or group of activities before that configuration was created.

To revert to a configuration:
  1. Select Help > Software Updates > Manage Configuration.
  2. In the Product Configuration dialog box, click on the root of the tree—Palm OS Developer Suite.
  3. In the right-hand panel, click on Revert to previous.
  4. In the Revert to a previous configuration dialog box, click on a date-time in the Past Configurations list.
  5. Examine the table titled Activities that caused the creation of this configuration.

    This is the complete list of activities that resulted in the selected configuration. Note that one activity, such as disabling a particular version of a feature, may be negated by a succeeding activity, such as enabling that same version.

  6. Click the Finish button after you verify that this is the configuration to which you wish to revert.

Consequences of Reverting a Feature

Reverting from a version of a feature causes that version to be disabled; it is not uninstalled. You will not be able to access this version again through the update mechanism. The version will not show up in the Find and Install dialog box, since it is already installed on your computer.

To access a version that was disabled via reverting:
  1. Select Help > Software Updates > Manage Configuration.
  2. In the tree, select the feature in question.
  3. In the right-hand panel, click Revert to Another Version.
  4. In the Replace With Another Version dialog box, select the version you want to make active.
  5. Click the Finish button.

Getting More Information ^TOP^

The Workbench provides much integrated documentation in the Help system. To view all of the integrated documentation, select Help > Help Contents.

The Workbench component itself is described in detail in the Workbench User Guide.