Porting packages to Rosemary

The quantity of changes in the Magic Cap API in Rosemary is daunting, at best. Many classes are obsolete while new classes have been introduced. Classes that still exist may have had fields added or removed, and methods may have had their interfaces changed. Additionally, the class and object definition syntaxes have been modified (hopefully improved) to support concepts introduced in the new runtime.

To help make porting packages from Magic Cap 1.x to Rosemary easier, the SDK includes a set of conversion scripts that automates many of the necessary changes. This document takes you through the steps you should follow to get a Magic Cap 1.x package up and running on Rosemary.

How to use the documentation

The Rosemary SDK comes with two sets of documents that describes the changes to Magic Cap: Class Changes and Release Notes.

The Class Changes document set is a list of raw changes to all Magic Cap classes, listing new and obsolete classes, fields, attributes, inheritance chains and methods. Many of these classes contains a section titled "background information", which is a list of links into the Release Notes document set.

The Release Notes document set provides more of a high level overview of the changes to Magic Cap. Each of the sections in the Release Notes discusses a particular area of Magic Cap, and provides a conceptual background for the changes in each area. Each section ends with a list of classes that are affected by the changes discussed in that section. Each class is linked to its list of changes in the Class Changes documents so you can see exactly what is different in each class.

How to use the conversion scripts

To start the automated conversion scripts:

On MPW:

simply choose the Convert Package To Rosemary menu item from the Utils menu. This command works on the current directory, so be sure you have made your package directory the current directory. You can also start the conversion scripts from the MPW Worksheet by typing the command

"{MagicDevConversionScripts}UpdatePackageToRosemary" packageDirectory

where packageDirectory is the full pathname to the directory containing the package you want to update. The pathname must be terminated with a colon (:).

On Developer Studio:

simply change directory to the directory where the package to be converted exists, and type the command

Convert2Rosemary

The conversion script will make a copy of your package source files before modifying them. The scripts determine which conversions will need to be performed on your package. This allows additional conversion scripts to be added in the future, allowing incremental automated conversions as work on Rosemary progresses. The automated conversion process will take several minutes to execute.

Conversion script details

This section discusses what modifications the conversion scripts will make to your package. You should refer to the Release Notes document for more detailed information about the particular changes made in Magic Cap that necessitate these modifications.

Indexicals

In Rosemary, indexicals are no longer entries in a root list; they are simply indirect object references. The brace style declaration of indexicals are no longer relevant, and indexicals can only be accessed with their symbolic names. As part of the conversion process, indexicals in object definition files that are still referenced with the brace format will be changed to use their symbolic names instead.

The conversion scripts will scan C source and header files for indexical declarations and create a new class definition file that declares your package indexicals. The root list entries in your software package object will be removed, and new indexical initialization statements will be generated for your package indexicals.

Note: Because indexicals are referenced symbolically, all package indexicals must have a corresponding name. The conversion scripts will warn you when an unnamed indexical is encountered.

System defined package indexicals no longer exist in Rosemary. The conversion scripts will take these root list entries and either make them into fields of the new SoftwarePackageContents object, or delete references that were never required.

Viewables

Viewables are no longer represented as doubly linked lists. In Rosemary, each viewable lists its subviews in back to front order in its extra data portion. The conversion scripts will convert the format of viewable objects in your object definition files from doubly linked lists to the new object list format.

Note: The scripts do not convert view chains with no superview. Examples of such view chains are chains referenced from a ViewChainList object, or from a SceneAdditions object. In these cases, where a view chain starts from a non-viewable object, you will need to create an ObjectList that lists the members of the view chain, then refer to this list from the original non-viewable object that referenced the view chain.

Object tags

The syntax for an object defintion has been modified to group all optional portions of the object definition after all the mandatory parts. This is the long way of saying that the unique object tag now comes before the optional object name in an object definition.

An object tag is now an alphanumeric identifier instead of a numeric identifier. The conversion scripts will change all numeric identifier in your object definitin files to alphanumeric tags be prepending the string "unnamed" to the numeric tag.

Class headers

In order to define new classes, the class compiler needs information about the superclasses for new classes. Similarly, in order to instance classes, the object compiler needs information about the class being instantiated. To do this, class and object definition files must specify the required class headers with read statements, much like source files must specify function prototypes with include statements. The conversion scripts will insert a read statement for system classes into your class and object definition files.

Note: If your source code accesses the fields of package classes, or calls package class methods, you will need to include the header files that are created by the class compiler for these classes. The class compiler creates a ".xh" and ".xph" file for each package class definition file. Every source file that uses a class from one of these class definition files should include the .xh and .xph header files for that class definition file. These include statements replace the old #include "Package.h" statement that normally appears in every source file. Similarly, if you have package classes that inherit from packages classes defined in another class definition file, you'll need to add a read statement for the superclass's class definition file. (We'll make conversion scripts for these soon.)

Changed fields

While the conversion scripts do not add new fields or deleted obsolete fields for most objects, objects that underwent major restructuring are updated automatically.

The length of extra data lists are encoded in a special word at the start of the extra data section of list objects, making the explicit length field of list objects obsolete. The object compiler considers the specification of a length field to be a syntax error. The conversion scripts will remove the length field of all instances of classes that inherit from class FixedList.

List view column data is no longer kept in the extra data of the parent list view object. The column offsets, flags and keys are stored in separate list objects, which are referenced from new fields in GridView subclasses. The conversion scripts will gather the column information from the extra data of list view objects and separate them out into the individual object lists.

The actionData field of class LocalRuleAction has been replaced by two new fields so that Magic Cap can separate operation numbers from other integer data. The conversion scripts will replace the actionData field with these two new fields and fill in the appropriate field based on the rule action type.

