Palm OSŪ Developer Suite

IMPORTANT: Read Before Using the Accompanying Software

IMPORTANT: Read Below Carefully if:

Table of Contents

Enhancements and Fixes -- What's New

Welcome to the 1.2.0 release of Palm OS Developer Suite. Palm OS Developer Suite is based on Eclipse, a widely-accepted open-source IDE. The 1.2.0 release includes the following:

Environment:

Development Support:

Changes from Palm OS Developer Suite 1.1.0

This release of Palm OS Developer Suite includes the following new features:

About Palm OS Developer Suite

Palm OS Developer Suite uses Eclipse as its base IDE. Eclipse version 3.0.1 and the C Development Toolkit feature (CDT) version 2.0.2 are the required minimum Eclipse base. JRE 1.4 or later is required but is already included with this product so an additional download of it is not needed. Additionally, Palm OS Developer Suite uses Cygwin as its C compilation environment.

Installation Instructions

To perform a complete installation of Palm OS Developer Suite, which includes all necessary components (such as Eclipse, Cygwin, prc-tools, and Palm OS SDKs and tools), run the Palm OS Developer Suite Installer.

The complete installation assumes that you do not have Cygwin installed. The complete installation installs an Eclipse instance complete with Palm OS Developer Suite specific plugins, a subset of Cygwin, prc-tools, Palm OS 5 SDK, and Palm OS Cobalt SDK, and tools modified for use with prc-tools and Eclipse, in a subfolder of your root drive:

  <root drive>:\Program Files\PalmSource\Palm OS Developer Suite

Warning - Cygwin Installations

The default installation installs a Palm OS Developer Suite provided version of Cygwin. The custom installation allows you to select which features are installed and the locations of installed features. Most users without Cygwin previously installed should use the default installation method. Use the custom installation method if you already have Cygwin and prc-tools installed on your target machine. It is highly recommended to take the defaults in all other cases in the custom installation method for packages to install and paths for installation.

NOTE: If you choose to install the Palm OS Developer Suite provided Cygwin, you should remove all previous Cygwin installations since Cygwin does not support multiple installations of that product to coexist on one machine. Palm OS Developer Suite installer modifies the Cygwin registry settings as part of the installation process and therefore may negatively affect any previous installations.

System Requirements

Palm OS Developer Suite requires the following:

Palm OS Developer Suite also uses Cygwin and prc-tools as one of its underlying tool chains. A complete installation of Palm OS Developer Suite includes a Cygwin package with the following list of packages and versions:

Additionally, the Palm OS Developer Suite provided Cygwin installation includes the prc-tools 2.3 patch for multi-section debugging of 68K applications. This patch was created by Ton van Overbeek, a contributor to the prc-tools chain at SourceForge.net. The patch can be retrieved from http://www.v-overbeek.nl/msectgdb/ if you install your own Cygwin and prc-tools and need to patch your installation. Thanks to Ton for his work in getting this patch done.

If you have already installed Cygwin and want to keep using that, update your packages to include all of the above packages of at least the versions numbers indicated. For instructions on how to update Cygwin, go to http://www.cygwin.com. For instructions on how to update prc-tools go to http://prc-tools.sourceforge.net. After updating the Cygwin and prc-tools packages, choose the custom installation path in the Palm OS Developer Suite full installer and uncheck Cygwin in order to use your own Cygwin and not use the one provided by PalmSource.

Web Updates through Eclipse Update Manager

This release supports the Eclipse Update Manager for automatically updating your Palm OS Developer Suite or Eclipse Platform using Palm OS Developer Suite updates. There is no additional configuration required in your Palm OS Developer Suite installation in order to find available updates from PalmSource. To look for updates, select from the menu Help > Software Updates > Find and Install... and follow the wizard.

NOTE: DO NOT apply any CDT updates provided by eclipse.org to your Palm OS Developer Suite instance through the Update Manager. The CDT requires patches from PalmSource in order to work within the Palm OS Developer Suite and updating the CDT features and plugins from eclipse.org will overwrite those required changes, thereby breaking your Palm OS Developer Suite instance.

NOTE: Once an update of Palm OS Developer Suite has been started, DO NOT cancel the operation; let it complete in its entirety. There is known bugs in the Eclipse 3.0.1 Update Manager feature that prevents a successful cancel of a partially completed update manager installation operation. This will be fixed in a future release when Palm OS Developer Suite includes Eclipse 3.1.

Upgrading Instructions

