TN005 - How to write Cocoa based programs for an Embedded LinuxPDA on the Mac

This is a translation of http://www.macentwicklerwelt.net/index.php?title=CocoaOnLinux which is licenced under GFDL.

About this tutorial

This tutorial describes how to make Cocoa programs run on a LinuxPDA (e.g. Sharp Zaurus).

The requirements

• Macintosh with Xcode (1.5 or 2.x)
• Sharp Zaurus (with Sharp ROM) with USB connection
• AJZaurusUSB driver (see below)
• Cross compiler Zaurus-X-gcc (see below)
• openssh, gdb for Zaurus (see below)
• Run time system myPDA for Zaurus (see below)

Installation

USB driver on the Mac

 

Firstly, one needs a USB driver for the Mac which gives access to the Sharp Zaurus. Just load and install the the USB driver AJZaurusUSB (http://www.lucid cake.net/osx zaurus usb/index de.html).

 

Note: On MacOS X 10.3.5 and later, there is a conflict with a driver provided by Apple, so that the Mac shows a Kernel Panic if one attaches the Zaurus before the newest driver (0.28 or later) is installed.

 

The driver provides a new network interface (pseudo Ethernet). To enable, you have just to enter an IP address in the network Settings. So, open the Network Settings, select the new interface (usually called Ethernet en2 or similarly) and start configuration. Please make sure that the Zaurus is attached and switched on!

 

Type in the address 192.168.129.1.

 

Test the access via the terminal

 

Please do the following:

1) open Terminal

2) enter ping 192.168.129.201

3) as a result, the Zaurus should answer

 

Access to files of the Zaurus via SMB

 

The Sharp Zaurus provides (starting from Sharp ROM 3.10 and/or 1.2) an integrated Samba server, which can be addressed directly from the Finder. To use it, select in the menu "Go to Server...". Then, type the following address:

 

smb://ZAURUS/

 

The fields Worksgroup and Password etc. can remain empty. After confirming the dialogs by pressing Return, the files of the Zaurus get mounted on the Desktop.

Installation of the Cross Compiler on the Mac

