Chapter 2. Platforms

Table of Contents

Desktop Windows
Overview
Installing Visual C++ 6.0
Creating the First Project
Desktop windows differences
Where to go from Here?
Symbian
Overview
Installation
Working with the Symbian tools
X-Forge Examples
Troubleshooting
PocketPC
Overview
Installation
First Program
Tapwave Zodiac
Overview
Installation
Using Tapwave Tools
Tapwave Zodiac differences
Palmsim Notes
Troubleshooting
Linux

Desktop Windows

Overview

This section walks you through getting an X-Forge application to compile and run under the desktop Windows platform.

While not a real release platform, the desktop Windows platform is useful for rapid development of X-Forge applications. Debugging is also often much simpler under the desktop platform, thanks to much more mature tools available.

Additionally, the desktop Windows platform of X-Forge has been designed to be embeddable into other applications. The core examples-directory includes an example of a simple MFC application that has X-Forge embedded in it.

The preferred development environment for desktop Windows is Microsoft Visual C++ 6.0 Professional (also included in the Microsoft Visual Studio 6.0 Professional package). Other versions may also work. The Desktop Windows platform has been tested with Visual C++ 7.0 (included in the Visual Studio .NET package) as well.

Installing Visual C++ 6.0

Insert Visual Studio CD1, and wait for the installer to launch. If you have the autolaunch disabled, you will have to open the CD with Windows Explorer and run install.exe.

In the installer, click 'Next', accept the EULA, click 'Next' again, enter the product id (found on a sticker on the back side of the CD cover), and click on 'Next' again.

Pick 'Install Visual Studio 6.0', and not the server applications package, click on 'Next'. If the default installation directory for common files is ok by you, click on 'Next'.

Click on 'Continue', and you will see your product id. You can get this on the 'About' box of Visual Studio later if you need it. Click on 'OK'.

Next click on the icon that has the Visual Studio infinity-sign drawn over some installation icon. On the package selection screen make sure Visual C++ is installing; the default options should be ok. Feel free to select or deselect other options as long as the C++ default packages are installing. When you're done, click on 'Continue'.

Make sure the 'Register environment variables' tick box is ticked, then click on 'OK'. After this the installer should start installing Visual Studio. If asked, insert different CDs. After the installation is done, click on 'OK' and 'Restart Windows'.

After reboot, the installer will ask whether you wish to install MSDN. Insert the MSDN install CD and answer 'Yes'. Click on 'Next', 'Continue', and you should be offered a product id again. Click on 'OK', agree to the EULA, select 'Full installation', and the installer should start installing again. If asked, insert different CDs.

Once the MSDN installation is complete, click on 'OK', and the installer should ask whether you wish to install InstallShield VC6 Edition. You can install this if you want, but we'll skip it here. Clicking on 'Next' will (depending on your edition) give you the choice of installing back office SDKs. We'll skip these as well. Click on 'Next'.

Next screen will let you register Visual Studio, and then you can click on 'Finish'.

Download and install VC6 service pack 4 or later. As of this writing you can find it at the following location:

http://msdn.microsoft.com/vstudio/downloads/updates/sp/vs6/sp4/default.asp

The service pack installer will ask you to agree to another EULA; otherwise it is pretty straightforward.

Creating the First Project

If you haven't done so already, create a folder in your hard drive and copy the X-Forge distribution into it. We'll use c:\fathammer\ but you can put the distribution anywhere you wish.

Launch Visual Studio, at Start / Programs / Microsoft Visual Studio 6.0 / Microsoft Visual C++ 6.0.

The Visual Studio workspace.

Close the tip of the day, then select file / new.

Select 'Win32 Application', set the location to where you wish to create your projects; we'll use c:\fathammer\ for these as well. Next, enter project name, we'll use 'tutorial'. You will notice that the location changes to c:\fathammer\tutorial. Click on 'OK', and select 'Empty project' at the next dialog. Click on 'Finish', and 'OK' to the final dialog.

Click on the 'File view' bottom tab (near left bottom of the window), click on the plus sign on the tree view. Next, right-click on the 'Source files' item, and select 'Add files to folder'. In the file open dialog, type tutorial.cpp and click on 'OK'. You will receive a dialog asking whether to add a non-existent file to the project; answer 'Yes'.

Next, click on the little plus that appeared next to the 'Source files' in the tree view, and double-click on tutorial.cpp. Answer 'Yes' to the question whether to create the file.

Depending on your preferences of the development environment, you may wish to maximize the editor window at this point.

Type in the following source code (or, at your preference, copy it from core_examples/tutorial/e1_minimal/source/e1_minimal.cpp).


#include <xforge.h>