Palm OS Developer Suite 1.2.0 does not support upgrading an existing earlier Palm OS Developer Suite version at this time. Rather, if you've already installed Palm OS Developer Suite 1.1.x or earlier you must first uninstall your previous installation. Your project data will be remain untouched on your system during the uninstall. You then can install Palm OS Developer Suite 1.2.0 in the same locations as you had previously chosen for the previous version. Your project data will remain in your workspace even though individual memorized workspace settings (such as global preferences and perspective modifications) may be modified or lost during the reinstallation process.

If you forget to uninstall an earlier installed version of Palm OS Developer Suite prior to running the Palm OS Developer Suite 1.2.0 installer, the installer will initiate an uninstall of the previous product version before installing the current version.

NOTE: If you did uninstall a previous version of Palm OS Developer Suite and then installed version 1.2.0 in the same directory as the previous installation or are using a PODS 1.0.0 workspace for the first time in version 1.2.0, you may receive an error dialog after restarting the IDE for the first time that states something similar to the following:

Unable to restore perspective: Workspace - Palm OS C/C++ Development Perspective
  Unable to create editor: Welcome.
  Could not create view: org.eclipse.cdt.ui.BuildConsoleView
  Could not find view: org.eclipse.cdt.ui.BuildConsoleView

This is due to settings in your workspace that reference IDE components that have been updated and/or replaced in version 1.2.0 (or more precisely in CDT 2.0 that is included by Palm OS Developer Suite 1.2.0). To correct the error, select Window > Reset Perspective while in the perspective that the error references.

Importing and Upgrading Projects

Importing non-Palm OS Developer Suite Projects

This release of Palm OS Developer Suite does not have any import wizards that automatically create new Palm OS Developer Suite projects from those existing Palm OS projects from other third party vendors. Included in this section is the recommended methods for importing the contents of your existing projects into Palm OS Developer Suite project.

prc-tools Make Projects

68K application projects using prc-tools 2.3 should be able to be imported into a 68K standard make project and compile without change. This is assuming that the prc-tools projects contains a makefile in its root directory and the tools invoked are in the PATH environment variable. Some modifications may be required to update the tools paths in the makefile or the make targets. To import a prc-tools 68K make project, do the following:

  1. Create a new Palm OS Development Standard Make 68K C/C++ project of output type Application and using the "Makefile Import Project" code template.
  2. Select File > Import... > File System and select the complete contents of your existing prc-tools make project. This will copy those contents into the Palm OS Developer Suite standard make project directory in your workspace.

Invoking build on the project will then build the "all" target in your makefile. For 68K shared libraries or static libraries, perform similar actions as above, except create a new Palm OS Development Standard Make 68K C/C++ project with the output type of Shared Library or Static Library as appropriate.

If you are building PNO applications with prc-tools, note that the default tool chain that Palm OS Developer Suite provides for compiling PNO segments is different from that of prc-tools. Palm OS Developer Suite by default uses the PalmSource C/C++ compiler to compile PNO segments for a device target while prc-tools 2.3 utilizes arm-palmos-gcc. Depending on your preferences you should either a) add the arm-palmos-gcc toolset to your Cygwin deployment to keep your makefiles the same, or b) modify your makefiles to utilizes the PalmSource C/C++ compiler. To utilize the PalmSource C/C++ compiler, create a sample project using a wizard provided code template and use those makefiles as an example for modification of your makefiles.

Other Third Party IDE Projects

For projects from other IDEs, the steps to take are:

  1. Create an appropriate Palm OS Developer Suite project for your target application (e.g. 68K or PNO project). Create the project using the "Source File Import Project" code template. You may create either a standard make project or a managed make project, depending on whether you want to manually maintain a makefile or manage your project through a project properties interface.
  2. Next you must import all source files, header files, resource files into the newly created Palm OS Developer Suite project. Import the files using File > Import... > File System. Importing the files will copy them into the Palm OS Developer Suite project.
  3. If you have a standard make project, you then must add the source and resource files into the makefile definition in order for the makefile to use those sources in a build. Managed make projects automatically compile all sources and resources in any subdirectory of a managed make project so there's no need to explicitly tell the project about the files.
  4. Finally you must manually apply any compiler/linker/build tools options from the existing project into the appropriate places in the Palm OS Developer Suite project. For standard make projects, this means update the makefile and possibly the makefile-engine.mk. For managed make projects, this means accessing the project's properties by selecting "C/C++ Build" and modifying the tools options there.

Upgrading 1.0.0 Palm OS Developer Suite Projects

Projects created in Palm OS Developer Suite 1.0.0 need to be upgraded in 1.2.0 in order for their properties to be accessed properly. To do so, first import the projects into Palm OS Developer Suite 1.2.0 if they are not already in your workspace. you will then be prompted that a restart of the IDE is required if the projects are not version 1.2.0 projects. Then you must RESTART Palm OS Developer Suite 1.2.0. When restarted, the IDE will detect that there are projects that have not been upgraded to 1.2.0 and show a dialog asking if the projects should be upgraded. Please allow it to do the upgrade so you can access your managed make projects properties properly. Note that there may be a slight delay of a few seconds before the IDE detects the projects to upgrade; be patient, it'll find them.

