GNU Pilot SDK

 

GNU Pilot SDK FAQ

0. Intro

Jeremy H. Sproat was the maintainer of this FAQ until it was found out that this has been unmaintained for long and the information is about to vanish. http://www.unmaintained-free-software.org/wiki/GNU_Pilot_SDK_FAQ

To preserve the data has been imported by MatthiasM to the Palm OS Development FAQ Wiki to allow easy collaboration.

 

0.1. Maintainer of the FAQ

Jeremy H. Sproat The Palm OS Development FAQ TWiki Software is the new maintainer. Everyone can collaborate after TWikiRegistration

 

0.2. Where can I find the FAQ on the Web?

I'll be posting this FAQ to the newsgroup pilot.programmer.gcc on news.massena.com at around the first of each month. Also, you can find it at its home on the Web: http://www.geocities.com/SiliconValley/Horizon/5249/GNU_Pilot_SDK.html A search for "GNU Pilot SDK FAQ" will turn it up as well. If you send me an e-mail, I might be able to throw a copy your way.

This FAQ has been moved to http://flippinbits.com/twiki/bin/view/FAQ/GNUPilotSDK

 

0.3. About the FAQ

This FAQ came about because I had so many questions that I didn't know where to start, and browsing the newsgroups revealed about fifty others who felt the same way I did. So I stopped asking where the FAQ was and started making one.

It is my intent to make this FAQ a quick reference to answer all those GNU Pilot SDK questions that can't be or aren't answered in the documentation. Even though my main area of experience in on the Win32 platform, I will make every effort to make this FAQ as OS-balanced as possible.

This is in no way intended to replace the existing documentation. If you have a question that is answered there, then you shouldn't have to look here for it.

Additionally, I will explicitly delete Pilot programming questions e-mailed to me personally and expecting a personal repsonse. If it's clearly in the docs, you should read it there first. If it's about changing the behavior of programs in the SDK, take it up with those who manage the utilities. If it's a question that's best answered by people on the newsgroup, send it there!

 

0.4. What do the [+++] and [***] mean?

This is the method by which I mark questions that have been added [+++] or changed [***] since the last posting to pilot.programmer.gcc.

 

0.5. Where do you get the questions and answers for the FAQ?

I get a lot of them from questions that I have found answers to, a lot of them from browsing the newsgroups pilot.programmer.gcc and pilot.programmer, and a lot of them from Q&A that people submit to the FAQ. It's about equal parts waiting for answers to find me and research.

 

0.6. I've found a flaw in the FAQ / I want to submit a question or answer to the FAQ

E-mail me! Join using TWikiRegistration

This FAQ will always need more Q&A. Answers are favored over questions, and answers with smallish code snippets are gold. Additionally, since I only have a Win32 box on my desk, any help you can give me for any other platform would be greatly appreciated!

This is a living document. It depends on you and others in the Internet community in order to grow.

 

0.6.1. What do the ##'s in the FAQ mean?

These are placeholders for myself. They usually indicate places where I am sure I need an answer, but I can't come up with one right away. If you see this and you have an answer, please e-mail me and let me know!

 

0.7. So who is this Sproat guy, anyway?

Just this guy who decided to stop pulling out his hair and get organized.

 

 

0.7.1. So he's an expert, right?

Not a chance. Not yet, anyway.

 

 

0.8. These questions and answers are way too simple for me.

That's because of two things: First, my level of programming on the Pilot right now is fairly low and many of these questions are based on problems that I've had so far. Second, I haven't received any Q&A that you can really sink your teeth into. Check back later (but please see the next question!)

 

 

0.9. This bites / I could do a better job on the FAQ

If you want to do better, let me know. I don't mind passing on the torch as long as the job still gets done.

 

 

0.10. Tools used in writing the FAQ

My main production computer is a Microsoft Windows NT 4.0 workstation patched with Service Pack 3. I use Microsoft Word as it is shipped with Microsoft Office 97 for the general layout. The font is Courier New, 12 pitch. The left and right margins are 0.5". For code re-formatting, regex search and replace functions, diff-ing, and other niceties, I use Visual SlickEdit v2.0a. This FAQ is posted to the Web and the newsgroup pilot.programmer.gcc using Netscape Communicator v4.03.

