Converting to MacApp Release 13


This document describes changes required to compile and run older MacApp applications using MacApp Release 13. Some changes are specific to migrating from MacApp 3.3 to R12, and some from R12 to R13, but a few regressed changes from MacApp 3.1 are also included because they were previously not required changes for migrating to MacApp 3.3, but now are required or highly recommended.

The following topics are covered:


Good Reasons for migrating

Here are a just a few of the many Good Reasons for migrating to Release 13, which many developers have been asking to have in MacApp, for you to remember as you are migrating:


Example & Tools

We have provided an annotated conversion example which shows many of the considerations discussed in the following sections.

ConvertToR13

This script iterates over all .h, .cp, .cpp, and .cxx source files in a specified path directory, applying the MPW Canon tool with the "R13.dict" dictionary file to those source code files. Running this script will make most class name and terminology changes. All changes will be reported in the MPW Shell, so you can examine this output for any mistakes.

R13.dict

This is a canon dictionary which can be used with MPW or ToolServer to translate old MacApp names into the new ACS names.

Free2Delete

This script will scan your source code and convert the old and no longer used Free methods into C++ destructors.

UpdateClassInfo

This script which will scan your source code and update your class description and definition macros.

Canonize

This is a helper script for the ConvertToR13 script, which calls Canon with the appropriate parameters.

RunCanon

This is a helper script for the ConvertToR13 script, which calls Canonize with the appropriate parameters.

Note: these scripts and the canon dictionary are not likely to look very good in your web browser. There are intended to be viewed using MPW.


Getting Ready to Migrate

The application should be compilable and runnable under a particular version of MacApp, at least version 3.1.5 or newer, before following these release notes. If you are using MacApp Release 3.3 or Release 12, you will encounter correspondingly fewer changes.


Migrating to Release 13

Assuming the application is compilable and runnable under MacApp 3.1.5, the following steps should be taken for migrating the application:

  1. Use MakeProjectFromTemplate to create a new CodeWarrior project. Remove the template files, add your existing source code, and make other application-specific project settings as needed. This will ensure the project settings, include paths, libraries, etc. are correct for MacApp and ACS, and it is a lot easier than applying all the requisite changes to your existing project.
  2. Run the Free2Delete MPW script (provided with MacApp 3.3, but also provided with Release 13) using MPW or ToolServer. This converts Free() methods to destructors automatically for you.
  3. Run the UpdateClassInfo MPW script (provided with MacApp 3.3, but also provided with Release 13). This cleans up ClassInfo macros so they use current names and removes DeclareClassDesc.
  4. Set the MPW current directory to the directory containing the ConvertToR13 script. Run the ConvertToR13 script (provided with Release 13) with a parameter specifying the directory path containing source files to be converted. This script iterates over all .h, .cp, .cpp, and .cxx source files using the MPW Canon tool with the "R13.dict" dictionary file. This handles most class name and terminology changes automatically, including a few anachronisms.
  5. If you choose not to perform the ConvertToR13 step, you may be able to get by if you add the following define to AutoSwitches_AC.h (located in CS:suites:core:headers:):
     #define qBackwardCompatible 1
  6. There are a few things the qBackwardCompatible flag can't do for you, such as replace all your Boolean, TRUE, and FALSE references with bool, true, and false, and transmogrify methods whose parameters have changed or that have become const.
  7. Change direct accesses to member data with accessor/manipulator functions. Porting tip: setting the qBackwardCompatibility flag also lets you continue to get away with bad programming practices such as directly accessing member data, so you can delay this cleanup step by temporarily setting the qBackwardCompatibility flag to 1.
  8. Convert I methods to constructors. For each occurrence, use the Constructors examples to convert your code manually.
  9. Search your code for "FailInfo". For each occurrence, use the Exception Handling examples to convert your code manually.
  10. Review the list of methods that have become const or that have changed parameters and update your source code.
  11. Review all command objects that implement filtering or that rely on the Commit method. The new multi-level Undo/Redo will break filtering, but you can disable multi-level undo by setting the undo/redo level to 1.


Conversion notes

The notes in this section are not required reading since many of them are covered by following the steps outlined above, but it contains useful reference material for converting your code.

The following applications have been migrated to Release 13, and were used to generate the conversion notes and examples.

Changes caught by the build environment

Changes caught by the compiler

   	short aNumber = Min(0, anotherNumber);	

becomes:

   	short aNumber = Min_AC(static_cast<short> (0), anotherNumber);

Changes caught by Rez

Changes caught by the linker

Changes noticed at Runtime

What seems to have been fixed that wasn't expected to be fixed


Back to the Index



© Copyright 1997 by Apple Computer, Inc. -- Last Updated 7/31/97