void xfcAppPref(XFcAppPrefs &aAppPrefs)
{
  aAppPrefs.mTotalMemoryLimit = (INT32)(1024 * 1024 * 0.5);
  aAppPrefs.mResourceMemoryLimit = (INT32)(1024 * 1024 * 0.5);
  aAppPrefs.mMinimumExtraMemory = (INT32)(1024 * 128);
  aAppPrefs.mUID = 0x0F470001;
}

INT32 xfcAppInit() 
{
  xfcUseDefaults();
  return 0;
}

Make sure you save at this point. Saving can be done through 'Control-S' for the current file, or 'Alt-F L' to save all files and the workspace. You can also click on the "stack of disks" icon to save everything.

Next we'll set up the paths in Visual Studio. You won't need to do this step but once per installation.

Go to Tools / Options, and select the 'Directories' tab.

By default the dialog shows the include paths. Add include path to the X-Forge distribution include directory (in our example, c:\fathammer\xforge\include). Next, select 'Library Paths' from the selection box, and add the X-Forge library path to the list (in our example, c:\fathammer\xforge\lib\windows). Click on 'OK'.

If you try to compile now, you'll get lots of error messages. We'll need to link to several libraries and set some compile parameters first.

Go to Project / Settings. Select the 'Link' tab.

Add the following libraries to the beginning of the library list: xfcored.lib xfutild.lib zlib.lib winmm.lib wsock32.lib

Note

We're configuring the debug build here, as you can see from the top left side of the dialog. The release mode configuration is exactly the same, except that you would link to xfcore.lib and xfutil.lib instead of the 'd' versions.

Next, go to the 'C/C++' tab. Here, add XFC_PLATFORM_DESKTOPWINDOWS to the preprocessor directives list. The desktopwindows platform tells X-Forge which platform we're running.

Note

When embedding X-Forge into another windows application, you should also add XFC_MEMMGR_DISABLE to the above list, and link towards xfcoreemb.lib instead of xfcore.lib. The memory manager has to be disabled so that the memory manager does not conflict with MFC, for instance.

Next, click on 'OK', and you're ready for compilation. Click on 'Build' in the 'Build' menu, or just press 'F7' for the same effect.

If you try running the application (F5), you will get a dialog about missing DLL. The application requires zlib.dll. You can find this in the xforge/lib/windows directory of the X-Forge distribution. Copy it to the same directory where the executable is (in our example, c:\fathammer\tutorial\Debug\), and try again. You should have a black, empty X-Forge window.

Desktop windows differences

The Desktop windows platform contains several differences that are designed to help in development. Assertion failures are more descriptive, and more error situations are checked, such as filename case differences.

Also, in the desktop windows versions, F12 saves screenshots. The shots are saved as BMP files with the name of ss0001.bmp. The number in the filename increases when you save more screenshots.

Where to go from Here?

If you wish, you can continue straight to the platform-independent 'Getting Started' chapter and get into X-Forge programming without delay (starting with explanation of what the above program actually does).

Alternatively you can read some other platform-specific getting started chapter, if you want to see how to make things run on an actual device first.

Symbian

Overview

This section introduces you to the Symbian platform specific features. X-Forge currently supports developing with the Series 60 SDK (e.g. for Nokia 7650) and the free UIQ SDK (e.g. for Sony Ericsson P800). For the latter the Symbian recommended development environment is Metrowerks CodeWarrior, and to run applications in the UIQ emulator requires it. However, we don't currently have support for the CodeWarrior, but might add it at some point. You will have to do without the emulator on UIQ, but you'll most probably be spending most of the time developing for the desktop Windows platform with your X-Forge projects anyway.

In general, Symbian development is a bit different from desktop system programming. The development tool chain is a bit more complicated. Debugging on the target device is not straightforward, and the emulator behaves differently from the actual device. In order to test the application on the device, you have to build the whole installation package and transfer it to the device. For these reasons it is recommended that the application is first developed on desktop Windows platform and then recompiled to the Symbian environment to test in on the device. This way the development cycle becomes much shorter.

Note

It is recommended that you do not use the Symbian emulator when developing your X-Forge application. Do the main development on desktop Windows platform and test the application in the actual target device on Symbian platform.

Under Symbian platform each of your applications will need a unique identifier or UID. As of this writing, the UID's have to be ordered from Symbian. However, if you want a few UID's just for development, you can use numbers in the range 0x00000001 - 0x0FFFFFFF. These UID's should not appear in any released products. For instructions on how to order UID's, please refer to Symbian documentation for up-to-date information.

Note

As of this writing, the UID ordering information can be found at http://www.symbian.com/developer/techlib/papers/tn_uid/uidinfo.html on the Symbian site.

The UID's must be specified on the epoc project definition files (.mmp). If you open the project definition file of the cube example (core_examples/graphics/cube/build/symbian/cubecommon.mmp) you can see a line specifying the UID. The first number on the UID line specifies the type of the file being built, and is always the same (0x100039CE) for applications (.app's). The UID must also be specified in the package file (.pkg) you write to make installers. If you decide to build an application information file (.aif) to go with your application, you have to write a resource file (.rss), in which you must also specify the UID. This will associate the aif-file with your application. When you build applications with X-Forge you must state the UID in the code, as well. This is done in the main application class, in function xfcAppPref(), for example:


