Previous Section
Index
Next Section

Starting Cross Platform Development

This topic will attempt to give you insight into the process of developing for the iPAQ. This includes sample commands and configurations which will probably be useful if you want to develop your own software or experiment with the internals of the Software Reference Platform.


Introduction to the Development Process

Developing software on the iPAQ is quite easy with the QNX software development tool chain. If you have installed the QNX Realtime Platform or purchased the QNX development environment for Microsoft Windows, you will likely use PhAB, the Photon Application Builder. If you have purchased the QNX development environment for Sun Solaris, at the time of this release, you will not have access to PhAB. As a result, we strongly recommend that you install the QNX Realtime Platform (QNX RTP) for the latest version of our graphical development environment. The remainder of this document will assume you have installed QNX RTP.

One of major benefits of the QNX RTP is the notion of self hosted development. What this means is that you can write code and test it on your PC before moving it to an embedded device. Of course, there are many circumstances where you may need to access the hardware or system software on your embedded device. In these instances, you will need to compile your software specifically for the processor of your remote device, potentially transfer the software to the device and then execute the code. This process is known as cross platform development.

This document will start you on your way for both self hosted and cross platform development, targeting the iPAQ's hardware. After you have finished with this document, please continue reading the iPAQ application developer guide to learn how properly write and install your software.

Part 1: Installing armle Packages

IMPORTANT: If the BSP and Reference Platform do not automatically install the armle development packages, you will need to download them, manually. The QNX Packaging architecture should resolve dependencies automatically, but just in case...

If you are working in the Windows or Solaris development environments, these packages are already installed on you PC. Otherwise you'll need to launch the Package Installer and connect to the WWW Repository. If you have a burned QNX RTP ISO image you may connect to the CD Repository with your QNX CD insert in the CD-ROM drive.

Once connected, you will need to change the Package Installer's repository view to show armle packages. Host packages have binaries which run on an armle device, like the iPAQ. Target packages contain files needed to develop code for an armle device.
Install the following packages, or the most up to date equivalent of these packages:

Package Installer: Installing armle Packages

Part 2: Starting a Project

When you begin a new iPAQ project, a cross platform project directory must be created. Within this directory will be sub directories and makefiles needed to build for your project's target. In the case of the iPAQ, your target is armle: the Intel Strong ARM processor, Little Endian. How you go about creating this project directory depends on the type of application you are developing.

Note: We assume that you know how to do basic editing of text files through the course of this documentation. The QNX Realtime Platform ships with vi and a graphical editor, ped. If you are more familiar with contemporary UNIX editors, we recommend downloading Jed or Vim. Vim is a much improved replacement for vi which includes syntax highlighting and remote shell commands. Jed is a lightweight clone of Emacs with almost all of its features including syntax highlighting, auto completion, remote shell commands and tracking of compiler errors. Both editors support graphical versions, xjed requires the XPhoton server packages to be installed.

Graphical Applications

If you are developing graphical applications, you will be using the Photon Application Builder (PhAB). Your project directory will be created automatically by PhAB as will a number of other sub directories, data files and automatically generated code.

1. Your first task is to create and save your project. This will create a directory which will hold all of your source code, object files and executables. We recommend that you save frequently to avoid losing your work. This release of PhAB is relatively stable, but there are still crashing bugs which we're aggressively working on fixing.

2. Once you have saved your project, you can activate the Build & Run Dialog and tell PhAB about your target processors. Generate a target platform for both x86 and armle. This will let you test your programs on your PC and move them over to the iPAQ when you're ready.

Build & Run Dialog
Generate: <add new platform>
3. Now that you have told PhAB what platforms you developing on, you can return to the Build & Run dialog and generate for each target. The first time you click Generate, PhAB will create the structure within your project. Subsequently, it will generate any user interface databases, automatically create code, header files and function stubs, as needed.

4. Once you have generated for the first time, the following directory structure is created:
   
project  The project directory.
project/wgt  The user interface (widget) database directory.
project/src  The source directory, where your source code should go.
project/src/gcc_ntox86  The x86 object directory, for your .o files and application.
project/src/gcc_armle  The armle object directory, for your .o files and application.


You now have a basic project set up. Hopefully you have a general understanding of why you did these steps and what resulted. You can now begin developing graphical applications for your iPAQ.