The software behind the GNUPilotSDK FAQ is now http://twiki.org

 

1. Stuff on the Internet

 

 

1.1. Other FAQs and sources of information

 

 

1.1.1. Pilot Software Development

Found at http://www.massena.com/darrin/pilot/index.html This is the main jump-point for most Pilot developing on the Internet. As well as having links to just about every possible way to write code on the Pilot, Darrin Massena has sponsored a very insightful set of articles by Luiz Coutinho on the hardware inside the Pilot. Bookmark this site at once.

As of January 1, 1998, Darrin Massena is no longer keeping this site the most up-to-date source of Pilot developer information. While this site is still rich in information, he will point you to Wade Hatler's Pilot Programming FAQ, RoadCoders.com, and his pilot.programming.* newsgroups for more up-to-date information.

 

 

1.1.2. PalmPilot Development Resources at RoadCoders

Found at http://www.roadcoders.com/pilot/index.html The RoadCoders site is dedicated to programming for palmtop computers. Here, you will find links to a large variety of SDKs for the PalmPilot, as well as all sorts of source code, programming articles, and merchandise to help you on your quest.

 

 

1.1.3. Wade's Pilot Programming FAQ

Found at http://www.wademan.com/Pilot/Program/FAQ.htm. This is a higher-level Pilot programming FAQ. This is probably the best starting point if you're not sure which SDK to use for your Pilot application. This FAQ is also available in German.

 

 

1.1.4. The Responsive Knowledgebase for Developers

Found at http://www.ResponsiveSoftware.com/kbase/ This is a knowledge base of Pilot programming issues. Not large yet, but keep checking back. I think that this place has potential.

 

 

1.1.5. The Pilot FAQ

Found at http://www.pilotfaq.com. This isn't a programming FAQ, but still a great document to browse for gerneral info about your Pilot and its features. This FAQ is also available in Japanese.

 

 

1.1.6. The Pilot developers' newsgroups at massena.com

Found at:

These are the Pilot developers' newsgroups. They are generously hosted by Darrin Massena. I can get in just fine with Netscape Collabra, and I am sure that most other news readers can access these newsgroups just as well. This FAQ is posted on pilot.programmer.gcc, and many of the questions and answers were taken from there.

 

 

1.2. Other Pilot-related sites

 

 

1.2.1. 3Com/Palm Computing's PalmPilot Developer Zone

Found at http://palmpilot.3com.com/5024.html This is the official 3Com page dedicated to developing for the Pilot. This site has a definite CodeWarrior slant. I couldn't find any info for Palm OS1.

On the gripping hand, this is a good launchpoint for Pilot developers, and the official source for the API documentation.

 

 

1.2.2. Ray's PalmPilot Software Archive

Found at http://www.palmpilotfiles.com/ This is where I go for most of my Pilot software needs. It has a large, categorized index to all the files here, and a list of the last 25 additions. Each file available has a description, a local copy, and a link to the original homepage. Also, there is a large development section with lots of code samples. Good stuff.

 

 

1.2.3. C & PILA Source Code Page

Found at http://www.iosphere.net/~howlett/pilot/source.html This site holds all sorts of sources for Pilot programs written with gcc, PILA, and CodeWarrior. If you're just starting, you definitely should download a couple and see how it's done.

 

 

2. About the utilities

 

 

2.1. gcc / prc-tools

GNU gcc is a very popular and free C/C++ compiler available for just about any platform with more than 2 bits on the chip. prc-tools was born when gcc was ported by D. Jeff Dionne and Kresten Krab Thorup to cross-compile for the Motorola 68328 Dragonball processor. Various utilities in prc- tools were done by Dionne and Ian Goldberg. Dionne is the current maintainer of prc-tools. The current version of prc-tools is 0.5.0., corresponding to gcc version 2.7.2.2. The official prc-tools archive with Linux versions is at ftp://ryeham.ee.ryerson.ca/pub/PalmOS/; you'll need the following GNU utilities at ftp://prep.ai.mit.edu/pub/gnu/: gcc-2.7.2.2, binutils-2.7, and gdb-4.16. John J. Lehett has ported these tools to Win32; you can find this version through http://www.land- j.com/gccwin32.html