// Configure the app
void xfcAppPref(XFcAppPrefs &aAppPrefs)
{
    ...
    aAppPrefs.mUID = 0x0F470001;
}

You can see the UID plays a big role, and subsequentially it is also a common source of problems. It's one of the first things you should check if you run into problems.

Making the installer files is briefly explained later in this chapter. Please refer to the Symbian documentation for building application information files, and thus writing the resource files.

Warning

You must ALWAYS make sure that your projects have a unique UID specified. Failure to do so will cause some very cryptic problems.

Installation

Install Visual C++ 6.0 if you haven't already. See 'Getting started -> Desktop Windows', above, for install instructions. Other versions may also work, but they're not verified on the Symbian platform.

You should also install the latest service pack since the Symbian tools will give a warning if you don't have at least service pack 3.

When installing the Symbian tools and SDK's we recommend installing them in a way, that the installation folder looks like it was the root of a drive. This way you are most likely to avoid problems if installing other Symbian SDK's. After the installation you will have two directories added to your PATH environment variable, for example X:\epoc32\gcc\bin;X:\epoc32\tools; If you install other Symbian SDK's specify a different drive letter. In that case you should remove the drive letters from these directories in the PATH variable and point them to the root: \epoc32\gcc\bin;\epoc32\tools;. This way the tools from the right SDK will be used, because you will be building your programs from the command line and thus already be on the correct drive. After the installation you should also have the environment variable EPOCROOT specified. It should point to the directory containing the epoc32 directory, in the above case the root: \.

Series 60 SDK installation

Make a folder called e.g. EpocSDKs and under it a folder Series60. "Subst" the EpocSDKs/Series60 so that the drive points there. From the command line:

subst x: c:\EpocSDKs\Series60

Start the setup program for the Series 60 SDK. When the setup program asks where to install replace both default paths with the root of the newly substed drive e.g. x:\. When the installation is complete you will need to reboot your computer. After each reboot you'll naturally need to "subst" the drive again.

Copy the epoc32 folder from xforge/lib/Symbian/N7650 of the X-Forge distribution on top of the x:\epoc32 folder.

UIQ SDK installation

The installation is similar to that of the Series 60 SDK. Make a folder called e.g. EpocSDKs and under it a folder UIQ. "Subst" the EpocSDKs/UIQ so that the drive points there. From the command line:

subst y: c:\EpocSDKs\UIQ

Start the setup program for the UIQ SDK. When the setup program asks where to install the Kit installer and the corresponding Kit, replace the default path with the root of the newly substed drive e.g. y:\. After each reboot you'll naturally need to "subst" the drive again.

Copy the epoc32 folder from xforge/lib/Symbian/UIQ of the X-Forge distribution on top of the y:\epoc32 folder.

Note

We've had some problems with the UIQ installers along the way. Sometimes the installation would fail because the installer is a Java software, and can be picky of the JRE version. Sometimes the root folder just hasn't been ok for the installer, and we've installed to a temporary directory, and later copied the directory to a "substed" root and modified the environment variables. Sometimes the installer would even delete the directory you are pointing it to. This has happened after the installer has complained with a dialog that the directory is not empty etc., and you've pressed 'Next' anyway. Nothing visible happens in the installer, however.

Note

Nothing prevents you from installing the Symbian SDK to the folder you want to. But if you later want to install other Symbian SDK's, and use them concurrently, you'll have to always edit the environment variables EPOCROOT and PATH for the right SDK to function properly.

Please consult to the installation instructions found in the corresponding SDK packages for additional information.

Working with the Symbian tools

This section briefly describes the tools and procedures that you'll need in building your projects for Symbian. For more extensive information on the tools or file formats, please refer to the Symbian SDK documentation.

Compiling your application

When compiling your own programs for Symbian you need to create two files:

  • A project definition file (.mpp file) that describes a project to be built. This is a file that can be used by the tools to produce make files for any of the supported target environments. It also defines resource files and application information files to be built.
  • A component description file (bld.inf), which lists all the projects in a component, and gives additional build instructions. Usually this file will only specify a single project mmp file.

When you create a new project, you write these files (or typically copy existing similar files and modify them) in a text editor. These project files are used by a program called 'bldmake'. You then run it from the directory where the bld.inf file is located:

bldmake bldfiles

This creates a batch file, abld.bat, which you will be using for the rest of the compiling process.

To build the project run

abld build [architecture] [variant]

