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.
- Eclipse
- C/C++ Development Tools
(CDT)
- prc-eclipse
- prc-tools
(version 2.3 or greater)
- 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:
- Click File > New > Project. The New Project Wizard
opens.
- Select C.
- 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.
- Click Next
- Provide a name for your project, type it into the Name
box.
- Click Finish.
- 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:
- Click File > Import. The Import Wizard opens.
- Select Zip file.
- Click Next.
- Click Browse and select the TZones zip file,
tzones-2.1.zip for
example.
- Ensure you new project is listed in the Into Folder box.
- 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:
- In the C/C++ Projects view, right click on your project
folder, and select Properties.
- Click C/C++ Make Project, and select the Make Builder
tab.
- Click the Browse button and select the TZones directory
contained in your project.
- Click OK.
- 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:
- Click Run > Debug.
- Select C/C++ Local, and click New. The newly
created debug configuration will inherit its name from your project
because it is selected.
- 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.
- Select the Debugger tag.
- Select PalmOS GDB Debugger from the Debugger drop
down menu.
- Ensure the Stop at main() on startup box is not checked
since most Palm OS programs do not have a main() function.
- Into the GDB debugger box type 'm68k-palmos-gdb',
or use the Browse button to locate the debugger executable.
- 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:
- 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.
- Click Run > Resume. The globe will start spinning
again the thread will be marked Running.
- In POSE, click on the Home or Applications icon.
- If a message box warns you about memory leaks, click Continue.
- Start the TZones application again. The debugger will stop just
inside the PilotMain function.
- 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.
- Click Run > Resume. The globe will start spinning.
- In the Outline frame select DoPreferencesDialog.
The editor will automatically select this function for you.
- Double click on the left margin immediately to the left of the
function definition. This will set a breakpoint on this function.
- 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.
- 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.
- Right click on the terminated session and click Terminate and
Remove to tidy up the Debug frame.
- 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.