PalmOS port

From Lazarus wiki
Revision as of 16:22, 28 May 2006 by Mazen (talk)

PalmOs port is in its early beginning stage. The port is started and will be maintained by Mazen Neifer. Peter Vreman ported PalmOs API headers.

Status

  • The 2.1.x compiler has compiler support (very experimental) for PalmOs.
  • ARM CPU is supported.
  • The following platforms will be supported:
    • Zire72 – PalmOs version: 3.0
  • Base RTL units are not yet ported.

Building Tutorial

During the tutorial some paths will be supposed to demonstrate the build process. Just substitute those paths with the ones on your system.


Step 1 - Cross binutils

These are the basic tools necessary to create executables, such as: Linker (ld), Assembler (as), Archiver (ar) (Creates smartlinking .a files), strip and some others.

You need cross binutils for arm-palmos, debian linux provides a ready to use package prc-tools-utils. Just "apt-get install prc-tools-utils" will do the job. Otherwise, you need to get them from http://www.palmos.com/dev/dl/dl_tools/.

Extract them to some dir in the path on your machine. In a debian machine these are installed to /usr/bin/arm-palmos-*


Step 2 - Cross compiler

Now you need to build fpc cross compiler for ARM processor. To do that you need latest fpc 2.1.x sources and working installation of fpc 2.0.2 or 2.0. Under debian linux you may install the fp-compiler package ("apt-get install fp-compiler"

Get the latest 2.1.x source repository from Subversion: http://www.freepascal.org/develop.html#svn

We will supose that your are using debian linux installation (etch or sid) and fpc compiler is located here: C:\Programas\fpc\bin\i386-win32

And your Free Pascal 2.1.x source code is located here: C:\Programas\fpc


Step 3 - The Build process

In order to build the cross compiler it is necessary to have a correct PATH environment variable. On Windows it is very easy to get a PATH crowded with information put by installers. To ensure that your path is correct, create a batch file with the following code:

PATH=C:\Programas\fpc\bin\i386-win32;C:\Programas\arm
make cycle CPU_TARGET=arm OS_TARGET=PalmOs

Put this file on C:\Programas\fpc\compiler, open the Windows command line, go to this folder and execute the batch file.

On the end of the compile you should not see any errors.

You should have a ppccrossarm.exe in C:\Programas\fpc\compiler and some .o and .ppu files in C:\Programas\fpc\rtl\units\arm-PalmOs

Now copy those files to your Free Pascal installation. The cross compiler ppccrossarm.exe should go to C:\Programas\fpc\bin\arm-PalmOs and the units to C:\Programas\fpc\units\arm-PalmOs


Step 4 - Configuration file

Now you need to create fpc.cfg configuration file in C:\Programas\fpc\bin\arm-PalmOs folder in order to use ppccrossarm.exe easy.

Create empty fpc.cfg file in C:\Programas\fpc\bin\arm-PalmOs folder and add the following lines to it:

-TPalmOs
-FuC:\Programas\fpc\units\arm-PalmOs
-XParm-PalmOs-
-FDC:\Programas\arm

Finally add C:\Programas\fpc\bin\arm-PalmOs and C:\Programas\fpc\bin\i386-win32 to your PATH environment variable.

Remember to substitute the paths with the ones on your system.

Compiling a Test Project

You compiled the compiler! Now, what can I do with it? This is a tutorial to create a hello world like software with your new compiler.

Step 1 - Installing and Configuring the Emulator

You will need a Windows CE Emulator configured for ActiveSync. The ActiveSync is necessary to install PocketCMD, a command line tool to run our hello world software.

Download the free Pocket PC device emulator from Microsoft. It emulates ARM CPU. It is beta currently, but stable. http://msdn.microsoft.com/mobility/windowsmobile/downloads/emulatorpreview/default.aspx

There is a tutorial on how to set up the Emulator for ActiveSync here.

Step 2 - Installing the command line

Download and install PocketCMD by SymbolicTools. Get it here

Check the PalmOs port notes section bellow for more details on command lines on Pocket PC.

Step 3 - Compiling

A example file to compile:

program test;

{$apptype console}

var
  Str: string;
begin
  WriteLn('Software Developed with:');
  WriteLn('The Free Pascal Compiler');
  WriteLn('');
  WriteLn('Please, enter your name:');
  ReadLn(Str);
  WriteLn('Your name is: ' + Str);
end.

Sample command line to compile test.pas:

ppcrossarm test.pas

You will get test.exe executable file. Copy it to your Windows CE device and run.

Here is a screenshot of a software created this way.

Debugging PalmOs applications

GDB can be used to debug your PalmOs applications remotely via ActiveSync. Download GDB 6.4 for Win32 host and arm-PalmOs target here: ftp://ftp.freepascal.org/pub/fpc/contrib/cross/gdb-6.4-win32-arm-PalmOs.zip

Some hints:

  • Pass --tui parameter to GDB to enable TUI interface which makes debugging more comfortable.
  • Use unix line endings (LF only) in your pascal source files. Otherwise GDB will show sources incorrctly.

How to use:

First, make ActiveSync connection to your Pocket PC device.

Then launch gdb:

gdb --tui <your_executable_at_local_pc>

On gdb prompt type:

run or just r

GDB will copy your executable to the device in \gdb folder and run it.

Here is a short list of most needed GDB commands:

  • s - step into.
  • n - step over.
  • c - continue execution.
  • br <function_name> - set a breakpoint at function_name. Use PASCALMAIN to set a breakpoint at program start.
  • br <source_file>:<line_number> - set a breakpoint at specified source line.

To learn more how to use GDB read its documentation here: http://www.gnu.org/software/gdb/documentation

Building FPC libraries

If you want to build libraries available with FPC just go to library folder and execute:

PATH=C:\Programas\fpc\bin\i386-win32;C:\Programas\fpc\compiler;C:\Programas\arm
make OS_TARGET=PalmOs CPU_TARGET=arm PP=ppcrossarm.exe

For example you want to build FCL. Go to fpc\fcl folder and execute the command above. You will get FCL compiled units in fpc\fcl\units\arm-PalmOs.

Documentation

PalmOs port notes

  • chdir procedure always produces an error (PalmOs does not support setting of current directory).
  • All file/dir paths must be absolute (started with \).
  • PalmOs is unicode OS. All string parameters to API calls must be PWideChar.
  • PalmOs does not have support for environment strings.
  • PalmOs does not have support for console applications by default. But you can install console support by yourself. Please note that FPC creates GUI applications for PalmOs target by default. To create console application you should use -WC compiler switch or put {$APPTYPE CONSOLE} directive to source code.
    To enable console in PalmOs install one of the following programs:
    • PocketCMD by SymbolicTools. It is recommended solution. Get it here
    • PPC Command Shell from Microsoft Windows Mobile Developer Power Toys. Get it here
      PPC Command Shell have less features than PocketCMD. Also it have some issues. One of them - a new console window is opened even if an application is started from a console command prompt.

Links

Here are some links related to ARM CPU Architecture

Contacts

Write any questions regarding PalmOs port to Yury Sidorov