prc-eclipse User Manual


Copyright © 2004, Daniel Thompson <prc-eclipse@redfelineninja.org.uk>

Table of Contents

Introduction

prc-eclipse is an Eclipse plugin that provides support for the GNU based Palm OS development tools, prc-tools. prc-eclipse is free software licenced under the Common Public Licence.

The plugin provides two useful features. The first is to allow the use of the Eclipse graphical debugger interface instead of the textual gdb interface. The second is (searchable) access to PalmSource's extensive on-line help through Eclipse's built in help system. These combine with the C/C++ Development Tools to make a powerful development environment.

Most of the credit for this work should go not to me but to the great team working on CDT. To my mind the trivial nature of this plugin demonstrates the quality of the framework that has already been laid down.

Getting started

This chapter will guide you through the process of debugging your first program with prc-eclipse.

Prerequisites

The following software is required in order to use prc-eclipse. Please see Test configurations below for detailed version information for the first three components.
  1. Eclipse
  2. C/C++ Development Tools (CDT)
  3. prc-eclipse
  4. prc-tools (version 2.3 or greater)
  5. POSE (Palm OS Emulator)

Installing prc-eclipse

After installing Eclipse and CDT as described on their web site the installation of prc-eclipse is a simple matter of unzipping prc-eclipse and copying the contents of eclipse/plugins into the plugins directory of the Eclipse installation.

Creating your project

Since this is a tutorial on prc-eclipse rather than PalmOS development we will be using a existing program, TZones, as the basis of the project. Before you start you should download the latest version of TZones from the project web site. In this tutorial we will be using TZones 2.1.

You need to create a project to contain your source code and related files. A project has an associated builder that can incrementally compile source files as they are changed.

To create your project:
  1. Click File > New > Project. The New Project Wizard opens.
  2. Select C.
  3. Click Standard Make C Project.
    Note: At present prc-eclipse does not support managed make projects so you will be required to provide a makefile in order to build the project.
  4. Click Next
  5. Provide a name for your project, type it into the Name box.
  6. Click Finish.
  7. If a message box prompts you to switch perspectives, click Yes.

Setting up the project to build TZones

Your new project is displayed in the C/C++ Projects view and in the Navigator view. Your project is empty because you have not yet created files for your project. You can now import the TZones sources directly from the zip file:
  1. Click File > Import. The Import Wizard opens.
  2. Select Zip file.
  3. Click Next.
  4. Click Browse and select the TZones zip file, tzones-2.1.zip for example.
  5. Ensure you new project is listed in the Into Folder box.
  6. Click Finish.
Although we have imported the sources it is not yet possible to build the project because the Makefile is held in a subdirectory called TZones. We could correct this by writing a wrapper Makefile to store in the top level directory but instead in this tutorial we will simply alter the project properties in order to change the build directory. This is achieved as follows:
  1. In the C/C++ Projects view, right click on your project folder, and select Properties.
  2. Click C/C++ Make Project, and select the Make Builder tab.
  3. Click the Browse button and select the TZones directory contained in your project.
  4. Click OK.
  5. Right click on your project folder, and select Build Project.

Starting the debugger

We are now ready to start debugging your project. In this tutorial we will be using POSE (PalmOS Emulator) as our target device.

Note: At the time of writing prc-eclipse only supports POSE based targets.

Start POSE and download the teezee.prc file you have just built onto the emulated device. This file will be in the TZones directory contained in your project.

Having started POSE we must now setup the debugger configuration in Eclipse:
  1. Click Run > Debug.
  2. Select C/C++ Local, and click New. The newly created debug configuration will inherit its name from your project because it is selected.
  3. Into the C/C++ Application box type 'TZones/teezee'.
    Note: prc-eclipse does not yet provide a binary parser for Palm's COFF format binary files so the Search and Browse buttons will not function correctly.
  4. Select the Debugger tag.
  5. Select PalmOS GDB Debugger from the Debugger drop down menu.
  6. Ensure the Stop at main() on startup box is not checked since most Palm OS programs do not have a main() function.
  7. Into the GDB debugger box type 'm68k-palmos-gdb', or use the Browse button to locate the debugger executable.
  8. Click Debug, then switch to POSE and start the TZones application.
    TZones will start running and eclipse will switch to the Debug view.
You are now running the Eclipse debugger on real Palm OS software. The following describes a very brief guided tour showing how to manipulate the control flow:
  1. Select Thread [0] from Eclipse's Debug frame, and click Run > Suspend. The TZones globe will stop spinning and a stack trace will appear. The stack trace usually, though not always, shows the target inside a function called SysDoze.
  2. Click Run > Resume. The globe will start spinning again the thread will be marked Running.
  3. In POSE, click on the Home or Applications icon.
  4. If a message box warns you about memory leaks, click Continue.
  5. Start the TZones application again. The debugger will stop just inside the PilotMain function.
  6. You can use Run > Step Into to step through the application initialization. Click this a few times to understand what it does and move onto the next step.
  7. Click Run > Resume. The globe will start spinning.
  8. In the Outline frame select DoPreferencesDialog. The editor will automatically select this function for you.
  9. Double click on the left margin immediately to the left of the function definition. This will set a breakpoint on this function.
  10. In POSE, click the Menu button and choose Preferences. The debugger will stop inside the DoPreferencesDialog function once again allowing you to step, resume or examine the state of the target.
Feel free to examine the debugger interface a bit more closely. When you have finished perform the following to close the debugger and return to the development perspective.
  1. Click Run > Terminate to finish this session, if the menu item is disabled the select Thread [0] and try again. When the session terminated POSE will reset and the debug session will terminate.
  2. Right click on the terminated session and click Terminate and Remove to tidy up the Debug frame.
  3. Click Window > Open Perspective > C/C++ Development.
This concludes the tutorial. There is still lots more to learn about the C/C++ Development tools but very little specific to prc-eclipse. See Further Reading for more information.

Tested configurations

This section describes known compatible version number of Eclipse, CDT and prc-eclipse. If a combination is not listed here this indicates it wasn't tested, not that it will not work. However it is recommended that these combinations be tested first by new user.

prc-eclipse
Eclipse
C/C++ Development Tools
0.3.0
2.1.2
1.2.1GA
0.2.1
2.1.2
1.2.1GA
0.2.1
2.1
1.1.0GA
0.2.0
2.1
1.1.0GA

Further reading

PalmOS Programming: The Developer's Guide, Rhodes & McKeehan, O'Reily, ISBN 1-56592-856-3.
This book provides an in-depth guide not only to the PalmOS but also to prc-tools and POSE. This makes it an excellent introductory text and very capable getting started guide.

C/C++ Development User Guide, click Help > Help Contents.
This is a complete introductory test to Eclipse C/C++ Development Tools. It provide an excellent following on point from the tutorials in this document.

Workbench User Guide, click Help > Help Contents.
In the tutorial above the focus has been on easy to follow instructions rather than demonstrating the most efficient way to work. This document will describe in more detail how the Eclipse workbench works and how to customize it to your liking.

Palm OS Programmer's Documentation, click Help > Help Contents.
This is PalmSource's official reference texts regarding the Palm OS. The are fully indexed within the help system and well worth getting familiar with. Note that once you have downloaded the doc.zip file you must restart Eclipse before the indexing will work correctly.