Non Graphical Applications

If you are developing a non graphical application such as resource manager, background process, or driver, you probably won't be using PhAB. Instead, you'll want to create a directory structure using the QNX Makefile architecture. There are many features and benefits to using QNX's recursive Makefiles; this section presents a brief tutorial on creating a basic project. We encourage you to read more out about our Makefile and project environment in our standard documentation.

QNX development projects which are not generated by PhAB build their applications in a more generic manner.  There are many details, options and features but what we will cover here are the basics of building a single binary.

Following in the tradition of all good samples let's begin with the basics of "Hello World":

Make a directory for your project: $HOME/cvs/hello
Inside the project directory make two files: hello.c and hello.use

Create the hello.use file with the text:

%C - Sample hello world program.

Create the hello.c file with the text:

#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>

int main( void )
{
    printf( "Hello World\n" );
    return EXIT_SUCCESS;
}

To allow for the development of x86, before any other processors:

Use this command to create initial makefiles, x86 development files: addvariant -i CPU x86 o
Use this command to compile for x86: CPULIST=x86 make

Take a moment to look in your project directory. Notice the two files it created: common.mk and Makefile.


To allow development for iPAQ after the inital makefiles are created:

Let's assume we have already run addvarient with a -i; the initial makefiles are already present.
Use this command to create the armle development files: addvariant arm le
Use this command to compile for the iPAQ: CPULIST=arm make

As a result of these basic steps, you may use the CPULIST environment variable to target different processors. As we mentioned earlier, many other cross platform development features exist in using the common.mk and addvarient files and utilities. We encourage you to read more about this in our standard documentation.

Part 3: Basic User Interface Guidelines


Users benefit from consistency in a graphical environment. The iPAQ Reference Platform is far from a complete environment, but still benefits from UI documentation. Here are few brief guidelines to make a basic iPAQ application.
 
  1. Design all your graphical application using the Photon Application Builder (PhAB). In the future it will be able to automate binding to custom functions to simplify your application development. Future user interface guides will assume this is your primary development tool.
  2. In this release, the window may resize vertically, be sure to anchor your widget such that the user interface accommodates the change in size. Start a basic project out with a window the size 240x300.
  3. Change your window render flags to have: Ph_WM_RENDER_BORDER, Ph_WM_RENDER_TITLE, Ph_WM_RENDER_CLOSE, and optionally Ph_WM_RENDER_MAX. The final flag will enable the title max to be collapsed, maximizing your application. In the future may of these window flags will enable controls which may rotate your display, show about dialog boxes, or other features. Until these are supported it is important to turn these flags off - as unpredictable things may happen.
  4. Be sure to change the border color of the background panel to black. This will merge with the bottom status bar creating a distinct two pixel separation.
    5. Start your projects by adding a pane with the following basic flags: Pt_FLAT_FILL, Pt_TOP_BEVEL and Pt_BOTTOM_OUTLINE. If you want something which looks like a toolbar, stack another pane on top of this one with the following basic flags: Pt_FLAT_FILL, Pt_TOP_BEVEL_BOTTOM_BEVEL. Make sure both of these have a Border Contrast of 50. Without this value, the bevelling may be too light to be seen on the bright iPAQ display. Yellow fill color, used by the tab is: R: 246, G: 240, B: 226. In the future, the tab will adopt the color of the window, but at this time it doesn't. Try and select a desaturated pastel for your panel fill colors.
    If you look closely, the corners of many applications are rounded by adding a labels with small black fills. These are just drawn in the labels, with transparency.
  5. Be sure to use TextFont 08 to maximize screen real estate.
  6. Giving focus to text fields will automatically cause the input area to appear. If you have a text field at the bottom of your application, place your widgets into a Scroll Container, with no vertical scrolling and horizontal scrolling on auto. This will allow users to see your application content at all times.
  7. The iPAQ environment is modal, applications should save state. This means that when your application exits, save your data in your application's directory. When you application starts again, reload your save data.
These are just initial notes on building an iPAQ application. As this reference platform expands, detailed design notes will be included with each new feature. Consider this a practice in following some basic standards and use it as guideline for learning some of the basics within the QNX Photon Application Builder (PhAB).
 
 
Previous Section
Index
Next Section