Jan 99 Getting Started
Volume Number: 15 (1999)
Issue Number: 1
Column Tag: Getting Started
Carbon: Getting Ready for Mac OS X
by Dan Parks Sydow
Becoming familiar with the Carbon API to ready your code for Mac OS X
In the previous few months we've covered a variety of graphics-related programming topics, including bringing color and animation to your Mac programs. In future articles we'll discuss other multimedia enhancements (such as sound-playing) that you can incorporate into your own code. This month, however, we'll take a pause in the multimedia action to look at what is becoming a very important topic to all Mac programmers: Mac OS X and the Carbon application programming interface.
Apple will seed the beta version of Mac OS X to select developers next month. Some of you readers may be in the group lucky enough to be getting your hands on a copy of the new, modern operating system. But even if you won't be getting a sneak-peek at Mac OS X, there are still plenty of things you can do to ensure that your own program - whether trivial or all-powerful - is ready for the prime-time release of Mac OS X later this year.
About Mac OS X
By now you've certainly read numerous magazine columns, online reports, and even newspaper articles, devoted to Mac OS X. So we can be succinct here in our definition of just what Mac OS X is. Mac OS X is the version of the Macintosh operating system that's to bring about the important new features and enhancements that all developers and many users have clamored for. Applications running in Mac OS X will have a number of advantages over applications running in previous versions of the Mac OS X. In short, these advantages are:
Increased stability A protected address space means memory protection. When a program "goes bad" it may crash, but it won't take down other applications or crash the system.
Increased responsiveness Preemptive multitasking means that the processor is better able to service all running applications, resulting in each application being more responsive.
Dynamic resource allocation Applications use system resources (such as memory) as needed - they don't need to specify and adhere to predetermined values.
Okay, Mac OS X sounds pretty cool - users will really experience faster applications and fewer crashes. But what do these enhancements mean for us programmers? The answer to that question is the basis of this article, so read on!
API stands for application programming interface, and it's the means of helping programmers develop applications that make use of, or interface with, the code that comprises the operating system. Each operating system has its own API, so to make it quickly evident which API a programmer is referring to, each API has a name. As you know from reading Getting Started, the API Macintosh programmers use is referred to as the Macintosh Toolbox (or the Mac Toolbox, or simply the Toolbox). The Macintosh Toolbox, like any API, is nothing more than a set (albeit a very large set) of routines. When you learn how to make use of these routines, you know how to write programs.
Mac OS X will introduce a host of changes to the Macintosh operating system, so a new means of allowing programmers to interface with the OS is needed. Carbon is that means. Carbon, like the Toolbox, is the set of programming interfaces a programmer uses to develop Macintosh applications. Specifically, Carbon is the set of routines programmers use to develop Mac OS X applications that can also run on Mac OS 8. When a programmer writes a program using Carbon, that program takes advantage of the features new to Mac OS X, such as preemptive multitasking, memory protection, and dynamic resource allocation.
What happens when you run a "carbonized" application on a Mac hosting Mac OS 8 rather than on a Mac hosting Mac OS X? It will run just fine. It won't, however, be more responsive or more stable than any other Mac OS 8 application. Mac OS 8 will simply consider it another Mac OS 8 application. Copy that same application to a Mac hosting Mac OS X, though, and the carbonized program will exhibit the traits expected of a Mac OS X application. To summarize:
Macintosh Toolbox The API for developing applications that run on a Macintosh computer hosting any version of the Mac OS prior to Mac OS X (such as Mac OS 8.5, Mac OS 7.6, and so forth).
Carbon The API for developing applications that can run on a Macintosh computer hosting Mac OS X or any version of Mac OS 8.
Learning a new API can be a daunting task. If you're a regular reader of Getting Started, you are probably just beginning to feel comfortable with using the Macintosh Toolbox API. If tomorrow you were asked to develop a program that would run on a PC hosting Windows 95 or Windows 98, you'd have your work cut out for you. While some general programming principles would translate from one operating system to the other, your API knowledge would be all but useless - Windows has its own huge set of API routines that a programmer uses to develop a Windows application. This all sounds pretty ominous, but it isn't. It's just a setup to let you know how easy you, the Mac programmer, has it. Why? Because the transition from the Macintosh Toolbox API to the Carbon API is nothing like the transition from the Macintosh API to the Windows API. This is because Carbon is nothing more than a cleaned-up, enhanced, Macintosh Toolbox. If you're familiar with the Macintosh Toolbox, you're familiar with Carbon. The more you already know about the Macintosh Toolbox, the more you will know about Carbon.
When Apple bought NeXT, they obtained OpenStep - the API that NeXT programmers use to write applications that run on a computer hosting the NeXT operating system. Just as a Mac programmer makes use of the Toolbox API (and soon, the Carbon API) when developing a Macintosh application, a NeXT programmer makes use of the OpenStep API when developing a NeXT application. After acquiring NeXT, Apple set about adding to OpenStep - Apple engineers wrote new code to enhance the existing OpenStep code. To distinguish this "enhanced OpenStep" from the original OpenStep, Apple gave the new API a new name: Yellow Box. Like Carbon, the Yellow Box is an API used to develop applications that will run on Mac OS X. Unlike Carbon, the Yellow Box isn't similar, or based on, the Macintosh Toolbox (because its origin is a different operating system - the NeXT operating system).
The disadvantage to developing with the Yellow Box is readily apparent: a Mac programmer needs to learn a completely new API. The advantage to developing with the Yellow Box, though, can be impressive: applications based on the Yellow Box API are cross-platform. An application developed using the Yellow Box will, without modification, run on a Macintosh hosting Mac OS X. It will also run on a PC running Yellow Box for Windows - the Apple software that can be installed on most PCs running Windows 95 or Windows 98. When a PC user has Yellow Box for Windows on his Wintel computer, his machine can run all his Windows applications and any Mac OS X application developed using the Yellow Box API.
Programming with the Yellow Box API is out of the scope of Getting Started - here we'll stick to the tried-and-true Macintosh Toolbox and its successor, Carbon. Look for a number of Yellow Box articles in other areas of upcoming issues of MacTech Magazine.
Preparing For Carbon
Mac OS X isn't here yet, and the Carbon API isn't finalized either. But of course we won't let those minor obstacles prevent us from getting started programming for Mac OS X! Even without a final version of Carbon available, you can write Carbon-compliant code. Carbon-compliance means:
Compilation Your code successfully compiles when using the same universal interface files that will be used for creating Mac OS X applications.
Mac OS X and Mac OS 8 compatible The resulting application runs on both Mac OS 8 and Mac OS X.
Mac OS X enhanced The resulting application takes advantage of Mac OS X features such as preemptive multitasking when running on Mac OS X.
Using The Universal Interface Header Files
One step in the preparation for Carbon is to obtain and use the most recent version of the universal header files. These interface files provide your projects with the latest function prototypes for all of the Toolbox functions. As Apple alters Toolbox functions for Carbon, the changes will be reflected in the function prototypes in the universal header files. These interface files are always available to programmers through Apple's public Web site - go to Apple's Carbon Web site at http://gemma.apple.com/macosx/carbon/ to find the link that lets you download the whole set.
When you installed CodeWarrior on your hard drive, the installer copied the universal header files from the install CD to a folder named Universal Headers in the Headers folder - the full path from inside your main CodeWarrior folder is Metrowerks CodeWarrior:MacOS Support:Headers:Universal Headers. Replace this Universal Header folder with the newly downloaded folder of the same name (you can always return to using the original set by copying the universal header files from the CodeWarrior install CD).
CodeWarrior projects typically make use of the universal header files by including one of the compiled MacHeaders libraries (they reside in the MacHeaders folder, which from your main CodeWarrior folder has a path of Metrowerks CodeWarrior:MacOS Support:MacHeaders). To get your projects to make use of the new universal header files you'll need to recompile the various MacHeader libraries. CodeWarrior comes with an AppleScript that takes care of that task for you - from the AppleScript menu of the CodeWarrior IDE choose Recompile MacHeaders. If the IDE isn't displaying the AppleScript menu, check the Use Script menu checkbox from the IDE Extras panel in the IDE's preferences window (choose Preferences from the Edit menu). Once the AppleScript executes, the MacHeaders libraries will be updated and your existing and new projects will make use of them without any extra effort on your part.
Become Familiar With Fundamental Toolbox Differences
The Mac OS X application model and the Mac OS 8 application model are essentially the same. Each type of program is centered on an event loop that calls WaitNextEvent() to procure events from the event queue, and each type of program uses Human Interface routines from the Toolbox to add and support interface elements such as menus and windows. Mac OS X and Mac OS 8 do differ enough from one another in that programs won't access system services in identical manners, though. Here are a few of the noteworthy differences.
Human Interface Toolbox This is the part of the Macintosh Toolbox that consists of a group of routines that implement the Mac OS human interface. Menu, window, and dialog box routines are all found here. For the most part, the Human Interface Toolbox is supported. The major exception is that the Standard File Package will not be supported. Instead, Mac OS X will rely on Navigation Services. Read more about Navigation Services in the August 1998 issue of MacTech Magazine (Vol.14, No.9) and in the Programmer's Introduction to Mac OS 8.5 article in the November 1998 MacTech Magazine issue (Vol.14, No.11).
Application Utilities This area of the Macintosh Toolbox holds the routines that extend the human interface. Apple Guide and the Drag Manager fall into this group. Mac OS X promises to support most of these utilities. One possible exception is the Speech Manager - Apple hasn't come to a final decision as to whether the Speech Manager routines will remain supported.
Graphic Services The Macintosh Toolbox functions that are thought of as graphic services routines are the ones that allow your program to display images. QuickDraw GX won't be supported in Carbon, but the more popular QuickDraw and QuickDraw 3D managers will be supported. Color QuickDraw, the topic of Getting Started two issues back, will also be supported.
Multimedia Services QuickTime is the most popular means of getting multimedia effects into a Macintosh program. QuickTime will be fully supported in Carbon.
Low-Level Operating System Services Designing and implementing an application's user-interface is enjoyable because you get visual feedback of your efforts. But the low-level OS services, such as memory management and file handling, are equally important. Carbon will support most of these services, but expect some reworking of your source code. Memory management in Mac OS X will differ from Mac OS 8, so flag (comment) any memory management code in your projects to remind you that changes may be in order. The same applies to your project's file handling code. Most file handling code will work as is, but the information necessary to define a file system specification (an FSSpec variable) will need to be more complete than in the past. Future Getting Started columns will tackle a couple of often-neglected low-level services: memory management and file handling.
Testing For Carbon Compatibility
Apple is going through the Macintosh Toolbox and determining which of the thousands of routines should be cut, which should stay in an unaltered state, and which should stay but undergo changes. You can find out the status of any Toolbox routine by clicking on the Carbon Specification link at http://gemma.apple.com/macosx/carbon/. Using this method to check the Carbon-compatibility of each Toolbox routine your application calls would be a laborious process, so Apple's come up with a software tool that automates the operation. The Carbon Dater application, freely available from Apple at http://developer.apple.com/macosx/, helps you determine the amount of effort you'll need to expend to port a Macintosh application to Mac OS X.
The Carbon Dater Analyzer
The Carbon Dater analyzer program examines any PowerPC application and generates an output file that can be further examined for Carbon-compatibility. You email this output file to Apple, and Apple then analyzes its contents and returns via email a final compatibility report in HTML format. The process is automated and fast - you may have your report back within the hour!
The Analyzer Report
The output data file created by the Carbon Dater program is an interim file - it alone isn't helpful to you. Instead, you want to read Apple's Carbon-compatibility report that gets generated from the interim Carbon Dater file.
Apple's report lists a number of potential pitfalls that you should watch for in writing code that you want to run on Mac OS X. Most importantly, the report examines all the Toolbox functions your code accesses and determines which calls you need to update or replace. Every questionable Toolbox call your application makes is mentioned in the report. Specifically, the report tells whether a questionable function is supported but modified, unsupported, under evaluation (as to whether it will be supported), or doesn't exist in the latest version of the universal header files.
As shown later in this article, the report includes a pie chart that shows the percentages of Toolbox calls that fall into each category. In addition to alerting you to questionable calls, the report may provide solutions that serve as workarounds.
Carbon Dating Some Code
You can run any PowerPC code you want through the Carbon Dater, but until you're familiar with the Carbon Dating process, it makes sense to avoid working with a monolithic application. Instead, make your initial test one that uses a relatively trivial program. Choose your own simple application, or pick any of the examples from previous Getting Started columns. For no particular reason we'll look over the PixMapper example from last month's Getting Started. You can download that code (or any other back-issue code) from the MacTech ftp site at ftp://ftp.mactech.com/src/mactech/volume15_1999/15.01.sit.
Running the Carbon Dater
The Carbon Dater only works with PowerPC-native applications, so set your CodeWarrior project to generate a PowerPC or fat application and then build an application. From the desktop open the Carbon Dater folder and drag your application's icon onto the Carbon Dater icon. When you do that, the Dater goes to work. As shown in Figure 1, the Carbon Dater posts a window that provides you with a little feedback as to what the analyzer is doing.
Figure 1. The Carbon Dater in action.
When the Carbon Dater is finished, you're prompted to enter your email address. This address should represent the address you want Apple's final report to be sent to, and will be embedded in the Carbon Dater output file. Figure 2 shows this prompt.
Figure 2. Telling Apple where to send the report.
After you dismiss the email dialog box, the program responds by telling you where to email the Carbon Dater output file. Figure 3 shows that the output file will be your program's name with the extension .CCT appended to it, and that this file goes to CarbonDating@apple.com.
Figure 3. Getting a reminder as to what to do with the Carbon Dater output file.
With the initial analysis complete, it's time to give Apple the opportunity to provide you with the final decision on the Carbon-compatibility of your code. Launch your email application of choice, create a new mail message, and address it to CarbonDating@apple.com. Find the .CCT data file on your hard drive and add it to the message as an attachment. While it may not always be necessary, Apple recommends that you send the .CCT file as a stuffed file. If your email program supports stuffing, enable that feature to place the .CCT file in a StuffIt archive. If your email program won't do that for you, use one of Aladdin's programs, such as StuffIt or DropStuff, to stuff the .CCT file and then attach it to the email message. The message subject and body will be ignored, so at this point you're all set to send the message off to Apple.
The chief responsibility of the Carbon Dater is to extract the names of the Toolbox routines your application calls. That information goes into the .CCT data file produced by the Carbon Dater. Apple's job is to look over the contents of the .CCT file, create a final report, and email that report to the address you specified when you ran the Carbon Dater. These tasks are all automated, so after emailing the .CCT file to Apple, expect a returned report within an hour or so.
Looking Over the Report
Apple's report to you will be in the form of an HTML file - open it with any browser. The report begins with a summary like the one shown in Figure 4. This figure shows that the PixMapper program is over ninety percent Carbon-compliant. Apple has gone to great lengths to ensure that porting existing Mac OS 8 code to Mac OS X code is as painless as possible, so unless your code performs exotic, non-recommended tricks, it too should be very compliant.
Figure 4. Looking over the final Carbon-compatibility report.
The report's summary shows that PixMapper includes calls to four questionable Toolbox functions. The next two paragraphs are what the report has to say about one of the three routines that fall into the Supported But Not Recommended category:
Carbon will support the Dialog Manager. However, Apple encourages you to ensure that your application accesses Dialog Manager data structures only through the supplied accessor functions. The use of these accessor functions, to be provided soon, will give your application greater threading flexibility in Mac OS X. Furthermore, you are encouraged to use the functions provided for creating and disposing of Dialog Manager data structures. In Mac OS X, applications might not be allowed to create and dispose of Dialog Manager data structures except by calling Dialog Manager functions.
InitDialogs InitDialogs does nothing. There is no need to initialize the Window Manager, because the shared library gets loaded as needed.
PixMapper's call to InitDialogs() is flagged because the call won't be necessary in Mac OS X applications. The Dialog Manager won't need to be initialized because in Mac OS X its code gets loaded into memory. A Mac application can still make the call, but it will be unnecessary.
Just before the information on InitDialogs(), the report includes information regarding Carbon's support of the Dialog Manager. Don't be alarmed by these "warnings" that appear throughout the report - they may or may not apply to your code. Each modified or unsupported Toolbox routine that your program makes generates a short, general essay on the Carbon-compatibility of the manager the routine belongs to. So while PixMapper doesn't make any serious Dialog Manager mistakes, the report still includes Dialog Manager information (because of the call to the unsupported Dialog Manager routine InitDialogs()). In short, we're being reminded to stick to using the Toolbox when working with dialog boxes. We shouldn't try to circumvent Apple's way of doing things by developing our own routines to access fields of a dialog record. As a Getting Started reader you know we try to stick to doing things by-the-book, and certainly would never try tricks like that!
Now let's see some of what the report has to say about PixMapper's one call to an unsupported Toolbox function:
In Mac OS X, code that communicates directly with hardware devices must use the IOKit API. Other types of code that have relied on the Device Manager interface in the past (such as desk accessories) should be converted into applications.
OpenDeskAcc Desk accessories will not be supported in Carbon. A new mechanism will be provided for handling selections from the Apple menu.
The IOKit is new, and particular to, Mac OS X. There is no comparable Mac OS routine set. The comment says that the concept of desk accessories is being abandoned (it has been, by the way, unofficially abandoned for awhile now). The OpenDeskAcc() routine - which we've been using in our examples to open any item in the Apple menu, won't be supported in Carbon. No replacement routine is mentioned in the report, but at least now we know what code is subject to change. We can't immediately correct the potential problem, but as shown in Figure 5 we can go back into the PixMapper.c file and add a comment to serve as a reminder of what needs updating in the PixMapper code.
Figure 5. Flagging code for future changes.
After looking over the report you'll be able to at best make the necessary code changes, and at worst mark the potential problem areas for future alterations. In all cases you'll be closer to being Mac OS X ready.
Till Next Month...
Apple's Mac OS X plan is clear: provide the user with a faster, more stable computing environment, and provide developers with a straightforward, short learning-curve way of getting the user there. The Mac OS X operating system is for the Macintosh user. Carbon is for you, the Macintosh programmer. Starting now, you'll want your code to be Carbon-compliant.
Now that you've seen how to Carbon date your code, do it! Don't stop at one test, Carbon date any programs to which you have the source code. It's reassuring to see returned reports that show your code to be very Carbon-compliant, but it's a good learning experience to get back a bad report too! Try to find out just what kind of code isn't acceptable for the development of a Carbon-compliant application so that you'll be truly ready for Mac OS X.
Previous Getting Started articles each included a short example program - this month's column didn't. Next month we'll return to our regular format of presenting a basic programming topic supplemented by a short, to-the-point, code example. As usual, the emphasis will be on Toolbox basics. However, now you know that what we've referred to in the past as Toolbox basics will subsequently be referred to as Carbon basics! See you next month...