Document Revision History

This table describes the changes to Carbon Porting Guide.

DateNotes
 

Updated path to LaunchCFMApp in Debugging Your Application to match that in Running Your Application on Mac OS X.

 

Updated CodeWarrior Mach-O information in Building Carbon Applications to remove mention of the older cross-compiler.

2001-06-23

Spelling correction: “supercedes” should be “supersedes.”

 

Added Important note to Replace Macro Calls to the Mixed Mode Manager With UPP Accessor Functions indicating that Thread Manager functions that did not previously require UPPs for function pointers now require them in Carbon.

 

Added new section: Move Custom Definition Procedures Out of Resources.

 

Added additional information to Add a 'plst' 0 Resource about how the Mac OS X Finder interprets the presence of resource forks and 'plst' 0 resources in determining what environment to launch an application.

 

IB Carbon Runtime in Determine the Appropriate CarbonLib Version is now called Interface Builder Services.

 

Added new section Do Not Write to Your Application’s Resource Fork.

 

Changed text in Running Your Application on Mac OS X to reflect new path to LaunchCFMApp: /System/Library/Frameworks/Carbon.framework/Versions/A/Support/LaunchCFMApp.

 

Correction in Carbon Event Manager: The Carbon Event Manager does not replace the functionality of the Notification Manager.

2000-12-04

The Aqua guidelines document, Adopting the Aqua Interface, is now called Inside Mac OS X: Aqua Human Interface Guidelines.

 

Changed “Add a 'carb' 0 Resource” to Add a 'plst' 0 Resource. The 'plst' 0 resource supersedes the 'carb' 0 resource.

 

Correction in Consider Using Bundles: A bundle appears as a folder hierarchy on Mac OS X if the bundle bit is unset (not set as previously stated).

 

Added information about __appstart to Building Applications Using MPW.

 

Indicated in Update Modified or Obsolete Functions and The Basic Conversion that Carbon does not support the diskEvt event. Removed diskEvt case from Carbon version of Sample.

 

Further subdivided The Basic Conversion by adding sections Installing the Standard Event Handlers and Registering Your Own Event Handlers.

 

Added information about the event handler parameters in The Application-Level Event Handler.

2000-11-15

General correction: specific references to CarbonLib 1.1 updated to CarbonLib 1.2.

 

General correction: CarbonStub now renamed CarbonLibStub.

 

In Preparing Your Code for Carbon, added a link to Technote TN2003, “Moving Your Code to Mac OS X.”

 

Changed URL link in Use the Carbon SDK to http://developer.apple.com/carbon/index.html, as this location is more Carbon-specific and allows ADC members to download prerelease versions of the SDK.

 

Declaration that CarbonAccessors.o is only a porting tool softened in Begin With CarbonAccessors.o and Functions in CarbonAccessors.o. You can link against CarbonAccessors.o to simplify building non-Carbon applications from a Carbon code base.

 

In Conditionalize Quit Menu Items, reworded the text to emphasize that the position of the Quit item is a feature of the user interface (Aqua versus Mac OS 8 and 9) rather than of the underlying system.

 

Added more information to Begin Transitioning to the Aqua Interface, including details about Appearance Manager compliance, sheets, and help tags.

 

In Adopt a Terse Name for the Application Menu changed the recommended storage location for the name from Info.plist to InfoPlist.strings, because the latter allows the name to be localized.

 

Simplified methods of transferring files between Mac OS X and Mac OS 8 and 9 in Native Mac OS 9 Versus Mac OS X’s Classic Environment, as file sharing is now fully supported.

 

Added About box screen shot to Modify the About Box.

 

Mentioned in The Application-Level Event Handler that you could assign a command ID for a menu item in an 'xmnu' resource instead of calling SetMenuItemCommandID.

 

Bug fix in Listing 4-1: Added DisposeRgn call to the kEventMouseMoved case of the application event handler to deallocate memory from the NewRgn call.

2000-10-24

Revised text in Resources and Move Resources to Data Fork–Based Files to emphasize that the preferred method for accessing application resources is by using CFBundle APIs. Also added that the 'cfrg' 0 and 'carb' 0 resources need to remain in the resource fork for CFM-based Carbon applications so the Mac OS X Finder can launch them properly.

 

The Carbon Event Manager constant kEventWindowSizeChanged now replaced by kEventWindowBoundsChanged.

 

In section Check Your OpenGL Code, the OpenGLMemoryLibrary library is now compatible with Carbon. Also, if you are building a Mach-O Carbon applicatiojn that uses OpenGL, you must call the aglConfigure function before creating any OpenGL contexts.

 

Added screen shot of the ported Sample application to The Carbon Version of Sample.

 

Added information about new Carbon technology Multilingual Text Engine (MLTE).

 

Added Index.

2000-10-12

Correction in How Does Carbon Work?: CarbonLibStub changed to CarbonStub.

 

Changed section “Adopt the Carbon.h Header” to Modify or Conditionalize Your Headers. You no longer need to adopt Carbon.h. The path required for the cc compiler is now -I /Developer/Headers/FlatCarbon. You can also use this path with the conventional Mac OS 8 and 9 headers when building on Mac OS X.

 