Architecture would be 'WINS' for emulator builds and 'ARMI' for device builds (e.g. Nokia 7650 and Sony Ericsson P800). Variant can be either 'UDEB' or 'UREL', meaning debug and release builds. If you leave the architecture and variant away, the project will be built for all valid targets with both release and debug mode. You'll most probably be compiling for the target to test your application, and you'll then run

abld build armi urel

This will create the application executable (.app) compiled for the target device in /epoc32/release/armi/urel/appname.app

Running

abld clean

will clean up executables and temporary object files (equals 'make clean'). To really make sure all the intermediate files (some files that were copied in the build process and individual makefiles) will be erased, use

abld reallyclean

, and use it twice. (Not kidding.)

Note

If your project definition changes you should do a clean up, and must then run bldmake to create the abld.bat again.

There are two important X-Forge libraries you'll need to know about for development with X-Forge:

  • xfcorestatic.lib - the X-Forge core static link library
  • xfutil.lib - a precompiled library for everything under the xfutil folder of the X-Forge distribution

There's also a big bunch of Symbian libraries, you'll have to link against. Please take a look in the examples provided with X-Forge to cover most of them. You'll tell abld.bat to link your application against the libraries in the mpp-file.

Installing your application

With some configurations you are able to directly browse the directory structure on your Symbian device. You can then make a folder appname under /system/apps/ on your Symbian "drive" and copy appname.app in that folder. To this folder you should copy also other files needed by the application, usually zlib.dll and the data files. However, we are encouraging you to start making installation packages from your applications right from the start. That procedure is common to all Symbian platforms, and is something you'll have to do if you plan to release an application.

These packages (.SIS files) are created using an application called 'makesis'. The package creation process is controlled with a configuration file (.pkg). It is a text file describing the files needed in the package and their intended target directories on the target device. Unless explicitly specified, the name of the new installation file will be the same as the package file, but with the .SIS extension. For an example of a simple .pkg-file, please refer to helloworld.pkg in the 'Hello World' engine example. Please note the product id, that is required and different for each platform installer. For Series 60 platforms the package file should state

(0x101F6F88), 0, 0, 0, {"Series60ProductID"}

and for Sony Ericsson P800 and P802 (UIQ)

(0x101F80BE), 1, 0, 0, {"SonyEricssonP80xPlatformProductID"}

Once you have created the .pkg-file, you can create the installation package by running

makesis appname.pkg

This will create the installer (named appname.SIS by default), which can be transferred to the target device. For example on Nokia 7650, the easiest way to do this is to send it over BlueTooth.

For more information on installing / transferring the .SIS-file to the device, please refer to the device documentation.

X-Forge Examples

This section describes building two X-Forge examples for the Series 60.

Every example has a Symbian folder that includes the required Symbian makefiles to compile them. The makefiles have a part common to all Symbian platforms, and then in a sub-folder the SDK specific project files, Series60 in this case. The common part is always included from them.

Example 1 - HelloWorld

This procedure describes compiling the HelloWorld example for a Series 60 phone.

The engine examples need additional data files to function properly. There are prebuilt installer package files to take care of them, but it's important to notice this fact.

Make a new folder on the root of your Symbian development drive and copy the X-Forge distribution there. Change into the folder \engine_examples\HelloWorld\build\symbian\Series60

Type

bldmake bldfiles

This will create the abld.bat file. Now type

abld build armi urel

This will do the actual compiling of the application and create a release version for ARM processors. After the build is over your application can be found in /epoc32/release/armi/urel/helloworld.app

In the current directory there should also be a package file helloworld.pkg. Run the installer generator:

makesis helloworld.pkg

You should now have helloworld.SIS ready to be installed and run on the device. Carry out the installation according to the instructions in your device documentation.

Example 2 - Cube Example

This procedure describes compiling the Cube Example for the Series 60 emulator.

If you haven't already, make a new folder on the root of your Symbian development drive and copy the X-Forge distribution there. Change into the folder core_examples/graphics/cube/build/symbian/Series60

Type

bldmake bldfiles

This will create the abld.bat file. Now type

abld build wins udeb

This will do the actual compiling of the application and create a unicode debug version, that will work with the emulator. After the build is over your application can be found in the folder epoc32/release/wins/udeb/z/system/apps/cube

Now run the emulator from epoc32/release/wins/udeb/epoc.exe. Click on the cube icon and the application should run. You should note that the emulator limits the maximum fps count somewhere close to ten, which is not the case when running on an actual device. Where your application appears varies under different flavours of Symbian OS. With Nokia 7650 your applications will appear under the 'Other' folder of the applications screen.

Notice that some of the core examples need additional data files to run, as well. You must copy them by hand from the core_examples/data folder into the epoc32/wins/c/system/apps/appname folder, appname being the name of the application. You must create this folder if it doesn't exist.

Note

Symbian core has been changed to disable backlight turning off after a few seconds of keyboard inactivity. In later versions there might be an interface to control this state.