As for the FAQ, all the UNIX-based FAQs seem to be out of date. Check the README in the prc-tools release first. A generic gcc FAQ can be found at http://www.fsf.org/software/gcc/gcc.html A more Linux-oriented gcc FAQ can be found at (##needs answer##). A more Win32-oriented gcc FAQ can be found at http://www.cygnus.com/misc/gnu-win32/faq_toc.html Full documentation in html format for gcc, gdb, and make can also be found at Andrew Howlett's site at http://www.iosphere.net/~howlett/pilot/GNU_Pilot.html

Note that gcc is GNU software, and the prc-tools package is a port of gcc. The distinction is important; prc-tools is not maintained, distributed, or handled in any way by the Free Software Foundation, Cygnus, or GNU. In this FAQ, the terms prc-tools and GNU Pilot SDK are used interchangably.

 

 

2.1.1. gdb

gdb is GNU's general-purpose debugger. It comes with the GNU Pilot SDK distribution, and can debug programs sitting on Copilot and XCopilot. It was modified for use with prc-tools by Kenneth Albanowski and D. Jeff Dionne. On Linux, you can use gdb to debug programs on a real Pilot over the wire. I need to get the FAQ location for gdb. Any takers? (##needs answer##)

 

 

2.1.2. Copilot / XCopilot / Zilot

Copilot, XCopilot, and Zilot are excellent (and probably the only!) Pilot emulators for Windows, X-Windows, and Macintosh, respectively. The current version of Copilot is 16h; however, the GNU Pilot SDK is distributed with version 1.0 beta 9 which has been patched to work with gdb. You can find the Win32 version (Copilot), the XWindows version (XCopilot) and a lot of documentation through http://ofb.net/~heath/pilot/copilot/ Greg Hewgill is the original developer for Copilot; Heath Hunnicut has since taken over this task. The changes to Copilot/XCopilot to work with gdb were made by Ian Goldberg and D. Jeff Dionne. Ben Thomas has a copy of Copilot that works with gdb on Windows NT; it can be found at http://www.tiac.net/users/thomas/pilot-downloads.html

Zilot is a Pilot emulator for the Macintosh, ported by Michel Pollet. It is available at http://w3.teaser.fr/~mpollet/Zilot/ It doesn't appear to support the GNU Pilot SDK gdb stuff. (##needs answer##)

 

 

2.2. PilRC / PilRCUI?

PilRC is what you use to compile your resource files into binary files to link with your object code. PilRCUI? is a utility that comes with PilRC which you can use to see how your GUI will look without needing to compile the resource file. Both utilities were written by Wes Cherry. The current version of PilRC is 2.0a. You can find the Win32 version of these programs through http://www.scumby.com/scumbysoft/pilot/pilrc/index.htm. There is no FAQ available for PILRC, but it's really pretty straightforward to use.

 

 

2.3. Emacs

Emacs is a powerful, general-purpose text editor released under the GNU Public License. A trimmed-down version of Emacs is included with prc- tools. The current version of Emacs (as shipped with the Win32 GNU Pilot SDK) is 19.34.1. A generic FAQ for Emacs can be found at http://www.geek-girl.com/emacs/faq/ A Win32-specific Emacs FAQ can be found at http://www.cs.washington.edu/homes/voelker/ntemacs.html

 

 

3. Install issues / Getting started

 

 

3.1. How do I set up gcc in Linux or Windows 95/NT?

Right. In general, before you read a FAQ, you should read the docs. This is one of those cases. The install procedure is quite different between the Linux and Win32 versions of gcc for Pilot. You can find the directions for setting up both the Linux and Win32 versions the end of the tutorial that comes with the GNU Pilot SDK.

 

 

3.1.1. Okay, so where do I find the tutorial / I deleted the tutorial

