This chapter describes the basic steps necessary to prepare your CodeWarrior system for building PowerPlant applications to run under the Carbon application programming interface. The chapter contains the following sections:
Certain Apple support software must be installed on your system in order to build Carbon applications. This section describes how to set up your system for Carbon development.
CarbonLib is a compatibility library provided by Apple to allow Carbon applications to run under Classic Mac OS (that is, under system versions prior to OS X). Carbon projects intended to run on Mac OS 8 or 9 must be linked against CarbonLib. If backward compatibility is not an issue (that is, if your project is intended to run only on Mac OS X and not on OS 8 or 9), then you do not need CarbonLib.
At the time of writing, two versions of CarbonLib are available from Apple. The CodeWarrior Pro 6 installer preinstalls CarbonLib 1.0.4, which is compatible with Mac OS version 8.1 or later, but does not support some of the more advanced features of Carbon (such as the Carbon event model, discussed in Chapter 3, "Carbonizing Your Code"). If compatibility back to OS 8.1 is important to you and you do not need these advanced features, you can simply use the preinstalled version of CarbonLib without further modification.
If you are willing to sacrifice some degree of backward compatibility, you may wish to build your project with CarbonLib 1.1 instead of 1.0.4. This version of CarbonLib supports a larger subset of the Carbon API (including Carbon events), but cannot run on Mac OS versions earlier than 8.6. If you are a member of Apple Developer Connection (ADC), you can obtain the CarbonLib 1.1 Software Development Kit (SDK) from the Apple Developers' Web site at
<http://developer.apple.com/macosx/carbon/>
After downloading the SDK, you'll need to perform the following steps to install CarbonLib 1.1 on your development system:
1. Copy the Carbon Support folder into your CodeWarrior folder at the same level as the CodeWarrior IDE.
2. Copy the CarbonLib extension from the Carbon Implementation Libraries folder of the SDK into the Extensions folder within your Macintosh system folder.
3. Copy the runtime library MrCExceptionsLib to your Extensions folder. (This library is required by CarbonLib 1.1, but not by CarbonLib 1.0.4.)
Code written to the Carbon interface requires the correct version of Apple's Universal Interface header files in order to compile. The CodeWarrior Pro 6 installer installs Universal Interfaces 3.3.1 (required by CarbonLib 1.0.4) in the folder
{Compiler}:MacOS Support:Universal
where {Compiler} is the folder containing the CodeWarrior IDE. If you are using CarbonLib 1.1, you will need to replace these with the Universal Interfaces 3.4, which you will find inside the Carbon Support folder in the CarbonLib 1.1 SDK.
Once you have your system set up for Carbon development, you'll need to make certain modifications to your existing PowerPlant projects in order to build them for Carbon. The following steps describe how to modify an existing project for Carbon development:
Add a target to your project for building to the Carbon API:
a. Open the project in CodeWarrior.
b. Display the project window's Targets view.
Click the Targets tab at the top of the project window.
c. Choose Create New Target from the Project menu.
Type a name (such as Carbon) into the New Target dialog box.
e. Clone the new target from an existing one.
Select the Clone existing target option and choose an existing PowerPC target from the pop-up
menu below it.
Click the OK button to confirm the creation of the new target and dismiss
the dialog box.
2. Change the application file name for the new target.
The application file name in your new Carbon target will initially be the same as in the existing target you cloned it from (step 1e above). You must change the file name for the new target, to prevent the two targets from overwriting each other's application files.
With the Targets view still displayed in the project window, click the new Carbon target to select it (or choose it from the pop-up menu at the top of the project window).
b. Display the Target Settings window.
Display the Target Settings window in any of the usual ways-such
as by double-clicking on the target, clicking on the settings
button at the top of the project window, or choosing target_name Settings from the Project menu (where target_name is the name you gave your Carbon target
in step 1d above).
c. Display the PPC Target settings panel.
Select PPC Target (in the Target category) from the scrollable list at the left of the Target
Settings window.
d. Specify the name of the application file.
Type a new file name into the File Name box in the PPC Target settings panel. Make sure the name you
type is different from the one specified in the original target
from which you cloned your new Carbon target.
Click the Save button to confirm the new application file name and dismiss the
Target Settings window.
3. Replace the Classic libraries with CarbonLib.
Remove the old (Classic) PowerPC libraries from your Carbon target and add CarbonLib in its place:
a. Display the project window's Files view.
Click the Files tab at the top of the project window.
Make sure your new Carbon target is selected in the pop-up menu at the top of the project window.
c. Select the Classic libraries.
Select all of the PowerPC *Lib files in the project window's file list. These will probably include InterfaceLib, AppearanceLib, ObjectSupportLib, MathLib, ControlsLib, and WindowsLib, as well as any other Toolbox stub libraries that you use. Do not select any MSL libraries.
d. Display the Project Inspector window.
Choose Project Inspector from the Window menu.
e. Display the Project Inspector's Targets view.
Click the Targets tab at the top of the Project Inspector window.
f. Remove the Classic libraries from the Carbon target.
In the Project Inspector's Targets view, uncheck your Carbon target
to remove the selected libraries from that target. (Don't remove
the libraries from any previously existing targets to which they
already belonged.) Then click the Save button and close the Project Inspector window.
g. Add CarbonLib to the project.
Choose the Add Files command from the Project menu, navigate to the CarbonLib library, and click the Add button to add it to your project. CarbonLib should be found in
the folder
{Compiler}:MacOS Support:Universal:Libraries:
StubLibraries
where {Compiler} is the folder containing the CodeWarrior IDE.
h. Add CarbonLib to the Carbon target.
When the Add Files dialog box appears, check only your Carbon target and uncheck
all others; then click the OK button to add the CarbonLib library to the target and dismiss the dialog box.
| File |
In subfolder |
|---|---|
| For all targets: |
|
| For Carbon targets: |
|
Depending on what parts of PowerPlant you use, you may need to add new PowerPlant files to your project. Table 2.1 summarizes these files, their locations within the PowerPlant folder, and the targets to which they may need to be added.
In addition, for Carbon targets to be run under Mac OS X, you should add the file carb.r (in the PowerPlant Resources folder) to include a 'carb' resource in your application. OS X looks for this resource to determine whether to launch the program in the Carbon or Classic environment; it is ignored in earlier versions of Mac OS, but there is no harm in including it.
5. Remove obsolete PowerPlant files.
The files listed in Table 2.2 are obsolete and should be removed from the indicated targets in your project.
| Remove from all targets: |
| Remove from Carbon targets: |
In order to set up the compilation options properly, it is recommended
that you use a separate prefix file for each target in your project.
Use the Prefix File option in the C/C++ Language settings panel (category Language Settings) to specify the name of each target's prefix file. The prefix
file for Classic targets should include the definitions shown
in Listing 2.1.
Prefix file definitions for Classic targets:
#define PP_Target_Carbon 0 #define PP_Target_Classic (!PP_Target_Carbon) #define TARGET_API_MAC_CARBON PP_Target_Carbon #define TARGET_API_MAC_OS8 PP_Target_Classic
Listing 2.2 shows the corresponding definitions for the Carbon target's prefix file.
Prefix file definitions for Carbon targets:
#define PP_Target_Carbon 1 #define PP_Target_Classic (!PP_Target_Carbon) #define TARGET_API_MAC_CARBON PP_Target_Carbon #define TARGET_API_MAC_OS8 PP_Target_Classic
Note that Carbon does not support the Standard File package or MacTCP. If your code uses Standard File, you must switch to Navigation Services by including the definition shown in Listing 2.3 in the prefix file for your Carbon build target.
Prefix file definition for Navigation Services:
#define PP_StdDialogs_Option PP_StdDialogs_NavServicesOnly
Similarly, if you use MacTCP, you must include the definitions shown in Listing 2.4 to switch to Open Transport instead.
Prefix file definitions for Open Transport:
#define OTCARBONAPPLICATION 1 #define USE_MACTCP 0