Note

When pressing buttons on dialog boxes the Symbian event handling sometimes sends the control up event of the keypress to the application that receives focus after the dialog box. This may cause undesirable effects if game pause mode is set off with control up event. Resuming game should in this case be mapped to control down event.

Troubleshooting

Q: Why is my application not visible on the emulator ?

A: Check that your application really has appeared under epoc32/release/wins... folder and your myapp.app is under a folder called myapp. If it is there then you have probably got a case of a bad UID or you are using the same UID for two applications. In the latter case only one of the two applications will appear on the emulator.

Q: Why does my application say 'System Error' on start-up ?

A: You are missing a DLL, bitmap or some other resource file. Make sure you have all the required files included in the installation.

PocketPC

Overview

This chapter walks through the steps of getting your program to compile on the PocketPC platform. The platform-independent getting started chapter continues from where this document ends.

Note

X-Forge mainly targets PocketPC2000 instead of PocketPC2002 in order to support the widest possible range of PocketPC devices. PocketPC2002 mainly included UI updates and desktop synchronization fixes, neither of which affect X-Forge in any way. PocketPC2000 applications run in PocketPC2002, but not necessarily vice versa.

Only negative side effect this has is that when doing remote debugging with a PocketPC2002 device, you will be prompted every time whether you wish to continue, since the platform ids do not match. The remote debugging will work despite of this warning.

X-Forge 1.1 onwards includes PocketPC2002 and Smartphone2002 libraries as well as normal PocketPC libraries. There is no gain for using PocketPC2002 libraries over PocketPC ones, apart from getting rid of the above warning message.

Installation

Install the Microsoft eMbedded Visual Studio (available from http://www.microsoft.com/mobile/downloads/emvt30.asp as a free download as of this writing).

After this you have to set up the include and library directories for eVC. This can be done by either configuring eVC's directories or you may opt to add these paths to every project separately.

If you want to set up the directories in eVC, go to Tools / Options / Directories. Then:

1) Make sure the Platform reads "Pocket PC" (and not, for 
   example, "Pocket PC 2002")
2) Make sure 'include files' is visible
3) add the path to the include root directory 
   (for example \xforge\include)
4) Go through all the CPUs in the list, add the same include
   path to all of them.

Then, change from 'include files' to 'library files' and add the library file paths to all platforms as well. You should set the ARM CPU library path to include xforge\lib\wince\arm, x86em CPU path to include xforge\lib\wince\x86em, etc.

If you're developing for PocketPC2002 or SmartPhone 2002, you will need to add the same paths for all of the CPUs in those platforms as well.

If you want to set up the directories in each project separately instead of the above, after having created a project open it and go to Project / Settings / c/c++ / preprocessor, then select, in the 'settings for' pulldown on the left side of the dialog (above the tree view) 'all configurations'. After this, add the X-Forge include path to the 'additional include directories' field.

Then go to Link / Input and add the X-Forge library path to the 'additional library paths' field. You will still have to set the library path separately for each CPU you wish to target (most likely x86em and ARM).

First Program

Now you can start a new project. Make sure you select 'pocket pc application' (and not, for example, 'pocket pc 2002 application').

I chose to call this project "tutorial". Select 'empty project' from the wizard, then click on finish. Change to file view from the bottom left side of the screen, click open the 'tutorial files', right-click on 'source files' and add a new file. Type app.cpp in the file dialog, and say yes when asked whether to add a non-existent file. Now click the app.cpp open (it will ask again whether to create a new file).

Here's the source code for the minimal program:


#include <xforge.h>

void xfcAppPref(XFcAppPrefs &aAppPrefs)
{
  aAppPrefs.mTotalMemoryLimit = (INT32)(1024 * 1024 * 0.5);
  aAppPrefs.mResourceMemoryLimit = (INT32)(1024 * 1024 * 0.5);
  aAppPrefs.mMinimumExtraMemory = (INT32)(1024 * 128);
  aAppPrefs.mUID = 0x0F470001;
}

INT32 xfcAppInit() 
{
  xfcUseDefaults();
  return 0;
}

(This source code can also be found at core_examples/tutorial/e1_minimal.cpp).

If you try to compile you will get a error message starting with: "Please define X-Forge Core platform in order to compile." Since some compilers are used to produce code for several different platforms (gcc and visual studio for instance) we cannot automatically detect which platform you wish to build for. Thus, we need to specify the platform (and some other bits) in the compile options.

Go to Project / Settings, in "settings for" select 'all configurations', go to the 'c/c++' tab, and add to the end of 'preprocessor definitions' the following: ",XFC_PLATFORM_WINCE" (without the quotes).

After this go to the 'link' tab, and add xfcored.lib as the FIRST library in the 'object/library modules' list. Also add xfutild.lib, gx.lib, winsock.lib and zlib.lib and make sure that aygshell.lib is there as well. (For release build you should use xfcore.lib and xfutil.lib instead of the 'd' versions).