First of all, Xcode 1.5 or later should already be installed. Then, install the compiler package (download from http://www.dsitri.de/wiki.php?page=Zaurus-x-gcc).

 

Note: this package is over 40MByte!

 

The package can be simply installed by double-clicking. It is installed into Xcode at /Developer/Zaurus-x-gcc.

 

Contents of the package:

• gcc 2.95.3 as cross compiler toolchain for Linux/ARM
• libc 2.2.2 (other gcc and libc versions are not compatible with the Linux core used by Sharp!)
• Translation tool for Interface Builder files (nib2mib)
• cross-makefile to integrate most easily into Xcode various further libraries, e.g. libX11
• mySTEP: the "Cocoa" libraries libFoundation, libAppkit, libPreferencePane, libMenuExtra etc.

Installation of open-ssh on the Zaurus

The compiler package also contains openssh-server 3.6.1p1 arm.ipk (in the ipk format) for the Zaurus. Please copy this .ipk file from the compiler package onto the Zaurus into the directory "Main Memory/Install Files". This is done best over SMB as described above. Alternatively you can do that with help of a memory card. Then, select "Add/Remove software" on the Zaurus in the Settings Tab and install the openssh-server package.

 

In a Terminal window of the Mac please type:

 

ssh -2 root@192.168.129.201

 

to gain access to a Shell on the LinuxPDA.

 

The first call raises a question for a SSH session key. Here you can simply enter "yes". If other error messages show up, it usually helps to delete $HOME/.ssh/known hosts.

 

Now, the door for embedded development is open: you can copy files on the LinuxPDA and remotely launch programs.

Installation of gdb on the Zaurus

For practical work it is recommended to install gdb on the Zaurus (and the library ncurses-5 that is needed for it). This works exactly the same as described for the openssh server.

Installation of the run time system on the Zaurus

So that you can finally run Cocoa programs on the Zaurus, the necessary Shared Libraries must be present as well. And as one would like to use the display and the touchscreen, a graphical screen server (X11) must be present.

 

Both are available as a complete package for download at http://www.quantum-step.com/wiki.php?page=QuantumSTEP-Zaurus-Edition. This package contains two files (in Install On Zaurus). Please copy both (through SMB or a memory card) to the Zaurus and install through Add/Remove software.

 

This package tries to resemble the runtime-environment of a Mac with MacOS X and Cocoa as good as possible and therefore installs on the Zaurus:

• X11-Server with some touchscreen modifications (resembles Quartz)
• Window-Manager
• libobjc - for Objective-C
• "Cocoa"-Libraries: libFoundation, libAppKit, libGdo, libMib, libPrefPanes, libMenuExtra, libAddressBook
• libX11, libffcall, libtiff, libungif, libjpeg, libpng
• gdomap is a daemon for Distributed Objects
• Tools: open, defaults, debug

Sample program

Create project

Start with creating a new Cocoa project in Xcode. You can either use a simple application project or a NSDocument based template, depending on your intentions. For the example, we use a simple Cocoa application project.

Interface design

Now, we use Interface builder to add a new window to the Main.nib file. Add some elements like buttons or static text as you like.

Compile fort he Macintosh and test

Do a Build&Run on the Mac. Fix any bugs that arise.

Run the project through the Cross compiler

This does not need much preparation. Most steps are encapsulated in a special shell script, the cross-makefile.

 

Firstly, select the Target for your application. Then add a new Shell Script Build Phase through the menu "Project/New Build Phase/New Shell Script Build Phase". Then, select this (open the grey disclosure triangle of the Program Target and show Information).

 

Copy this code into the shell script:

 

export SOURCES=*.m                  # all source codes

export LIBS=                        # add any additional -lAddressBook etc.

export STRIP MacOS=false            # set to true if you want a Linux-ARM only bundle export

INSTALL=true                        # true will try to install on the Zaurus (using ssh)

export INSTALL PATH=/Applications   # override INSTALL PATH for MacOS X for the Zaurus

export RUN=true                     # true will try to run with mySTEP/myPDA on the Zaurus and X11

                                    # on MacOS (using ssh through USB with address 192.168.129.201)

/usr/bin/make -f $SYSTEM DEVELOPER DIR/Zaurus-X-gcc/SDKs/mySTEP.sdk/usr/mySTEP/etc/cross-makefile $ACTION

 

That’s it!

 

If you now build the project, this creates the initial application bundle for MacOS X. Then, it runs all sources (because *.m is specified) through the cross compiler. If this is successful, additional libraries are linked to the code (none in this example). The final executable is then copied into the Application bundle.

 

Then, it translates any interface builder files.

 

Finally, the application bundle is copied to the Zaurus (because INSTALL=true) into the directory /home/myPDA/Applications and launched immediately (RUN=true).

 

This requires that you have the Apple X11 server running on the Mac and has the result that the application runs on the Zaurus while redirecting its user interface to the Mac to ease development and debugging.

Running programs on the Zaurus, operate on Apple X11

As described before, the cross-makefile automatically runs the compiled application and redirects the output to the Mac (through Apple X11). This works as follows:

 

1. the variable $DISPLAY is set appropriately
2. $PATH and $LD LIBRARY PATH are set appropriately
3. xhost + is executed so that the connection is not rejected by the X11-Server.

 

It is not always reasonable or intended (e.g. for debugging the Mac version first) to automatically run the application. Just set RUN=false in the shell script build phase.

 

For extended debugging, open an ssh connection to the Zaurus as described above. Type “qsx” into the Shell that runs on the Zaurus. This command also initializes $DISPLAY, $PATH and $LD LIBRARY PATH so that the user interface is redirected to the Mac.

 

Now, you can launch applications manually. To support that, the “open” command is also provided. Like on the Mac you can type ”open -a Application” or “open File.ext”. The open tool searches for application bundles and launches the best fitting (association is based on the Info.plist records like on the Mac).

 

A variant is the script “qssh“ that sets $DISPLAY to “:0.0“, which requires a local X server to run on the Zaurus. This is very useful when debugging applications while the QuantumSTEP system has been launched on the Zaurus.

Tip for Debugging

Programs usually don’t run immediately. Although you can find many bugs by Exceptions or you can identify them by using NSLog(), but sometimes you get a segment-fault or an illegal instruction. In that case, gdb (GNU debugger) is asked for.

 

As the first step you connect to the Zaurus and start “qsx”. Then, you change into the directory where the application bundle (.app) is stored. This is usually /home/myPDA/Applications or /home/myPDA/Users/zaurus/Applications.

 

Now, you start the debugging script, passing the name of the application to debug: e.g. “debug myApp.app” (the .app is optional).

 

Within gdb, you can launch the program with the “run” command and as usual you can control the user interface on the Mac X11-Server until the application crash occurs.

 

Then, you can look into the Stack trace by the “bt” command to see the calling order of nested methods. This is in most cases the required hint where you did dereference a NULL pointer or something similar.

Advanced Aspects

Unfortunately, many advanced topics can’t be described in depth in this tutorial. These are e.g.

• Creation of loadable NSBundles
• Creation of Command-Line Tools using Cocoa/Objective-C (like e.g. the command “open”)
• User interface design for a small screen (320x240) and operation by Touch Screen
• Compatibility and Limitations to full Cocoa on MacOS X
• Performance and Tuning
• Open Source of the GUI libraries (mySTEP)
• Advanced Debugging

 

In case you need support, please visit the project page: http://www.quantum-step.com