Writing applications for PalmOS using native ARM code, especially using only free tools is something that seems impossible to most people. Well, with this tutorial I aim to prove them wrong: the aim is create a simple breakout tool using only free tools. It's primarily aimed at people who have some experience with the programming language C, but have never developed for PalmOS. However if you have some understanding of how a computer works, you should be able to complete it without too many difficulties as well.
Basically, this document is divided into the following parts:
Tools Setup
Cygwin
PRC-Tools
PalmOS SDK
PEAL
PARM Lib
pilrc
The breakout game will be posted lateron :)
Naturally, the first thing you want to do is set up all the tools you'll need to compile your code into a PalmOS application, While this is a bit of a task, most of it is pretty straightforward, the most difficult part is actually knowing what you are going to need:
All the tools you are going to use are actually Linux tools, so the first thing you're going to need is a Linux-like environment. Of course you could install Linux, but of course that's not for everybody.
Cygwin is basically an environment that translates Linux commands into their Windows counterparts, so that Linux apps can run under Windows. Think of it as a Linux emulator (Before the more experienced users start crying: I know that's not the way it works, but for our purposes this comparison is sufficient).
Installation is very simple, just download the installer from http://www.cygwin.com/ (“Install or update now! (using setup.exe)”) and run it. Chose the following options:
“Next” ->
“Install from the Internet”, “Next” ->
“Root Directory” (Enter the path where you want to install Cygwin), “Install for All Users”, “Default Text File Type Unix / binary”, “Next” ->
“Local Package Directory” (Enter path where downloaded files should be saved, so you can reuse them when reinstalling Cygwin), “Next” ->
“Direct Connection” or whatever you need to get a connection to the internet, “Next” ->
Enter “http://prc-tools.sourceforge.net” into the “User URL:” field, press “Add”, Locate “http://prc-tools.sourceforge.net” in the list, click to select, locate a different mirror, for example “http://ftp.heanet.ie” is pretty reliable, hold down “CTRL” while selecting it, check if both “http://prc-tools.sourceforge.net” and “http://ftp.heanet.ie” are selected, “Next” ->
Click on the “+” in front of “Devel” and find the packages “GCC”, “Make”, “PRC-Tools” and “PRC-Tools-ARM”. Click on the word “Skip” next to them until it says “install”or the latest version number (Don't install “pilrc”), “Next” ->
“Installation Complete”
Now the compiler is installed and ready.
Unfortunately, you need a little more than just a compiler to create a working program. You also need some libraries that allow you access to the PalmOS system internals. These libraries are contained in the PalmOS SDK. To get it, you have to register at http://www.developerpavilion.com/. After you have registered, sign in and go to “Palm OS Developer Tools“. Chose “Core Palm OS SDK” and finally download “Palm OS Garnet SDK (68K) R3 PRC tools Generic UNIX”. Don't worry about it saying “UNIX”, that includes Cygwin as well. Create a new directory inside your Cygwin installation and name it “PalmDev”. Save the file to that directory. (While you're there, it's probably a good idea to also get the PalmOS reference, companions and simulator)
Open the Cygwin Bash Shell from your Start Menu and perform the following actions:
cd /PalmDev/
tar -xzf palmos-sdk-5.0r3-1.tar.gz
palmdev-prep
(Of course, if the archive has a different file name, use that instead of “palmos-sdk-5.0r3-1.tar.gz”)
After running palmdev-prep you should get something like this:
Checking SDKs in /PalmDev
sdk-5r3 headers in 'include', libraries in 'lib'
When GCC is given no -palmos options, SDK '5r3' will be used by default
Writing SDK details to configuration files...
...done
OK, so now the SDK is installed and configured as the default option for the PalmOS compiler. Now you could already start writing code for the 68k plattform. But we want to do a little more than that.
Problem is that the arm-palmos-gcc compiler, aside from not working well with the SDK, is that it is pretty limited in what C features it supports. Especially global variables are a problem and this is where PEAL comes in. PEAL is a little parser that relocates data so that global variables work. To install it, just download the tar.gz archive from http://www.sealiesoftware.com/peal/ and place it in PalmDev as well. Extract it with
tar -xzf peal-2005_4_14.tar.gz
(Or whatever you named that file).
This will extract peal and create a directory named something like “peal-2005_4_14” to rename it to just “peal” enter
mv peal-2005_4_14 peal
Now, change to that directory with
cd peal
And go to the postlink directory
cd postlink
Now all you've got to do is compiling PEAL. Just type in
make
You'll get a few warnings, but after a few seconds you'll get back to the shell.
Enter
./peal-postlink
and you get the help message for PEAL.
Now we have to overcome the final (and most difficult) shortcoming of arm-palmos-gcc: It's inability to communicate with PalmOS. PARM does some magic to do this... it's rather complicated and you actually don't need to understand it, so there's no point trying to explain it. Installation is very simple, just download http://www.tapper-ware.net/files/PARM.zip and extract it to your PalmDev directory. It will create a PARM directory containing the necessary files and an example. Change to the example directory with
cd /PalmDev/PARM/example/
The sample code is contained in main.c, make68k.sh contains the information to build the application so that the PalmOS simulator can run it, while makepno.sh compiles the real ARM application. Try it. Run
./make68k.sh
and a main68k.prc file should appear in the directory. Drag it onto the simulator and run “MyBreakout”. It will display an empty screen and when you click somewhere it will draw “Hello World” at that point.
Now try to build the native application. Run
./makepno.sh
and it will first output a warning message
In file included from ../../pnotest.c:27:
../../pace_gen.c: In function `StrPrintF':
../../pace_gen.c:133: warning: dereferencing type-punned pointer will break stri
ct-aliasing rules
Just ignore it, that's normal. You'll get it every time you compile something, there's nothing wrong with that. A mainpno.prc file should appear that's identical to main68k.prc, but contains fast, native ARM code. Hotsync it and see if it works. If makepno.sh throws any more errors than it probably can't find some file, because you placed it somewhere other than the default location. In that case you need to edit the make* scripts. You really only need a simple text-editor for that, but it has to support UNIX-style linebreaks... that's something pretty much any editor besides notepad can do, but my favourite editor is SciTE ( http://scintilla.sourceforge.net/SciTEDownload.html ), because it requires no installation and has pretty good source highlighting for about any programming language I know. Open makepno.sh in the editor of your choice and you'll see the script's source. The most common problem is that you installed PEAL somewhere else than /PalmDev/peal . Just look through it and most likely, you'll spot the culprit within seconds.
Pilrc is a resource editor for PalmOS. You'll need it to add icons, forms, bitmaps and so on to your PRC file. Just download pilrc-3.2-win32.zip from http://sourceforge.net/project/showfiles.php?group_id=7404 and extract it to your \windows\system32\ directory. That's it :) I'm not going to give you a sample now, but we're going to need it when we do the breakout game next time.
See you then :)
Hans