And while we're changing the settings, go to 'Debug' tab and change the 'Download directory' to "\my documents" (it should say "\windows\start menu" by default).

Now if you try to compile you should get several warnings that certain header files are missing (e32base.h for example). This happens when eVC is building the automatic precompiled header set, and unfortunately tries to find files that it should not (those includes have been conditionally compiled out). You can safely ignore these warnings. The initial build may take a while as eVC is looking for files, so if your PC seems to have hung, be patient.

Tip

If you wish to get rid of the "missing header file" warnings, you can create dummy header files somewhere in the include path. These files must have a non-zero length, or otherwise the compiler will give an error.

Apart from the above your program should compile fine. Right above the file tree view and text editor you should have a toolbar with the build configuration. If it is not visible, just right-click on any toolbar and make sure 'WCE configuration' is checked. Make sure the bar says, from left to right: your project name, "Pocket PC", "Win32 (WCE x86em) Debug", "Pocket PC Emulation". Press F7 to compile.

If you press F5 to run now, the emulator pops up and you get a dialog box saying "unable to locate dll". Please note that if you try to execute the program (control-F5) the emulator will not say anything, but doesn't start the program either.

Note

'Run' means to run the application with debugger enabled, while 'execute' means to run the application on its own. If you try to 'run' an application with no debug information the IDE will give you a warning.

In order to run your program, the target machine must contain gx.dll and zlib.dll, either in the same directory as the application or in the Windows directory. These files can be found in the library directory in the X-Forge distribution (for instance, for the PocketPC emulator, the dlls are in xforge\library\wince\x86em). Emulator platforms (x86, x86em) may not include the gx.dll file, since the emulators do not support the GX interface.

Note

PocketPC emulator uses x86em libraries while PocketPC2002/Smartphone2002 emulators use x86 libraries.

Now we want to know where the executable was copied. As you remember we set the 'download directory' in Project / Settings / Debug tab to \my documents. This is the directory on the emulator. The emulator itself is by default located at

X:\Windows CE Tools\wce300\MS Pocket PC\emulation\palm300

Copy the zlib.dll for x86em into the \my documents directory of the emulator. (This file could be copied into the \Windows directory as well, or the proper directory for WinCE programs, \program files\yourprogramdir, but we will do things as simply as possible for this time. When copying the DLLs onto an actual device, remember to copy the gx.dll as well).

If, when you're copying the DLLs, you notice that the executable is not in the download directory, you can check whether the download directory is correct by checking Project / Settings / Debug tab.

If you try to execute the program (control-F5 or F5 if you want to run with the debugger) after this you should get an application that does nothing and cannot be exited from. You can shut down the emulator from the round button below the screen.

Please continue to the platform independent 'getting started' chapter next, which goes through the program, and gets you into the X-Forge philosophy.

Tapwave Zodiac

Overview

This section introduces the Tapwave Zodiac platform and its specific differences for X-Forge developers.

The Zodiac uses a modified version of Palm OS 5. These modifications enable convenient use of ARM code, large memory allocations and other changes that make it better suited for high-end mobile gaming. Using X-Forge you don't need to know about Palm programming, although it helps if you wish to use some of the functionality in the device that are not exposed by the X-Forge APIs.

Note

At the time of writing, the development tools are still much under development. Familiarity with the codewarrior environment is assumed, and many of the paths and library names are subject to change. ARMlets are going away and will be replaced by Tapwave Native Applications (TNAs) or PACE Native Objects (PNOs).

Installation

You will need Codewarrior 9.2 for Palm OS from Metrowerks, possibly with Tapwave extensions installed, and the Tapwave SDK available from http://www.tapwave.com/developer/.

Using Tapwave Tools

Contents of a Tapwave Native Application project

A Tapwave Native Application (TNA) project consists of a small Dragonball (68k) code side and an ARM code side.

Dragonball Files

The Dragonball side of a TNA consists of the following files:

ARMC0001.bin - the ARM code block, generated by the compiler.

