TweetFollow Us on Twitter

Jan 98 Factory Floor

Volume Number: 14 (1998)
Issue Number: 1
Column Tag: From The Factory Floor

CodeWarrior Latitude: Porting Your Apps to Rhapsody

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:

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 is where Latitude was installed on our Rhapsody system. We place ColorTutor.c in the directory:


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
#define QD(x)   qd.x

We now go through ColorTutor.c and replace instances of qd. with the use of the QD() macro. So

InitGraf( &qd.thePort );



There are a few other instances in the file which we'll replace as well.

Before we build ColorTutor, we must insert code to initialize Latitude. The lg_latitude_init() call does several things. It sets up Latitude's trap table, initializes various toolbox managers, and opens Latitude's System file and the application's resource file. lg_latitude_init() also allows settings that affect how the application looks and behaves. For ColorTutor, only the bare minimum is required.

Currently, main() starts out like this:

void  main( void )

We're going to change main() to accept arguments and pass those arguments to lg_latitude_init:

#ifndef _LATITUDE_
void  main( void )
void  main( long argc, char **argv )
#ifdef _LATITUDE_
    LG_APP_INFO_BLOCK lblock;

    lblock.flags = LG_APP_INFO_SIGNATURE |
    lblock.signature = QUADCONST('C','T','T','R');
    lblock.classname = "Latitude";
    lg_latitude_init(argc,argv, &lblock);


We're now ready to build ColorTutor. Using the gcc 2.7.2 compiler, this code compiles without error. However, if you're using a different C compiler, you may find that the C++ style '//' comments at the top of ColorTutor.c are a problem. If so, simply replace them with C style '/* */' comments and rebuild. The first time we run ColorTutor, Latitude brings up a Get File Dialog asking us to locate the application's resource file. This is only done once. Latitude stores the location of the resource file in it's own desktop database located at:


Once that is done, ColorTutor is off and running on our platform. Playing with the app's popup menus and seeing the proper results in the dialog shows that this application was ported successfully with very little effort. Additionally, we can take this source code back to the Mac, along with the LGLatitude.h file, and continue to use the same source to build both our Mac and non-Mac platform versions.


Obviously, ColorTutor is a very simple application that doesn't contain any serious portability problems. It's ANSI C code, contains no private resource data that it uses itself, doesn't patch traps, doesn't have custom definition functions, etc. Lets move on to a more complex porting example and look at what's required to bring a PowerPlant app, like Muscle, over to Rhapsody using CodeWarrior Latitude.

The first thing to notice about PowerPlant is that it's written in C++ and that its source code is laid out hierarchically in a directory structure. It's easy to replicate this structure on our new platform. The prepare_sources script currently only recognizes file extensions for C (.c & .h). It is easy to modify the 'find' incantation in prepare_sources to recognize the C++ file naming convention used in PowerPlant. prepare_sources is also fairly naive about complex development environments. Depending on your own expertise with Makefiles, you may decide to build the development environment yourself. You do need to run the conversion script, mac2unix, over the code to take care of the pascal strings and four character constants, however.

Inside the PowerPlant code itself, there are a few modifications we need to make.

Template Instantiation

Template instantiation is not standardized across C++ platforms. When we brought PowerPlant away from the Metrowerks environment, we entered a world where multiple instantiations of C++ templates needed to be handled differently.

There are two classic approaches to solving the instantiation issue: the Cfront and Borland models. In Cfront all instantiations occur in a single well-known directory. The Borland model, on the other hand, instantiates each template in each translation unit with duplicates being removed by the linker. Both techniques have serious flaws and have led to other approaches. The gcc compiler that we're using on Rhapsody, in particular, eschews these and provides instead 3 different techniques. The details of the problems encountered with all of these approaches will be deferred for a future article. In short, the only approach that worked was to:

  • disable implicit instantiation (compiler option)
  • disable explicit instantiations in header files
  • explicitly instantiate each template in each translation unit in which the linker complained

This solution is not optimal because the burden for template instantiation is placed on the programmer. Change the code or how the translation units are combined and you may have to change where the explicit instantiations are placed. But it does work. We hope that better automatic approaches are found in the future that eliminates the need for any explicit instantiation statements.

For example, we had to turn off any explicit instantiation statements that occurred in .h files (really a bad idea to begin with):


  template class TArray<LPane*>;

