Jan 98 Factory Floor
Volume Number: 14
Issue Number: 1
Column Tag: From The Factory Floor
CodeWarrior Latitude: Porting Your Apps to
by Dave Mark, ©1997 by Metrowerks, Inc., all rights reserved.
The June, 1997 Factory Floor column contained an interview with David Hempling,
CodeWarrior Latitude engineering lead. You can find the interview at:
http://www.metrowerks.com/products/cw/latitude/index.html.
For those who missed the interview, CodeWarrior Latitude is essentially a porting
library that greatly simplifies the process of porting MacOS applications to Rhapsody.
Latitude is an implementation of the Macintosh System 7 application programming
interfaces (APIs) that allows source code for a Macintosh application to be compiled
with little modification on a Rhapsody platform, resulting in a native Rhapsody
application. Latitude maps the Mac API requests to native Unix system calls. An
application built with Latitude attains the look and feel of the new native platform. In
this column we'll explore the process of using Latitude to port applications to
Rhapsody.
A Simple Example
Let's start off with a simple example, straight from the pages of the Mac Primer,
Volume II. ColorTutor allows you to play with the various Color Quickdraw drawing
modes. Written in C, ColorTutor consists of a project file, a C source file, and a
resource file containing MENU & WIND resources.
The first task in porting an application to Rhapsody is to physically get the
application's files to the Rhaposdy platform. There are several ways to do this. For the
source code itself, any means of transferring text files from one computer to another
will do. If we had a collection of sources, we could tar them up with a tar tool on the
Mac, ftp the tar file to Rhapsody with something like Fetch, and untar the image on the
other side. This method cannot be used to transfer Mac resource data.
Another method would be to use one of several available UNIX/Mac file sharing systems
such as MacNFS, NFS/Share, IPT uShare, Helios EtherShare, or Xinet K-AShare.
Latitude's File Manager understands the various formats that these systems use so they
are also good for transferring Mac resource data.
Before copying over the resource file, however, we must ensure that a BNDL resource
is present in the application's resource data. Latitude requires the signature value in
an application's BNDL resource in order to maintain its own "desktop database".
ColorTutor.rsrc does not have a BNDL resource so we'll add one, using ResEdit, on the
Mac. We'll make ColorTutor's signature 'CTTR'. That done, we'll build ColorTutor on
the Mac, ensuring that all of the application's resources are collected into the
application's executable.
For this example, we use NFS/Share to transfer the ColorTutor executable to our
target platform. NFS/Share uses AppleDouble format, so the file will be split into two
pieces when it is transferred, namely ColorTutor and %ColorTutor.
Once we've successfully transferred the file to our Rhapsody file system, we place
%ColorTutor in a directory named:
$LATITUDE_ROOT/Latitude.MacFiles/Applications/ColorTutor/
$LATITUDE_ROOT is where Latitude was installed on our Rhapsody system. We place
ColorTutor.c in the directory:
$LATITUDE_ROOT/Latitude.MacFiles/Applications/ColorTutor/Sources/
We can now prepare the ColorTutor.c file for compilation. Latitude includes a tool
called prepare_sources that traverses your source files and replaces non-ANSI
Mac-isms in your sources (such as pascal strings, eight-bit characters, and four
character constants) with macros that conditionally expand to either the Macintosh or
the ANSI styles, depending on where the build takes place. It also creates a Makefile
usable with gnu make that can be used to build your application.
prepare_sources wants to know the name of the application we're creating and the type
of system includes it is using:
% prepare_sources ColorTutor universal
Creating Latitude.manifest...
Converting source files to Latitude files.
mac2unix: processing ./ColorTutor.c
Writing default Makefile...
Conversion complete.
ColorTutor.c is copied to ColorTutor.c.bak, preserving the original code, and three
files are created: the modified source ColorTutor.c, a Makefile, and Latitude.Manifest,
which is a list of the source files used to create the application.
Looking at ColorTutor.c, we can see that prepare_sources replaced all "\p..." strings
with PSTRINGCONST("...") macros. It also replaced four-character constants like
'DRVR' with the QUADCONST('D','R','V','R') macro. Even though some non-Mac
compilers will handle a four character constant, the order of the characters in the
resulting long can be flipped. By using QUADCONST(), we ensure that the proper
ordering is achieved.
When compiled on the Mac, ColorTutor.c relied on the MacHeaders pre-compiled
headers. Since we don't have pre-compiled headers on our non-Mac platform (yet), we
must explicitly include MacHeaders in our source. A copy of the standard MacHeaders
is included in $LATITUDE_ROOT/utilities, so we'll copy it to our ColorTutor/Sources
and #include it at the top of ColorTutor.c
ColorTutor.c uses qd. to access Quickdraw low memory globals like thePort,
screenBits, etc. CodeWarrior Latitude supports these globals but does not keep them in
a qd structure. We can use a macro to remove qd. when it is used. At the top of
ColorTutor.c, we add the following:
#ifdef _LATITUDE_
#define QD(x) x
#else
#define QD(x) qd.x
#endif
We now go through ColorTutor.c and replace instances of qd. with the use of the QD()
macro. So
InitGraf( &qd.thePort );
becomes
InitGraf(&QD(thePort));
There are a few other instances in the file which we'll replace as well.