Application.cpp - the Dragonball stub, which mainly locates the ARM code and jumps to it. It may also contain checks to make sure the application can run on the current device, and display error message if not. (Right now it shouldn't be a problem as most TNAs are too large to fit into older Palm devices, but some future Palm device might be able to support the file sizes, but not the Tapwave APIs).

PalmOSRuntime*.lib - Palm Dragonball runtime library.

Application.rcp - PRC file resource script. Contains the application category, icons, and palmsim support resources.

*.bin - Any resources required by the application (such as pxFs0000.bin).

ARM files

The ARM side of the application consists of the following files:

ARMlet.cpp - This is ARM counterpart to Application.cpp, and takes care of relocation, memory management etc. In general you shouldn't need to touch the contents of this file.

Runtime_PNO.a - Palm ARM runtime library.

MSL_C_PNO.a - Standard C library, required by X-Forge.

xfcore.a - X-Forge Core library.

xfutil.a - X-Forge Util library.

*.cpp - Any project source files.

Important Compile Options

The TNA project has two build targets, PACE native object (PNO) and the application itself.

Application Project Settings

In the 'Palm OS 68K Target' tab, you can set the file name of the target application, plus application name ('tAIN') as it will be shown on the device.

In the 'PRC File Settings' there's a 'Creator' field. This field has to contain a creator id that has to be unique for all applications (much like the unique id's on Symbian platforms). You can register creator IDs at PalmSource's web site at http://dev.palmos.com/creatorid/. Thus tab also contains 'DB name' field, which should be set to something sensible (such as your application name). All database names must also be unique, and Palmsource recommends postfixing the database name with the creator code, for instance "example-XFe1".

PNO Project Settings

In the 'PACE Native Object Target' tab, make sure the 'Generate relocation lists' checkbox is checked. Without this, virtual functions will not work. Also, make sure the Instruction Set is set to "ARM".

In 'Access Paths', system paths should be, in this order: Tapwave's SDK:s include directory, ARM_EABI_Support, X-Forge's include directory and finally the project's own include directory (if any).

Finally, the xfcore.a should be first in the link order for the memory management to work.

Tapwave Zodiac differences

The Tapwave Zodiac platform uses a modified Palm operating system. The main differences on this platform compared to other X-Forge platforms are:

Threads

Applications cannot use threads. Trying to launch threads will fail. This also means that using the X-Forge Engine asyncLoad() call will fail; use load() instead. The operating system itself, however, does use threads, for instance for the audio.

Filesystem

See 'Files and pxFs' chapter, below.

Analog controller

The Zodiac has an analog controller, which is mapped to onJoystickMoved call on XFcInput. Moving the controller will also send normal digital joystick calls, but it is recommended that applications use the analog controller, as it has a much better feel to it.

2d hardware acceleration

While the Zodiac device has some 2d acceleration features, X-Forge does not currently abstract its use. See 'Graphics Output', below.

Files and pxFs

Traditionally, a Palm device does not contain any 'internal volume' where files could be stored, but uses a database instead. However, one of the Tapwave extensions to the Palm operating system is such a volume. For an X-Forge application the internal volume looks just the same as the filesystem on a memory card.

All launchable .prc files should be located in the directory /PALM/launcher/ on a memory card. All files associated to a program should be located in /PALM/programs/databasename-creatorcode/. The database name and creator code were set in the 'PRC File Settings' in Codewarrior. As an example, if the application database name was 'example' and the creator code was 'XFe1', the proper directory would be /PALM/programs/example-XFe1/. If the database name is already postfixed with the creatorcode, that is not duplicated (ie. the directory will not become example-XFe1-XFe1).

X-Forge will automatically open files in the proper place. When opening files, they are first looked for on the same volume where the application was launched, and then on all volumes in the device. To override this behavior, you can prefix the filename with //. For instance, to find files in the /foo directory, use ///foo/. To find a file in the first slot, you can use //a:/foo. For second slot, use b:, for the internal volume, use z:, and finally, to open files in the pxFs, use x:. If you don't follow the : character with a / character, the application's proper storage directory is used (for instance, //a:foo.dat would try open the file /PALM/programs/example-XFe1/foo.dat on any volume in the first memory card slot).

As an alternative to storing data on the volumes, you can also use pxFs, or Palm X-Forge Filesystem. It's a read-only virtual filesystem built on top of the Palm database. The good side of using pxFs is that you get a single self-contained .prc file that contains all the data for your application. The bad side is that your .prc file might become rather large, and might not fit into users' devices, while when having the data files stored externally the user can leave the data files on a memory card.

Much like when building CFL files, the pxFs files are built with a command-line tool called palmxfs.

Create a text file with one filename per line, and give this text file as a parameter to palmxfs. You should then have one or more files named pxFs????.bin. Add these .bin files to your project and your application can then use the files as if they were on a ROM card on a normal filesystem. (Yes, you can put CFLs inside the pxFs).

Note

Tapwave recommends storing data files externally, and to save game state in the application preferences database.

X-Forge doesn't currently abstract database access, and Fathammer recommends using files normally for game state and configuration storage for maximum portability.

Graphics Output

X-Forge doesn't have abstraction for the 2d accelerator. The application can, however, use the 2d accelerator directly with the TwGfx library by overriding the normal screen update. This can be done by overriding the updateScreen() callback in XFcRenderer class.

The updateScreen call receives a pointer. Under the Tapwave Zodiac platform, the pointer points at the following structure:

struct xfcUpdateScreenInfo
{
    TwGfxSurfaceType *mBackSurface;
    TwGfxSurfaceType *mScreenSurface;
    TwGfxType *mTwGfx;    
};