If you are upgrading standard make projects from 1.0.0, please note the following changes made in PODS 1.2.0 that are not automatically applied to your makefiles during the upgrade. The upgrade process does not modify your standard make makefiles, so you'd have to make any of these changes manually if you need them:

NOTE: If you've changed the installation locations of any component of Palm OS Developer Suite (such as the SDKs or Cygwin) in installing the latest version when compared to the previous Palm OS Developer Suite, you may have compilation errors due to changed dependency locations. This is a known issue in CDT. To rectify this, you can do either of the following:

Upgrading 1.1.x Palm OS Developer Suite Projects

Currently, there are no explicit steps required in order to upgrade Palm OS Developer Suite 1.1.x projects for 1.2.0. These projects will work unchanged in this release.

Unsupported Palm OS Developer Suite Project Versions

The following Palm OS Developers Suite project versions are not supported "as-is" in the current release of Palm OS Developer Suite:

The only supported method for updating the Palm OS Developer Suite projects listed above is to manually create new projects and incorporate the sources from the unsupported projects into the new projects. To do so, do the following:

  1. Create a new project in the current release of Palm OS Developer Suite corresponding to the target API and project type (e.g. 68K, PNO, or Protein and application, shared library, static library, or database). Choose the code generation template of "Source File Import Project" to get all project specific files except for the actual source files.
  2. Select the project and then select from the menu File > Import > File System . That will bring you to a dialog that allows you to select all of the source to copy into your project's workspace.
  3. After including all of your source, if you've created a standard make project you have to modify the makefile so that the SOURCES, RESOURCES, and PNO information matches the sources you are including.

Incorporating User Defined Makefiles

Standard make projects in Palm OS Developer Suite uses user-controlled makefiles for its builds. Palm OS Developer Suite essentially just invokes 'make' from a command line to build the standard make projects. In the standard make project wizards, Palm OS Developer Suite provides a generic set of makefiles that the user can modify and tailor for their specific application build.

The user also has the option of not using the Palm OS Developer Suite supplied makefiles and providing their own. This can be done, but the user must modify their makefiles to meet certain requirements that Palm OS Developer Suite defines for makefiles. Palm OS Developer Suite requires some variables to be defined in the file 'makefile' so that Palm OS Developer Suite can accurately derive information about the build for debugging and running the result. A complete list of the variables required can be found in the Introduction to Palm OS Developer Suite book in the HTML help contents within Palm OS Developer Suite.

Uninstalling Palm OS Developer Suite

To uninstall Palm OS Developer Suite, follow the steps below:

  1. Go to Windows Start Menu > Settings > Control Panel > Add/Remove Programs
  2. Select the following from the list "Currently Installed Programs" and click on Change/Remove button for each to uninstall each component:
    • Palm OS Developer Suite
  3. Other components such as any updated plugins and features can be deleted manually.

NOTE: If you chose to install the included Palm OS version of Cygwin as part of the Palm OS Developer Suite, the uninstall feature may leave the Cygwin directory behind after uninstallation due to the creation of files during the use of Cygwin. You can safely remove this directory after uninstallation.

Restrictions

This section details the restrictions or limitations you should be aware of when using Palm OS Developer Suite.

Install/Uninstall/Update

Project Management

68K Development

PNO Development

Protein Development

PalmSource Installer Package Export Wizard

Language Support

Samples

Debugging

General

Known Issues

This sections lists significant issues, defects, and bugs in Palm OS Developer Suite known at the time of the release of this version of the product.

Install/Uninstall/Update

Cygwin and prc-tools

Global Preferences

68K Development

PNO Development

Protein Development

Samples

Compiling

This product contains a pre-release version of the PalmSource Palm OS Protein C/C++ Compiler. Significant known issues in this compiler include:

We would appreciate reports of any bugs or abnormal behavior that developers encounter.

Debugging - 68K

Debugging - PNO

Debugging - Protein

Debugging - General

General

Other Information

Undocumented Features

The Palm OS Protein C/C++ Compiler has a --preinclude switch that acts like the prefix file feature in the CodeWarrior compilers. The text of the file specified by this switch is included before each source file, as if it were #included immediately before the source text begins. The usage is --preinclude=filename.h.

Licensing


PalmSource, Inc.
1188 East Arques Avenue
Sunnyvale, California 94085
(408) 400-3000