and then to make sure that source files that required the instantiations had them:


  template class TArray<LPane*>;
  template class TArrayIterator<LPane*>;

Scripting & AEObject Support

Latitude's Apple event implementation is not complete. While basic Apple event calls are in place, AEObject support is not. PowerPlant uses AEObjects to record user actions as well as trigger window management, such as taking a window down or allowing a window to be dragged. PowerPlant's AEObject code is centralized and it was clear where an event was dispatched and where it was picked up. We modified the code to perform the end result directly, without going through the AEObject dispatching mechanism.

For example, PowerPlant's LWindow::AttemptClose() function now looks like this:

   // Get approval from SuperCommander
   if ((mSuperCommander == nil) 
      || mSuperCommander->AllowSubRemoval(this)) {
      // Send Close AE for recording only
      SendSelfAE(kAECoreSuite, kAEClose, false);
      delete this;

Long-Word Alignment

Mac resource data is kept in 680x0 alignment space, meaning long words can fall on short word boundaries. Reading in a 680x0 aligned resource on a platform in which long words are aligned on long word boundaries yields inaccessible data and even segmentation and bus errors, depending upon how the source code accesses the data. While some compilers have align pragmas that can keep structures in a specified alignment space, these pragmas are not common to all platforms, even with the same compiler. We recommend that these pragmas not be used since they don't ensure portability.

Latitude includes tools to pack and unpack Mac resources and file data. By using these tools, your app is assured to be portable to other platforms where CodeWarrior Latitude is supported. Additionally, Latitude's lg_align* tools will perform byte swapping once Latitude is made available for x86 platforms. In PowerPlant, the LWindow::MakeMacWindow() function sneaks a peek at a WIND resource before calling Mac Window Manager's GetNewWindow(). The code fragment looks like this:

SWINDREsourceH theWind = (SWINDResourceH) ::GetResource(QUADCONST('W','I','N','D'), inWINDid);

Int16 kind;

#ifdef _LATITUDE_
if (lg_align_unpack((Handle)theWIND, SWINDResource_align) != noErr)
   /* unpack failed! */
kind = (**theWIND).refcon;

The SWINDResource_align argument to lg_align_unpack is a LG_ALIGN token array containing a description of the elements of the WIND resource. Had we not done the lg_align_unpack, the kind variable would contain garbage since the refcon field of a WIND resource is not naturally long word aligned.

Floating Windows

Many Mac applications have floating windows and it seems that every Mac application accomplishes this feat differently. Some patch traps such as FrontWindow, SendBehind, and WaitNextEvent. Some modify the Window Manager's WindowList. Latitude is capable of supporting floating windows through many different methods. The best method, however, is to let Latitude float the windows without intervention.

Regardless of how your application floats windows, it is best to alert Latitude that a certain window is meant to float when the window is created. This way Latitude can make this communication to the gui layer and ensure that the window is created with a floating attribute.

In PowerPlant's UDesktop::NewDeskWindow() function, we want to inform Latitude that the window we're about to create is a floater. Just before the GetNewWindow() call at the bottom of this function, we insert the following:

#ifdef _LATITUDE_
   if (inWindow->HasAttribute(windAttr_Floating)) {
      LG_WMGR_WINDOW_BLOCK wblock;
      wblock.flags = LG_WMGR_WINDOW_FLOAT;
      wblock.floats = LG_WINDOW_IS_FLOATER;

   if (UEnvironment::HasFeature(env_SupportsColor)) {
      macWindowP = ::GetNewCWindow(inWINDid, nil, inBehind);
   } else {
      macWindowP = ::GetNewWindow(inWINDid, nil, inBehind);

CW Latitude has three settings for the floats attribute: LG_WINDOW_IS_FLOATER means that this window is to float above other windows that aren't specified to float. LG_WINDOW_HAS_FLOATERS is the default for regular windows. These windows allow others to float above them. Finally, LG_WINDOW_HAS_NO_FLOATERS specifies windows that must float above all else.

Controls As Drawings

On the Mac, standard controls are drawn in Quickdraw so the area they're rendered in, when scrolled, behaves as expected and the control scrolls with the area. This not the case with CW Latitude and the gui layers it supports. On systems like Motif, controls float above the window's canvas, so if drawings are scrolled across the window, the controls will not move by themselves. They must be explicitly moved.

PowerPlant's LPane::AdaptToSuperScroll() adjusts the control's rectangles but doesn't move the controls themselves. By overriding AdaptToSuperScroll for the LStdControl class and adding a Draw(nil) call, we can be sure that CW Latitude's gui layer will move the control for us.


With as much PowerPlant as needed for Muscle ported, we can now begin looking at Muscle's source code. Since Muscle is almost entirely written in terms of PowerPlant, we have very little work to do.

In the ColorTutor example, we had to remove instances of qd. for CW Latitude. In C++ applications however, the QDGlobals type is a class of inline definitions tied to the Quickdraw low memory globals and the application must define it's own QDGlobals qd. So at the top of CMuscleApp.c, we add

#ifdef _LATITUDE_
QDGlobals qd;

We also add a lg_latitude_init() call similar to the one we added in ColorTutor.c. Muscle's signature is 'MePo'. We can also turn on CW Latitude's gui colorization so that windows have a default background color that matches the rest of their desktop.

void   main( long argc, char **argv )
#ifdef _LATITUDE_
   LG_APP_INFO_BLOCK   lblock;

   lblock.flags = LG_APP_INFO_SIGNATURE |                   LG_APP_INFO_CLASSNAME |
   lblock.signature = QUADCONST( 'M','e','P','o' );
   lblock.classname = "Latitude";
   lblock.window_gui_color = 1;
   lg_latitude_init( argc, argv, &lblock );

Muscle contains a demonstration of PowerPlant's QuickTime support. Unfortunately, Rhapsody does not yet support QuickTime. Latitude will rely on Rhapsody's own QuickTime support once it becomes available. At this point, it is necessary for us to #ifdef out code involving QuickTime. This code is centralized in Muscle's CMuscleApp.cp file and is easy to spot. QuickTime initialization and destruction code in CMuscleApp::CMusleApp and CMuscleApp::~CMusleApp, QuickTime demo selection code in CMusleApp::ObeyCommand, and CMusleApp::FindCommandStatus can all be #ifdefed out.

Porting YOUR Application

As any seasoned Mac programmer will agree, there is a lot of lore in Mac programming. Having assisted many Mac porting projects using CodeWarrior Latitude since its beginnings, we have seen some porting efforts go smoothly and some go rough. Knowledge of Mac programming lore is key.

The make-up of the porting team makes all the difference in the world. The best team combines experience from both Mac and Rhapsody environments in addition to a strong understanding of the underlying Mac code base.

Less advantaged teams are made up entirely of either Mac programmers who aren't familiar with Rhapsody details or Rhapsody programmers who have no Mac programming experience and are not at all familiar with the code base being ported. Experience from both sides is necessary. Rhapsody and/or UNIX skills are needed to properly set up the development environment and address platform issues. Mac skills are needed to understand what exactly is being done in the application source code. By taking the time to put the right team together for the job, your porting project will be much smoother and easier.

We've touched on only a few aspects of the process of porting Mac applications to Rhapsody. Fortunately, PowerPlant and Muscle do not contain many of the imaginative coding techniques we've seen in other Mac applications. Many of these issues are discussed in the CodeWarrior Latitude Guide that accompanies the CodeWarrior Latitude software package.

We invite you to stop by Developer Central at MacWorld in San Francisco, January 6 - 9, 1998, and see Latitude in action. You can pick up the ColorTutor and other sample code at MacTech's web site. And don't forget to stop by for up to the minute updates on CW Latitude and Metrowerks' other products.


Community Search:
MacTech Search:

Software Updates via MacUpdate

Between 2 Taps - Tap for Tap interview M...
Hello, and welcome back to Between 2 Taps, Tap for Tap’s Indie Dev interview series. [Read more] | Read more »
Facility 47 (Games)
Facility 47 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: You wake up alone and freezing in an icy cell. You try the cell door but it’s locked, it seems that you are stuck with no... | Read more »
The best Photoshop alternative on iPad
Instagram and Lightroom are great and all, but sometimes people need to get extra creative with their image editing.Like, Photoshop creative. If you're one of these people, take a look at our pick for the best mobile Photoshop experience on iPad... | Read more »
The Walking Dead: No Man’s Land guide -...
A new update for The Walking Dead: No Man’s Land was released last week, making it the perfect time for you to head back to your base and take out some walkers. Here’s the lowdown on what’s new to the game, and how to take advantage. [Read more] | Read more »
Goat Rider guide - Tips and tricks to st...
We've all been there. One second, we're riding high on a crazed goat, and the next, we've been tossed off it like someone who's no good at goat ridin'. [Read more] | Read more »
Real Boxing 2 CREED: How to become a gre...
Just in time for Rocky fans who can’t wait to see CREED, the latest movie, we have the official tie-in game,Real Boxing 2 CREED. It builds on the success of its predecessor and there’s lots to take in so we at 148apps thought we’d run you through... | Read more »
CoinOp Heroes 2 guide - How to build an...
CoinOp Heroes 2 justlaunched and, like all clickers, it's dangerously addictive stuff. You have to furiously tap your screen to defeat wave after wave of foes and earn an insane amount of cash to spend on character upgrades and an army of minions... | Read more »
Dr. Panda Firefighters (Education)
Dr. Panda Firefighters 1.0.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0.1 (iTunes) Description: FIGHT FIRES AND SAVE THE DAY!Work together with Dr. Panda and his firefighting team to rescue his trapped... | Read more »
Puddle + (Games)
Puddle + 1.0 Device: iOS iPhone Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Puddle is back in a new "+" edition featuring enhanced graphics, new videos and Apple TV support ! No IAP and No Ads. Dive into Puddle... | Read more »
Football Manager Mobile 2016 (Games)
Football Manager Mobile 2016 7.0.0 Device: iOS Universal Category: Games Price: $8.99, Version: 7.0.0 (iTunes) Description: Football Manager Mobile 2016 is designed to be played on the move and is the quickest way to manage your... | Read more »

Price Scanner via

Adorama Black Friday deals: Up to $400 off Ma...
Adorama has released their Black Friday deals for 2015. Save up to $400 on MacBook Pros, $200 on MacBooks and MacBook Airs, and $270 on iMacs. Use code RYBFDEAL during checkout to see these prices.... Read more
B&H Photo Deals: $200 off 12-inch 1.2GHz...
In addition to the B&H Photo Black Friday week sales we posted yesterday, B&H has lowered their price on two products to $200 off MSRP: - 12″ 1.2GHz Gray Retina MacBook: $1399 save $200 - 13... Read more
Best Buy Early Access: Today only, Up to $125...
Best Buy has iPad Air 2s on sale for up to $125 off MSRP and Apple Watch models on sale on their online store for up to $100 off MSRP with special codes through midnight CT tonight. Choose free... Read more
UPPERCASE DESIGNS Premium Ultra Thin Keyboard...
UPPERCASE Designs today announced its new Premium Ultra Thin Keyboard Protector and its Palm Rest Protector Set for the 12-inch MacBook. The accessories provide durable protection for the 12-inch... Read more
Al Jazeera Launches New iOS And Android Mobil...
Doha, Qatar based Al Jazeera has launched new mobile and tablet apps on the iOS and Android systems bringing the latest Al Jazeera news and programmes live together with on-demand personalisation.... Read more
B&H Photo Holiday Sale: Up to $250 off Ma...
B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their Holiday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799 $200 off - 15″ 2.... Read more
Free Aura ‘Ultimate’ Mac App For Gmail Update...
Miami, Florida based Crosscoded has announced Aura 1.2.0, an update to the Mac app for Gmail. Aura mixes the power of a native client with the flexibility of the Gmail web app with support for up to... Read more
Apple Will Edge Closer to Samsung in Smartpho...
Total smartphone shipments for 2015 are projected to decline by 9.7% to 1.286 billion units, according to the latest report from global market research firm TrendForce. Though Chinese vendors have... Read more
Sidefari – Split Screen Multitasking In Safar...
Francisco Cantu’s Sidefari is a simple web browser designed to act as a companion to Safari on the iPad. With multitasking in iOS 9, Sidefari uses the new Safari View Controller to show an extra... Read more
12-inch MacBooks in stock for up to $120 off,...
Adorama has 12″ Retina MacBooks in stock for up to $120 off MSRP including free shipping plus NY & NJ sales tax only. For a limited time, Adorama will include a free Apple USB-C to USB Adapter,... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Merchant Operations Manager: *Apple* Pay -...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
*Apple* Pay QA Manager - Apple Inc. (United...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
Sr Software Engineer *Apple* Pay - Apple In...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
Hardware Systems Architect - *Apple* Watch...
# Hardware Systems Architect - Apple Watch Job Number: 38449977 Santa Clara Valley, Califo ia, United States Posted: Apr. 16, 2015 Weekly Hours: **Job Summary** The Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.