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:

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.

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.

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:

user.MacFiles/System/Preferences/LatitudeApps

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.

PowerPlant

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):

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:

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:

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:

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.

Muscle

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;
#endif

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.

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 http://www.metrowerks.com for up to the minute updates on CW Latitude and Metrowerks' other products.

PCalc is a full-featured, scriptable scientific calculator with support for hexadecimal, octal, and binary calculations, as well as an RPN mode, programmable functions, and an extensive set of unit... Read more

FileZilla 3.10.2 - Fast and reliable FTP...

FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface.
Version 3.10.2:
Note: Now requires a 64-bit Intel processor.... Read more

The Hit List 1.1.11 - Advanced reminder...

The Hit List manages the daily chaos of your modern life. It's easy to learn - it's as easy as making lists. And it's powerful enough to let you plan, then forget, then act when the time is right.... Read more

Bartender 1.2.32 - Organize your menu ba...

Bartender lets you organize your menu bar apps.
Features:
Lets you tidy your menu bar apps how you want.
See your menu bar apps when you want.
Hide the apps you need to run, but do not need to... Read more

ClamXav 2.7.5 - Free virus checker, base...

ClamXav is a free virus checker for OS X. It uses the tried, tested, and very popular ClamAV open source antivirus engine as a back end.
I hope you like and use ClamXav a lot and that it helps keep... Read more

xScope 4.1.2 - Onscreen graphic measurem...

xScope is powerful set of tools that are ideal for measuring, inspecting, and testing on-screen graphics and layouts. Its tools float above your desktop windows and can be accessed via a toolbar,... Read more

MacFamilyTree 7.3.3 - Create and explore...

MacFamilyTree gives genealogy a facelift: it's modern, interactive, incredibly fast, and easy to use. We're convinced that generations of chroniclers would have loved to trade in their genealogy... Read more

Skype 7.5.0.738 - Voice-over-internet ph...

Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more

PushPal 3.0 - Mirror Android notificatio...

PushPal is a client for Pushbullet, which automatically shows you all of your phone's notifications right on your computer. This means you can see who's calling or read text messages even if your... Read more

At this point it’s pretty safe to say that no MOBA is going to dethrone Dota 2 and League of Legends anytime soon. After all, if Batman can’t do it, nobody can. However, with a genre as popular and profitable as this one, there’s still room for... | Read more »

Final February Fun at 148Apps
How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you’re looking for. The ones we love become Editor’s Choice, standing out... | Read more »

GDC 2015 – Does Not Commute is Definitel...

GDC 2015 – Does Not Commute is Definitely a Game You Should Keep an Eye on
Posted by Rob Rich on March 2nd, 2015 [ permalink ]
We were teased about Mediocre Games’ (Smash Hit,
| Read more »

F84 Games & POW! Announce Stan Lee V...

F84 Games has announced that it is working with legendary comic creator Stan Lee and POW! Entertainment to produce Stan Lee’s Hero Command. The game will be a action adventure of heroic proportions.
| Read more »

Setlyst Keeps Your Set Straight So You C...

Setlyst Keeps Your Set Straight So You Can Focus On Rocking Out.
Posted by Jessica Fisher on March 2nd, 2015 [ permalink ]
Universal App - Designed for iPhone and iPad
| Read more »

Space is Vast, So Space Agency Has a Vas...

Space is Vast, So Space Agency Has a Vast New Update!
Posted by Jessica Fisher on March 2nd, 2015 [ permalink ]
Universal App - Designed for iPhone and iPad
| Read more »

Size DOES Matter Review

Size DOES Matter Review
By Campbell Bird on March 2nd, 2015
Our Rating: :: HARD TO BEATUniversal App - Designed for iPhone and iPad
This rhythm game has a unique control scheme and performance system that make it feel like a true... | Read more »

The first ever action 3D card battler Al...

On the other hand, you probably haven’t played an action 3D card battler – until now. Step forward, All Star Legion.
All Star Legion is a 3D QTE-based action RPG card battler, but fear not – the game itself isn’t as convoluted as its description.... | Read more »

Travel Back to the 1980s With the Making...

Headup Games has released a hilarious making of video for its upcoming title, Pixel Heroes: Byte & Magic. The game is a RPG/Roguelike where you control three heroes set to save the township of Pixton from an evil cult called The Sons of Dawn.... | Read more »

Price Scanner via MacPrices.net

Sale! 15-inch 2.2GHz Retina MacBook Pro for $...

Best Buy has the 15″ 2.2GHz Retina MacBook Pro on sale for $1774.99 $1799.99, or $225 off MSRP. Choose free home shipping or free local store pickup (if available). Price valid for online orders... Read more

27-inch 3.5GHz 5K iMac in stock today and on...

B&H Photo has the 27″ 3.5GHz 5K iMac in stock today and on sale for $2299 including free shipping plus NY sales tax only. Their price is $200 off MSRP, and it’s the lowest price available for... Read more

Apple Launches Free Web-Based Pages and Other...

Apple’s new Web-only access to iWork productivity apps is a free level of iCloud service available to anyone, including people who don’t own or use Apple devices. The service includes access to Apple... Read more

Survey Reveals Solid State Disk (SSD) Technol...

In a recent SSD technology use survey, Kroll Ontrack, a firm specializing in data recovery, found that while nearly 90 percent of respondents leverage the performance and reliability benefits of SSD... Read more

Save up to $600 with Apple refurbished Mac Pr...

The Apple Store is offering Apple Certified Refurbished Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more

Apple CEO Tim Cook will deliver the George Washington University’s Commencement address to GWU grads on May 17, at which time he will also be awarded an honorary doctorate of public service from the... Read more

Apple restocks refurbished Mac minis for up t...

The Apple Store has restocked Apple 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... Read more

Walmart has the 16GB iPad Air 2 WiFi on sale for $446.99 on their online store for a limited time. Choose free shipping or free local store pickup (if available). Sale price for online orders only,... Read more

Jobs Board

*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

*Apple* Pay Automation Engineer - iOS System...

**Job Summary** At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring passion and dedication to your job
Read more

Sr. Technical Services Consultant, *Apple*...

**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional
Read more

Event Director, *Apple* Retail Marketing -...

…This senior level position is responsible for leading and imagining the Apple Retail Team's global engagement strategy and team. Delivering an overarching brand
Read more

*Apple* Pay - Site Reliability Engineer - Ap...

**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring
Read more

MacTech is a registered trademark of Xplain Corporation. Xplain, "The journal of Apple technology", Apple Expo, Explain It, MacDev, MacDev-1, THINK Reference, NetProfessional, Apple Expo, MacTech Central, MacTech Domains, MacNews, MacForge, and the MacTutorMan are trademarks or service marks of Xplain Corporation. Sprocket is a registered trademark of eSprocket Corporation. Other trademarks and copyrights appearing in this printing or software remain the property of their respective holders. Not responsible for typographical errors.

All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.