Changed text in Begin Transitioning to the Aqua Interface to indicate that your application automatically registers with the Appearance Manager when you link with CarbonLib.

 

Added new chapters, A Porting Example and New Carbon Technologies.

 

Added new appendix, The Sample Application which contains the source code to be ported in A Porting Example.

2000-09-07

Updated software and header versions to reflect the latest available.

 

Added new porting guideline Modify or Conditionalize Your Headers.

 

Added info about using plists to signify Mac OS X Carbon applications in Add a 'plst' 0 Resource and Running Your Application on Mac OS X.

 

Correction in Determine the Appropriate CarbonLib Version:: Appearance Manager 1.1 is available in all versions of CarbonLib, not just 1.1 and later. Also, DataBrowser is now available back to System 8.6.

 

Handling Buffered Windows section added, which incorporates information from the older section “Drawing into Windows Without QuickDraw”.

 

Added more specific event information (for example, which event to wait on) in answers to questions in Window Dragging and Resizing Q&A.

 

The Aqua guidelines document referenced in Begin Transitioning to the Aqua Interface is now Adopting the Aqua Interface. Added URL pointer to the document.

 

Added new porting guidelines: Move Resources to Data Fork–Based Files and Consider Using Bundles.

 

Added new build section Building Applications Using MPW.

 

Added new sections Changes to WDEFs and Changes to MDEFs under Custom Definition Procedures.

 

Removed private functions from CarbonAccessors.o list in Table A-3.

 

In Table A-3, QError should be QDError.

 

Removed functions accidentally identified as removed from CarbonAccessors.o in Table A-3: GetWindowKind, SetWindowKind, GetKeys, GetWindowSpareFlag, InvalWindowRect, and InvalWindowRgn,.

2000-07-11

Major reorganization of material.

 

Introduction to Carbon Porting Guide rewritten to reflect the current state of Carbon.

 

Porting guidelines reorganized into sections: Essential Steps for Porting Your Application, Additional Porting Issues, and Optimizing Your Code for Carbon.

 

Some existing porting sections were renamed to better integrate wth the new sections.

 

New porting guideline sections added: Use the Carbon SDK, Target Mac OS 8 and 9 First, Use DebuggingCarbonLib, Adopt Required Carbon Technologies, Update Modified or Obsolete Functions, Determine the Appropriate CarbonLib Version, Examine Your Plug-ins, Adopt HFS Plus APIs, Consider Mach-O Executables, Adopt a Terse Name for the Application Menu.

 

Softened requirements for the contents of a carb'0' resource in Add a 'plst' 0 Resource. The resource can contain arbitrary data.

 

Comparision of CFM versus Mach-O object file formats moved to the porting guidelines chapter under Consider Mach-O Executables.

 

Linking to Non-Carbon-Compliant Code moved to porting guidelines chapter.

 

Directory paths in Mac OS X have changed:

 

Path /System/Developer/Tools/LaunchCFMApp is now /Developer/Tools/LaunchCFMApp.

 

Path System/Administration/Terminal.app is now /Applications/Utilities/Terminal.app.

 

Function descriptions and other reference-like material moved to the Appendix: Custom Definition Procedures, Functions for Accessing Opaque Data Structures, Functions in CarbonAccessors.o, Debugging Functions, and Resource Chain Manipulation Functions.

 

Revised contents of CarbonAccessors.o in Table A-3 and Table A-4.

2000-05-01

Updated software and header versions to reflect the latest available (for example, CarbonLib 1.1 and Universal Interfaces 3.4d2).

 

Added new section, The Carbon Specification.

 

Added new sections describing preparations for Carbon conversion:Don’t Pass Pointers Across ProcessesAvoid Polling and Busy WaitingUse Casting Functions to Convert DialogPtrs and WindowPtrsUse Lazy Initialization for Shared LibrariesCheck Your OpenGL CodeBegin Transitioning to the Aqua InterfaceProvide Thumbnail Icons for Your Application

 

Added information about avoiding preallocation and suballocators in Manage Memory Efficiently.

 

Created new section, Window Manager Issues, to cover Window Manager porting issues in detail.

 

In Table A-1, added SetMenuDefinition as the accessor function for the MenuProc element in a MenuInfo structure.

 

Added Table A-2 listing QuickDraw accessor functions.

 

Added information about transferring files between Mac OS 9 and Mac OS X computers in Native Mac OS 9 Versus Mac OS X’s Classic Environment.

 

Revised contents of CarbonAccessors.o in Table A-3..

 

Added list of functions removed from CarbonAccessors.o in Table A-4.

 

Emphasized that you cannot link with InterfaceLib if you link to CarbonLib in Using CodeWarrior to Build a CFM Carbon Application

 

Created new section, Linking to Non-Carbon-Compliant Code.

 

Revised Debugging Your Application to include specific information about debugging Carbon applications using GDB.

 

Added this document revision history.