Carbonization 101
Volume Number: 16
Issue Number: 12
Column Tag: Carbon Development
By Éric Simenel
Easier than you might think and so rewarding
The Benefits of Carbon
A beta version of Mac OS X has just been released to the public and a final version
should be released in early 2001.
Figure 1. Mac OS X applications.
Four different kinds of applications, shown in Figure 1, can run on Mac OS X:
1. unmodified Mac OS applications currently running on Mac OS 9 or
earlier, will run in the Classic environment. The User Experience will be the
same as the one provided with Mac OS 9, and if one of the applications running
in that environment encounters a serious problem, it may bring down the
whole environment and thus any other application running in that
environment.
2. Java applications, developed using only the JDK and companion libraries.
3. Cocoa applications, developed in either java or Objective-C (possibly
mixed with C/C++), and using the Cocoa frameworks.
4. and, last but not least, Carbon applications which are slightly modified
Mac OS applications.
Each of the last three kinds of application, Java, Cocoa, and Carbon, all run as separate
processes in their own protected memory area. If any of those applications encounters
a serious problem, it won't affect the others.
The benefits, then, of Carbonizing an application should be apparent: for the cost of a
few hours or days of work, you get a much more robust and impervious application
that your users can run without problems. Another advantage is that a carbonized
application gives you the Aqua theme user interface on Mac OS X.
Carbon being present, through the installation of CarbonLib, on Mac OS 9, 8.6, and
8.1, a Carbonized application, as a single binary, can run on all Mac OS from 8.1 to X.
The Scope of Carbon
Most applications and some plug-ins can be carbonized successfully. Extensions
(INITs), Control Panels (cdev), and drivers of any sort cannot be carbonized since
they don't run on Mac OS X and the main goal of Carbon is to provide an easy transition
for developers from Mac OS 8 and 9 to Mac OS X.
Which version of Carbon should be used?
The version of Carbon that you choose depends on your goals and the configurations that
you are targeting. If you want the maximum Mac OS coverage, use only Carbon 1.0.4
APIs which are supported from Mac OS 8.1 to Mac OS X. CarbonLib 1.0.4 gives most of
the Toolbox APIs, plus the Control, Window, and Menu Properties, Navigation
Services, the Core Foundation APIs, and Carbon Printing 1.0. If, when carbonizing,
you find that you are missing a desired functionality, check if it is provided in the
Carbon 1.1 APIs which give you access to Appearance 1.1, Carbon Events (which offer
an alternative to patching the Toolbox), the new DataBrowser control, ATSUI, URL
Access, Keychain, FontSync, XML, HTMLRenderingLib, and others. Choosing the Carbon
1.1 APIs will restrict your target configurations to Mac OS 8.6 and above.
Note: Carbon on Mac OS X, and its companion CarbonLib for Mac OS 8 and 9, are not a
closed API but an ongoing development. Future Apple technologies might be delivered
only through the Carbon APIs.
The Carbon Porting Process
Let's examine the nuts-and-bolts to see how porting to Carnon can be done. The goal of
this article is not to be a rewrite of the "Carbon Porting" document which can be found
in the Carbon SDK (see the bibliography at the end of the article for useful URLs), but
rather a step-by-step guide based on DTS Engineers' experiences during various
Carbon Porting lab events with 3rd-party developers at Apple.
This is not just a bunch of recipes, although you may find them very useful, but rather
a methodology to apply when you encounter a problem not yet covered in any
documentation.
Estimating how much work will be required
Of course, the amount of work depends on the size of the source code and the number of
unsupported APIs in your source code. Experience in the Carbon Porting labs tells us
that most developers can successfully carbonize 80% or more of their applications in
the 3 to 5 days of that event.
CarbonDater is a tool which may help you quickly determine the amount of work to be
done. An example of a Carbon Compatibility Report is shown in Figure 2.
Figure 2. The Carbon Compatibility Report.
The Carbon Compatibility Report also provides a fairly detailed analysis and some
suggestions as to how to replace unsupported APIs (Figure 3) and the kinds of
modifications you will have to make in order to be Carbon-compliant (Figure 4).
Figure 3. Unsupported API.
Figure 4. Modified API.
Another way to estimate the necessary amount of time is to plunge right into the
Carbonization process; the first compilation will give you an idea of the extent of the
work to be done.
First things first
As the "Carbon Porting Guide" suggests, it's best to update your project to the latest
Universal Headers first. If you're interested in Carbon 1.0, then use the Universal
Headers 3.3.2, but if you're interested in Carbon 1.1, then use the Universal Headers
3.4. If you are developing with CodeWarrior, be careful to follow the instructions
(from your CodeWarrior User's manual) and update any pre-compiled headers if
you're using them.
The next step depends on the size of your project and the way you prefer to develop.
You can either follow all the steps described in the "Carbon Porting Guide" (which is
preferable if your project is large), or follow these instructions (which assume you
are using CodeWarrior, any version after and including Pro 2):
• first, clone your existing PowerPC target,
• second, add the preprocessor command #define
TARGET_API_MAC_CARBON 1 to the beginning of your project's prefix file (if
you already have a prefix file, then duplicate it, add the preprocessor
command in one of them and use this one for your Carbon target),
• and third, remove all Apple stub libraries such as InterfaceLib and any
others that you might have needed in your project such as AppearanceLib,
WindowsLib, etc., and add the CarbonLib stub instead. You can keep non-Apple
libraries such as "MSL RuntimePPC.Lib", "MSL C.PPC.Lib", etc.
If you are using any other libraries, then you will need to determine (the PEF Viewer
utility can help you do that) if the code they contain is importing any symbols from
InterfaceLib or any of those Apple libraries at runtime. If that's not the case then they
should be safe to use as is, but if they are , then those libraries will have to be
carbonized as well.