Reinstall and don't delete anything without backing it up first. Having said that, you can find Andrew Howlett's excellent GNU Pilot SDK tutorial on his Web site at http://www.iosphere.net/~howlett/pilot/

 

 

3.2. I installed gcc to drive D: and now it doesn't work!

Put a \tmp directory on each hard drive. Put a \bin directory on each hard drive, and copy bash.exe into \bin as sh.exe. (## Is there a more streamlined way? ##)

From Derek Kwan: One common problem is the path and environment doesn't setup correctly using gcc for Windowz (either 95 or NT). If gcc is installed on a drive other than C:, it will not update the BAT to setup the path and enviorment. Here is what you should check in your BAT if nothing works. This example is assume you have install gcc on the D:\PROGRAM FILES\GNU PALMPILOT directory

call d:\PROGRA~1\GNUPAL~1\bin\instsh.bat \bin d:\PROGRA~1\GNUPAL~1\bin\bash.exe \bin\sh.exe SET EMACSLOADPATH=d:\PROGRA~1\GNUPAL~1\emacs\lisp SET EMACSPATH=d:\PROGRA~1\GNUPAL~1\bin SET EMACSLOCKDIR=c:\temp SET INFOPATH=d:\PROGRA~1\GNUPAL~1\emacs\info SET EMACSDOC=d:\PROGRA~1\GNUPAL~1\emacs\etc SET EMACSDATA=d:\PROGRA~1\GNUPAL~1\emacs\etc SET gcc_EXEC_PREFIX=d:\PROGRA~1\GNUPAL~1\lib\gcc-lib Also make sure to include d:\PROGRA~1\GNUPAL~1\bin in your PATH.

 

 

3.3. I can't get this to work in Win32S (Win 3.x) / DJGPP (DOS)!

That's because this is a true 32-bit app, and needs features that Win32S and DJGPP lack, such as long filename support. You really need a 32-bit OS for this, but...

From D. Jeff Dionne: It is possible to port these tools to DJGPP, but I've not done it for a while (older versions once were).

 

 

3.4. Can I / How do I set up gcc for developing for the Pilot on the Mac?

From D. Jeff Dionne: For 68k mac, start with Stan Shebs gcc 2.3 (or some such) port of gcc to Apple's MPW. Use that to compile prc-tools (I've never done this, but Palm has asked me if it can be done, and I've acquired some Mac hardware and will make an attempt).

 

 

3.5. Where can I find some source code to look at?

See the section about the "C & Pila Source Code Page". Also, grab a copy of some sample sources (including the Table object source code) from 3Com at http://palmpilot.3com.com/palm/SrcPack1.zip.

For beginner coders, Dave Kelly published source code for his Lottery Checker, and gives some explanations and how-to's on his Web page at http://www.kellyhq.demon.co.uk/pilot.htm.

From Frank Kannemann: The BEST simple source code example: http://www.best.com/~mcravit/pilot/HelloWorld.html The BEST complicated source code example is Launchpad it includes multiple c sourefiles, lots of cool stuff: http://www.nwlink.com/~emilyk/LaunchPad/

 

 

3.6. What is some good software to have on the side?

The Adobe Acrobat Reader is necessary for reading the PilotOS? API docs from 3Com.

Perl comes in handy, especially if you're trying to write GLIBs or taking advantage of Ian Goldberg's pilot-template utility (see next question).

 

 

3.7. Is there a utility to take care of creating the basics for a new app?

Ian Goldberg has put together a perl script which will create a makefile, main C file, etc. for you. See his site at http://www.isaac.cs.berkeley.edu/pilot/, and look for pilot-template, for more information.

Additionally, check out the utilities referred to in the section titled "IDEs, editors and such".

 

 

3.8. How do I get the rest of the Emacs distribution?

The Win32 version of the SDK comes with most of the Emacs files. Missing are the lisp source files, and files from the etc directory. Fetch the file ftp://ftp.cs.washington.edu/pub/ntemacs/latest/i386/emacs-19.34.1- lisp.tar.gz (without the line breaks). In case you can't find this ftp site right away...

From D. Jeff Dionne: Search for 'ntEmacs' and 'washington' on Yahoo.

 

 

3.9. I'm getting the error message "Error while dumping state

(probably corrupt stack) in cygwin_except_handler" when I use the SDK! [+++]

This is on the Win32 platform only. This error can be caused from a rogue cygwin.dll from another Win32 GNU app.

From D. Jeff Dionne: You likely still have the old cygwin.dll from 040 kicking around in the path. They are incompatible.

 

 

4. Common pitfalls / Common questions / Not-so-common questions

 

 

4.1. What are some of the most frequently-used command-line options for gcc?

OPTION WHAT IT MEANS == ========= -c compile only; don't link -o ABC output filename is "ABC" -static link static (not dynamic) -OX optimization level X (a number 1-5) -g build with debug symbols -S build to assembly

 

 

4.2. Can I use the GNU Pilot SDK to compile program sources intended for CodeWarrior?

From D. Jeff Dionne: gcc is now (as far as we know) fully compatable at the source code level with CodeWarrior. CodeWarrior UI resources are still a problem at this time.

 

 

4.3. What does the gcc error DISP16 mean? [***]

This is a linker error. It means that you have called a function that does not exist, or your code segment is too large. Check your code for typos first (especially the API calls, since they tend to be long.)

From Derek Kwan: Most of the time when you have this error, you better check the CaSe? of your functions. For example if you call strstr as in regular C function you will have this error. You have to use StrStr? as in palmpilot developer manual. For me everytime when I have a typo in the function which doesn't exist or the CaSe? of the function doesn't match, I will have this error. Of course YMMV. :)