Normal screen update (currently) follows the following pattern:

1. Transfer secondary framebuffer to mBackSurface using TwGfxWriteSurface()

2. Bitblt the mBackSurface to mScreenSurface (TwGfxBitBlt)

It is possible to replace the standard screen update and use the 2d acceleration to draw sprites etc.

Please note that the above structure and screen update pattern may change as the Zodiac hardware evolves.

Additionally, there are two global functions, specified as follows:

extern "C" void xfcTapwaveSetOutBlitAlpha(INT32 aValue);
extern "C" void xfcTapwaveSetVBlankWait(INT32 aValue);

The xfcTapwaveSetOutBlitAlpha() function can be used to create a "motion blur" effect in hardware. The aValue can range from 0 to 255. Set it to 255 or above to disable the alpha blitting. A value of 127 or 192 is pretty good for the motion blur effect.

The xfcTapwaveSetVBlankWait() function can be used to force vertical blank waiting before blitting out. If you're experiencing severe tearing, you can use this function to make X-Forge wait until the next vertical blank before updating the screen.

You can also use graffiti with X-Forge applications. This is achieved by setting X-Forge to nonexclusive mode, and then instructing the operating system to show graffiti. It is recommended that you also disable the screen rotation feature, as using it causes some glitches. You might also want to disable the 'hide graffiti' feature.

XFcExclusiveModeSettings settings;
XFcCore::setExclusiveMode(0,settings); // set non-exclusive mode
PINSetInputAreaState(pinInputAreaShow);     // show graffiti
SysSetOrientationTriggerState(sysOrientationTriggerDisabled);

You can call XFcCore::setExclusiveMode(0,settings) repeatedly to get the currently active screen region. To get back to exclusive mode, do the following:

XFcExclusiveModeSettings settings;
XFcCore::setExclusiveMode(1,settings); // set exclusive mode
SysSetOrientationTriggerState(sysOrientationTriggerEnabled);
PINSetInputAreaState(pinInputAreaHide);     // Hide graffiti
StatHide();                                 // Hide status bar

Palmsim Notes

Palmsim works by running Dragonball code under emulation, much like the actual device does. It doesn't, however, emulate ARM code, but instead all PNO code is compiled as a normal x86 DLL.

In Tapwave applications, the Application.rcp contains a resource with the code "SIMC" (SIMulator Code) which is used to figure out which dll is related to this PRC.

In order to build X-Forge applications for palmsim, you'll have to define the following preprocessor directives (in vc6, go to project, settings, c/c++, preprocessor directives): ,__PALMOS_ARMLET__,XFC_PLATFORM_PALM,XFC_FORCEDEVICE_TAPWAVE,USE_TAPWAVE_NEW=0

Please refer to the Palm documentation on further use of the palmsim.

Note

Fathammer recommends using the X-Forge 'desktop windows' platform instead of the palmsim for most of the development.

Troubleshooting

Known issues of note

Some features of the Tapwave port may be unfinished or untested.

- All file access is case sensitive. This includes directory names.
  Some memory card writers actually write filenames in all caps although
  they are shown as mixed case.
- If a file is found on several volumes (memory cards, internal storage)
  it will be listed several times with filefind.
- Filefind only iterates through the proper storage directories 
  (eg. example-pxFs)
- File rename and remove, as well as directory remove do not care about
  the 'drive letters' and will act on the first file/directory found.
- Directory create will try to create the directory on all volumes.
- Network code is not stable.  
- Most examples have not been made to work with the Tapwave device 
  specifically; features such as the screen size and analog joystick 
  are not used. Also, the lack of threads may cause some examples to 
  work differently.
- Examples do not have ready pxFs files. Copy example data to the 
  proper directory on a memory card before running the examples, or build
  the pxFs files and add their .bin files to the projects before build.
- The Tapwave port uses slightly more memory from the memory pool than
  the desktop windows platform, due to file IO caching.
- Palmsim projects have seen minimal testing.  

Debugging

If you develop on a memory card, and your application crashes, the device cannot remove the temporary copy from its memory and thus a copy is left on the device. Remember to delete it from the device, or otherwise the device may not use the version you have on the memory card.

One way of locating a crash address is to insert debug print lines in the code. An easy way to do this is to declare the following extern;

extern "C" void xfcPalmDebugprint(const char *aString);

Calling this function will print some text on screen immediately. (Internally this call uses WinPaintChars(), but using xfcPalmDebugprint saves you from including any Palm headers).

Also remember that you can use XFcCore::systemPanic() to make sure that a certain piece of code gets executed.

Please continue to the platform independent 'getting started' chapter next, which goes through the program, and gets you into the X-Forge philosophy.

Linux

The Linux Platform Package is available separately. Contact your X-Forge contact person or support for more information.