Some fields have been renamed. The conversion scripts will update the old field names to the new names.

Magic Cap 1.x used flags fields in objects to compactly store various boolean attributes. Because the object compiler can compact these values, many flags fields have been split into individual boolean fields, making it easier to set particular attributes of various objects. Classes which use flags fields to store non-Boolean information still contains flags fields. The conversion scripts will split flags fields into individual boolean fields, maintaining the value of the boolean attribute.

Note: Some flag bits have always been reserved or undefined. The conversion script will issue a warning if it encounters a set bit that corresponds to one of these flag bits.

Classes whose instances are shared inherit from class HasDigest to get a checksum field so that identical objects can be found. The new shared object framework in Rosemary obsoletes this class and field. The conversion scripts will remove the checksum field from instances of class Image, MIDISong, ShapeType and Sound.

Keyword changes

Several keywords for the class and object compilers are obsolete. The conversion scripts will update obsolete keywords to the current syntax if possible, or simply delete keywords that are no longer supported.

Note: The conversion scripts do not remove explicit declarations of class, operation or intrinsic numbers from class definition files. You'll need to remove these lines manually.

Magic scripts

The CompiledScript and Procedure classes that supported scripted objects in Magic Cap 1.x have been replaced with classes that support the Java byte codes used by the new script interpreter. The conversion scripts will change the old objects into a high level script syntax that is compiled into the new script objects when the package is built.

Source files

The C++ compiler is used to build Magic Cap packages for Rosemary. The conversion scripts will change all source files with .c suffix to the C++ .cpp suffix.

The empty main() function is no longer required by the linker in Rosemary packages. The conversion scripts will remove this function from source files.

Updating Magic Cap methods

Many Magic Cap methods have been removed, replaced, or simply changed since Magic Cap 1.5. You can see if your package uses any of these methods by choosing Find Changed Interfaces from the Utils menu. This script will scan all the C and C++ source files in the current package directory for method calls. For each method call the script finds, it will look it up in a database of methods that have been removed or changed. A window listing all such methods will appear. Each method is marked with its source file and line number so that you can quickly get to that method. Often, each marked method will be followed by a brief note about what needs to be done to use the method, or its replacement in Rosemary.

Here are examples of messages that this script generates:


EndRead( iTrios )
#------------------------------------------------------
File "cap:Desktop Folder:OfficialSamples:TicTacToe:TicTacToe.c"; Line 184
The new interface for EndRead is:
	This method is obsolete.

Use either EndReadFields() or EndReadExtra() instead.
#------------------------------------------------------

TextToString(text, str)
#------------------------------------------------------
File "cap:Desktop Folder:OfficialSamples:TicTacToe:TicTacToe.c"; Line 328
The new interface for TextToString is:
	This method is obsolete.

Use text manipulation calls directly if possible.
#------------------------------------------------------

HideFingerprint(TouchInput_)
#------------------------------------------------------
File "cap:Desktop Folder:OfficialSamples:TicTacToe:TicTacToe.c"; Line 439
The new interface for HideFingerprint is:
	HideFingerprint();

HideFingerprint is now an intrinsic, and no longer needs a <self> parameter.
#------------------------------------------------------

SetUpParameters(&params.header, 1)
#------------------------------------------------------
File "cap:Desktop Folder:OfficialSamples:TicTacToe:TicTacToe.c"; Line 621
The new interface for SetUpParameters is:
	This method is obsolete.
#------------------------------------------------------

MakeUsable(self, TTTFields.squares)
#------------------------------------------------------
File "cap:Desktop Folder:OfficialSamples:TicTacToe:TicTacToe.c"; Line 626
The new interface for MakeUsable is:
	This method is obsolete.

Use MakeUsableReference() instead.
#------------------------------------------------------

Conversion script limitations

There are some cases that the conversion scripts will not handle properly. If you have any of these constructs in your files, you may need to modify them before running the conversion scripts, or possibly update your source files manually.

#ifdefs

The conversion scripts do not handle conditional compilation statements properly. If your object definition files contain #ifdefs around or in objects that the conversion scripts modify will not be correct in the resulting object file. Conditional statements around objects that are not looked at by the conversion scripts will not affect the conversion process.

Long filenames

The conversion scripts will create new files based on the name of the package being converted. If the package name is more than 17 characters long, some of the new files will not be able to be created. Unfortunately, this is a silent error in this version of the conversion scripts.

Dead objects

After running the conversion scripts, some objects in your object definition files may no longer be referenced by any other object in your package. The object compiler considers the presence of dead objects to be an error; you will have to remove these objects manually. A specific example of dead objects that will be left in your object definition file will be the object tree starting from the Citation object which was used to uniquely identify packages in Magic Cap 1.x. This object tree is obsolete in Rosemary, but these objects are not deleted automatically.

Creating phrase files for your package

Rosemary will be international capable; packages built for Rosemary can be localized for the U.S., France, or Japan. Localizable elements of packages are described in phrase files. The actual localization is done with FileMaker. When you build a package, you will always be building for one of the three possible locales. You choose the desired locale from the Target menu in the development environment. Because you will always be building a localized version of your package, you will need a phrase file for the target locale. Template phrase files are located in the Phrase file templates folder of the SDK. You should copy these files into your package directory before building your package.

Creating a new make file

Rosemary introduces a new set of tools that are used to build your package, so you'll need to regenerate your package make file. The standard Magic Cap package make file that is created with the Create Build Commands... menu item in the Build menu will create the correct build rules. If you have heavily customized your package make file, you'll need to first create the default make file, then add your customizations again.

Porting packages to Rosemary