From Ian Goldberg: The DISP16 error means that a (16-bit displacement) branch could not be constructed, for one of two reasons:

1) Branches cannot span more than 32K, so if you have more than that much code, a refence to a symbol at the end of your code by something at the beginning will give this error. If you get a DISP16 for "bhook_start" or something similar, this is the problem.

2) The symbol referenced simply does not exist. This is the most common reason for the DISP16 error. Check to see if your function name is misspelled or WronglyCapitalized.

From Robert Petersen: Check that you aren't calling a function that is declared static from another source file. Static functions are only available in the source file they are declared in, so the linker will act as if they don't exist for code in separate modules.

 

 

4.3.1. What does the gcc error DISP16 bzero mean? [+++]

From Ian Goldberg: You have a structure or an array declared with a partial initailization, like this:

void foo(void) myvar = 7; /* or */ int bar[6] = ; }

This is a known bug, but it's easy to work around: just complete the initialization, or assign the values in code.

 

 

4.4. I have a PilotMain() function, but the compiler says that I don't!

Make sure that your PilotMain() function is not declared static.

From Ian Goldberg: There's no way your program will possibly link if it has a static PilotMain.

 

 

4.5. Why won't my global data work when I'm running a callback function?

From Ian Goldberg (reformatted): Routines compiled by gcc, but called by routines not compiled by gcc (most commonly, your event handlers) have their globals sometimes broken, unless you use a workaround.

At the top of the callback (right after the var. declarations), put

CALLBACK_PROLOGUE

At the bottom (just before the return), put

CALLBACK_EPILOGUE

Make sure the event handler can only exit by going through the CALLBACK_EPILOGUE.

Also, do #include "callback.h" in your file. callback.h is next.

 

8----cut here----8---- #ifndef CALLBACK_H #define CALLBACK_H

/* This is a workaround for a bug in the current version of gcc: gcc assumes that no one will touch %a4 after it is set up in crt0.o. This isn't true if a function is called as a callback by something that wasn't compiled by gcc (like FrmCloseAllForms()). It may also not be true if it is used as a callback by something in a different shared library. We really want a function attribute "callback" which will insert this progloue and epilogoue automatically. - Ian */

register void *reg_a4 asm("%a4");

#define CALLBACK_PROLOGUE void *save_a4 = reg_a4; asm("move.l %%a5,%%a4; sub.l #edata,%%a4" : :); #define CALLBACK_EPILOGUE reg_a4 = save_a4;

