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

ExpanDrive - Access cloud storag...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Markly 1.5.3 - Create measurement and de...
Markly is a measurement and design-spec plugin/extension for Photoshop and Sketch. It is made for modern Web designers and app front-end developers. You can add specification marks simply by clicking... Read more
Suitcase Fusion 6 17.3.0 - Font manageme...
Suitcase Fusion 6 is the creative professional's font manager. Every professional font manager should deliver the basics: spectacular previews, powerful search tools, and efficient font organization... Read more
Nisus Writer Pro 2.1.2 - Multilingual wo...
Nisus Writer Pro is a powerful multilingual word processor, similar to its entry level products, but brings new features such as table of contents, indexing, bookmarks, widow and orphan control,... Read more
calibre 2.40.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Vivaldi - An advanced browser...
Vivaldi is a browser for our friends. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind... Read more
OmniPlan 3.0 - Robust project management...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Yummy FTP 1.11 - FTP/SFTP/FTPS client fo...
Yummy FTP is an FTP + SFTP + FTPS file transfer client which focuses on speed, reliability and productivity. Whether you need to transfer a few files or a few thousand, schedule automatic backups, or... Read more
Tweetbot 2.1 - Popular Twitter client. (...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
MacPilot 8.0 - Enable over 1,200 hidden...
MacPilot gives you the power of UNIX and the simplicity of Macintosh, which means a phenomenal amount of untapped power in your hands! Use MacPilot to unlock over 1,200 features, and access them all... Read more

Balloony Land offers a fresh twist on th...
Balloony Land by Palringo offers a fresh twist on the match three genre and is out now on iOS and Android. First-off, you'll be popping balloons instead of crushing candy and the balloons will float up and fill the empty spaces instead of dropping... | Read more »
Graphic - vector illustration and design...
Graphic - vector illustration and design 1.0 Device: iOS iPhone Category: Productivity Price: $2.99, Version: 1.0 (iTunes) Description: Autodesk Graphic is a powerful full-featured vector drawing and illustration application right in... | Read more »
Sago Mini Babies (Education)
Sago Mini Babies 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: Introducing the Sago Mini babies. Boys and girls love caring for these adorable characters. Feed Robin her favorite mush... | Read more »
PAUSE - Relaxation at your fingertip (H...
PAUSE - Relaxation at your fingertip 1.1 Device: iOS iPhone Category: Healthcare & Fitness Price: $1.99, Version: 1.1 (iTunes) Description: | Read more »
Super Sharp (Games)
Super Sharp 1.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.1 (iTunes) Description: Your finger has never been so sharp! Cut with skill to complete the 120 ingenious physics levels of Super Sharp and become a cut... | Read more »
Assembly - Graphic design for everyone...
Assembly - Graphic design for everyone 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Assembly is the easiest most powerful design tool on the App Store. Create anything you can... | Read more »
Dub Dash (Games)
Dub Dash 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: ARE YOU READY FOR THE ULTIMATE CHALLENGE? UNIQUE SYMBIOSIS OF MUSIC AND GRAPHICS | Read more »
Leave Me Alone (Games)
Leave Me Alone 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: 33% off launch sale!!! Somewhere between the 1980s and 1990s there exists a world that never was. A world of skatepunks,... | Read more »
YAMGUN (Games)
YAMGUN 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: The invasion has begun! Protect the walls of the citadel against waves of enemies! But watch out, you will soon run out of ammo...... | Read more »
Chesh (Games)
Chesh 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: It’s like chess, only not at all. ***40% off for a limited time to celebrate our launch!*** Chesh is a game of skill, strategy, luck,... | Read more »

Price Scanner via

Apple restocks refurbished Mac minis for up t...
Apple has restocked Certified Refurbished 2014 Mac minis, with models available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $... Read more
TP-LINK Next-Gen Routers Support a Large Numb...
TP-LINK, specialists in consumer and business networking products, have announced the availability of Archer C2600, the company’s next-generation router featuring wireless AC, multi-user MIMO, and 4-... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
Save up to $350 with Apple refurbished iMacs
Apple has Certified Refurbished iMacs available for up to $350 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $1949 $350 off MSRP - 27... Read more
Mac Pros on sale for up to $300 off MSRP
B&H Photo has Mac Pros on sale for up to $300 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2818.99, $181 off MSRP - 3.5GHz 6-core Mac Pro: $3699... Read more
5K iMacs on sale for up to $150 off MSRP, fre...
B&H Photo has the 27″ 3.3GHz 5K iMac on sale for $1899.99 including free shipping plus NY tax only. Their price is $100 off MSRP. They have the 27″ 3.5GHz 5K iMac on sale for $2149, $150 off MSRP... Read more
Twelve South Redesigns BookArc For Today’s Sm...
Twelve South has announced a redesigned version of their very first product, BookArc for MacBook. Tailored specifically for the newest generation of MacBooks, BookArc holds the new, smaller Apple... Read more
Phone 6s Tips & Tricks – Tips Book For iP...
Poole, United Kingdom based Tap Guides Ltd. has announced the release and immediate availability of iPhone 6s Tips & Tricks, an in-depth eBook available in the iBookstore that’s priced just $2.99... Read more
Apple refurbished 2014 13-inch Retina MacBook...
Apple has Certified Refurbished 2014 13″ Retina MacBook Pros available for up to $400 off original MSRP, starting at $979. An Apple one-year warranty is included with each model, and shipping is free... Read more
13-inch 2.5GHz MacBook Pro on sale for $994,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $994.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $105 off MSRP. Price valid... 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
*Apple* Retail - Multiple Positions (US) - A...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're Read more
*Apple* Solutions Consultant -Bilingual, Chi...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
SW QA Engineer - *Apple* TV - Apple (United...
**Job Summary** The Apple TV team is looking for experienced Quality Assurance Engineers with a passion for delivering first in class home entertainment solutions. **Key Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.