#endif

8----cut here----8----

 

 

4.6. Where can I get a generic makefile?

From Leo Breuss:

8----cut here----8---- #Makefile for gcc PalmPilot crosscompiler m68k-palmos-coff-gcc package. # Change the strings from APP to BUILDPRC to match your own # system configuration. # Place the file into the developping directory. # Start it with "gmake". # "gmake clean" removes all generated files, even the ".prc". APP =myownprogram ICONTEXT ="My Own" ICON =icon.bmp APPID =MyOn RCP =$(APP).rcp PRC =$(APP).prc SRC =$(APP).c GRC =$(APP).grc BIN =$(APP).bin

CC =m68k-palmos-coff-gcc PILRC =pilrc TXT2BITM =txt2bitm OBJRES =m68k-palmos-coff-obj-res BUILDPRC =build-prc BINDIR =bin

# uncomment this if you want to build a gdb debuggable version #DEFINES =-DDEBUG #INCLUDES = -I ../PalmOS2 -I../PalmOS2/UI -I../PalmOS2/System -I../PalmOS2/Hardware #LINKFILES =-l/usr/local/PalmPilot/m68k-palmos-coff/include/math.h # LDFLAGS: including -g links gcrt0.o instead of crt0.o #LDFLAGS = # -On: n=Optimization-level (0=none), -g: needed for debugging CFLAGS =-O0 -g $(DEFINES) $(INCLUDES)

all: $(BINDIR) $(BINDIR)/$(PRC)

$(BINDIR): ; mkdir $(BINDIR)

$(BINDIR)/$(PRC): $(BINDIR)/grc.stamp $(BINDIR)/bin.stamp $(ICON); $(shell cd $(BINDIR); $(BUILDPRC) ../$(PRC) $(ICONTEXT) $(APPID) *.grc *.bin $(LINKFILES)) ls -l *.prc

$(BINDIR)/grc.stamp: $(BINDIR)/$(APP) ; $(shell cd $(BINDIR); $(OBJRES) $(APP)) touch $@

$(BINDIR)/$(APP): $(BINDIR)/$(SRC:.c=.o) ; $(CC) $(CFLAGS) $^ -o $@ cp $@ $(APP)

$(BINDIR)/bin.stamp: $(RCP) ; $(PILRC) $^ $(BINDIR) touch $@

$(BINDIR)/%.o: %.c ; $(CC) $(CFLAGS) -c $< -o $@ # touch $< # enable this line if you want to compile EVERY time.

depend dep: ; $(CC) -M $(SRC) .dependencies

clean: rm -rf .o $(APP) *.bin *.grc *.prc $(BINDIR)/ *~

8----cut here----8----

 

 

4.7. Why has my makefile stopped working?

From Dave MacLeod: Choose your editor carefully. The makefile requires "hard tabs", i.e. Chr(9).

Among the editors that support hard tabs are: Emacs (comes with gcc for Pilot), Visual SlickEdit, Microsoft Word, and others. Check your editor's documentation and/or look for ASCII character 0x09 in a hex dump of your source code.

 

 

4.8. I entered a few lines of code, and now I can't use the 'find' feature of my pilot without crashing! a.k.a. My program crashes the Pilot when I install it! What's going on?!

From Ian Goldberg: You have code in PilotMain outside your cmd test. PilotMain is called not only when your program is launched, but in a number of other situations as well (including when your program is installed, the user does a "Find", etc.). The first parameter to PilotMain is "cmd", a command code that indicates under what circumstances the program was started. Usually, you only want to do things for a "Normal Launch"; that is, when (cmd == sysAppLaunchCmdNormalLaunch). Note especially that for most of the launch codes, _you have no global variables and any attempt to access them will likely crash the Pilot_.

If you have any code outside the test for the value of cmd, you are almost certainly doing the Wrong Thing. The following PilotMain is, IMHO, canonical:

DWord PilotMain(Word cmd, Ptr cmdPBP, Word launchFlags) else return 0; }

The only reason you would need to change this is if you wanted to handle different launch codes.

 

 

4.9. What does "#pragma pack(2)" mean?

This is a holdover from prc-tools version 0.4.0 and earlier.

From Ian Goldberg: Short answer: It does nothing, and can be removed.

Long answer: It sets the alignment for elements of structures to 2 bytes. However, that's the default for m68k-palmos-coff-gcc, so it's unnecessary.

 

 

4.10. How can I reduce the size of my .prc file? / Why has my .prc file size increased dramatically?

Try compiling with the gcc command-line switch -O2 (optimize) and remove any -g switches (debugging symbols) when you link.

From Johnathan Vail: Are you using floating-point or libc functions like printf()? If you start linking in standard C libraries you can bulk up an executable pretty quickly.

From Ian Goldberg: You should always compile with -g. The debugging symbols don't get put into the .prc file, so removing it won't make a difference in the size of the .prc file (and you won't be able to debug your program).

Linking with the -g flag does add a very small amount of code to the .prc file.

 

 

4.11. My local variables are overwriting my global variables! / Is there a limit to the size of local variables?

From Ian Goldberg: Is [your local variable] local or is it static? Locals (automatics) go on the (extremely small) stack. Statics sit next to globals in memory. There's no way a 5K object can be put on the stack (but gcc doesn't know this; that's a runtime decision).

If you are declaring your big array as:

static int foo(int bar)

then change it to:

static int foo(int bar)

If you're already declaring it static, then you're probably writing off the end of it, which would start into global variables.

 

 

5. Copilot / XCopilot / gdb / Debugging

 

 

5.1. How can I debug with Copilot / XCopilot and gdb?

1) First of all, you need TCP/IP on your computer. (If you can go over the Internet, you have TCP/IP.)

2) Compile your program with -g (debug symbols). Don't delete the .o files after compiling, as these contain the actual debug symbols.

3) Start m68k-palmos-coff-gdb with the name of your program (without the .prc extension) as an argument.

4) Launch Copilot or XCopilot with the argument "-gdebug :2000" (make sure that there is a space between the "g" and the ":"!)

5) From the gdb prompt, give the command "target pilot <PATH", where "<PATH" depends on where your code is running. If you're using Copilot, it's "localhost:2000". For XCopilot, "/dev/ttyqf". If you're debugging on a real Pilot from Linux, try "/dev/pilot" or "/dev/ttyS0" or whatever port your Pilot is using.

6) Before you enter the program you are debugging, be sure to load gdbpanel.prc into Copilot/XCopilot and mark the checkbox "Enable stub" inside this app. (You can find this file in the "example" subdirectory.) 7) Be sure to reload the program you are debugging. Launch your program. gdb should break on PilotMain().

 

5.1.1. I don't have an "example" directory / I can't find gdbpanel.prc!

Reinstall the GNU Pilot SDK, this time installing the examples.

 

 

5.2. I'll just use Copilot / XCopilot to debug, thanks.

From D. Jeff Dionne: XCopilot has no built in debugger, it relies solely on gdb, where CoPilot? has a built in debugger that knows about MetroWerks? debug symbols.

If the standard Copilot debugging is enough for you, you can compile with [gcc option] -mdebug-labels and you code will contain the same sort of wasteful strings and such as the other tools generate. This feature was added by Kresten a while ago to make Copilot's debugger happy.

 

 

5.3. How can I debug my program in Copilot on Windows NT?

You can't, at least with the Copilot that is distributed with prc-tools. When you try running it, you will get an error message saying that your executable is not a valid NT image.

Ben Thomas has built Copilot so that it will work with gdb on Windows NT. D. Jeff Dionne is working with him to include the fix in the next release of prc-tools. For now, it can be obtained from http://www.tiac.net/users/thomas/pilot-downloads.html

 

 

5.4. I downloaded Copilot / XCopilot from its original Web site, but I

can't get it to debug with gdb!

Right now, the only version of Copilot and XCopilot that will work with gdb is that which comes with prc-tools.

 

 

5.5. The lines in gdb don't match up with what my program's doing!

This seems to be happen only on Windows 95/NT. Your extra end-of-line character is throwing off the debugger. Save your source files in Unix format (end-of-line = 0x0A instead of 0x0D0A), recompile, and try again.

From Ben Thomas: Line number problems can also occur if you are out of sync between source and binary. Surprisingly simple, but it happens. Just rebuild to cure.

 

 

5.6. I'm debugging and I can't see all of my variables!

From D. Jeff Dionne: If you've specified any optimization level ( a -O command line switch ) to gcc, it may have optimized away those vars. Try building again without any -O switches and see how that goes.

 

 

5.7. Why can't I edit database records in-place while I'm debugging?

From Yves Mahe:

The PalmPilot databases are write protected (see documentation for DmWrite). Old versions of Copilot used to allow it, but new versions catch this error that will generate a Fatal Error on the PalmPilot. The only way to modify a database record is to use DmWrite or DmSet.

 

 

5.8. How do I compile a breakpoint into my code?

You may not need to. gdb should break on PilotMain(), and will allow you to set breakpoints from there. Here are a couple more suggestions:

From Yves Mahe: Put the following in your C code: asm( "dc.w 0x4afc"); for breakpoint And the debugger will be launched by Copilot automatically.

From D. Jeff Dionne: Try DbgBreak() It's defined in System/DebugMgr.h, but for the CoPilot? debugger only, which we ripped out of XCopilot.

 

 

6. API / Libraries

 

 

6.1. What APIs are available?

There is the standard API from 3Com. The most recent version is for Palm OS2. As well as additional API calls, there are some calls that have changed from Palm OS1. See the documentation available from 3Com for more details.

The HackMaster utility from DaggerWare has an API you can use to create system-level control panel-like utilities. See the section on HackMaster for more information.

PilRC 2.0 introduced the capibility to create, manage, and generally play with 2-bits-per-pixel greyscale bitmaps. Wes Cherry has devised an API called Win2 to handle this. For more information, please see http://www.scumby.com/scumbysoft/pilot/win2/

 

 

6.1.1. Can I use the standard C libraries?

From D. Jeff Dionne: prc-tools comes with a minimal libc that contains string functions, (s)printf and such. Also comes with a single precision math library that can be used on PalmOS1? or 2. libc can be used shared or static.

 

 

6.1.1.1. What does the Copilot error "palmos_GLib.c, Line:23, C Library is
not installed" mean?

From D. Jeff Dionne: You've used a function from libc (printf, whatever) and you're linked dynamic, which is the default. When your code calls this function, it tries to auto load the shared version of libc. If you load Libc.prc into your Pilot, it will find it at run time, or you can specify -static when you link. That will link libc.a into your code insted of linking with the shared version.

 

 

6.1.1.2. The <ctype.h functions aren't working!

That's because you're linking the standard C library dynamically.

From Paul McDermott: If you look in <ctype.h, you'll see that isalpha() is defined as a macro which looks up values in a global array _ctype[]. When the shared library is created, this array becomes global for the shared library, not for your application. So when isalpha(c) is converted to ((_ctype+1)[c]&(_U|_L)), _ctype is pointing somewhere invalid, and you get crazy results.

<ctype.h functions should work if you link libc as static. The problem described above will only occur if if you create a libc shared standard C library.

 

 

6.1.2. I can compile C++! Is there a class library for the Pilot?

Yes there is. It's called PCL, and it's being developed by Thomas Johler. You can find it along with more information on compiling C++ for the Pilot at <http://home.t-online.de/home/johler/pilot.html

 

 

6.1.2.1. I can't compile C++! Where can I find information on getting
this to work? [+++]

(##needs answer##)

 

 

6.2. What's this business about shared libraries?

Ian Goldberg has detailed the necessary steps to creating a GLIB shared library. Please see his site at http://www.isaac.cs.berkeley.edu/pilot/

From Ian Goldberg: Shared libraries enable many applications to share common code, without having to have a copy of the code in each application's code resource. For example, there can be one copy of encryption routines, or a version of the standard C library, and many applications can be using it.

Shared libraries can also help you get around the

Today: Sep 10, 2010