This document provides installation instructions for using ODF with Metrowerks CodeWarrior and also gives instructions for creating new parts and building them with CodeWarrior.
Table of Contents
-------------------------
• Using the ODF Installer
• Installing ODF Manually
• Installing Cyberdog Support
• Creating a New Part
• Using PartMaker
• Adding New Files to Your Project
• Updating Your NMAP Resources
• Building Your Part
• Running Your Part
• Building ODF
Using the ODF Installer
Run the ODF Installer located in this folder ('Install ODF (CW)') and follow the instructions to install ODF for use with the CodeWarrior development environment. This installer allows you to choose whether you want to install support for either PowerPC or 68K part development and also allows you to specify where you want ODF installed.
Note that the installer must be run from the CD.
After running the installer, read the sections later in this document for instructions on how to create a part, build, and run it.
Installing ODF Manually
For the most part, installing ODF is simply a matter of copying the ODF source and tools to your local hard drive. However, since ODF supports several different compilers, there are some files that you don't need to copy if you are doing all of your development with CodeWarrior.
The basic steps you need to follow when installing ODF for CodeWarrior are as shown in the following list. These steps are explained in more detail below.
1) Copy the ODFDev folder to your local hard drive.
2) Copy the CodeWarrior plugin tools to your CodeWarrior Plugins folder.
3) Copy the stationery files for the ODF example parts to your Stationery folder. (optional)
4) Copy any desired reference materials to your local hard drive. (optional)
5) Make an alias to the ODF library (debug build, PPC or 68K) and copy it into your Editors folder.
6) Copy the ODF sample parts. (optional)
1) Copy the ODFDev folder to your local hard drive.
You can copy the ODFDev folder in its entirety to your local hard drive. This folder contains the ODF source code and the source code for ODF's example parts. The ODFDev:ODF subfolder also contains configurations and project setups for building the ODF libraries.
Once you’ve copied ODFDev, you can throw away folders for other environments. Inside the ODF folder, you can throw away the RB (Symantec), MC (MPW PPC), and SC (MPW 68K) folders. You only need to keep the CW (CodeWarrior) and SL (Shared Library) folders. The same is true for all the example projects.
The following table indicates, for each folder, which compiler is used, and the resulting binary. Notice that the 68K ODF Shared Library is currently built with the Symantec 68K compiler and the PPC ODF Shared Library is always built with CodeWarrior.
The following table indicates which folders are necessary for each supported compiler.
Folder CW/PPC CW/68K Symantec68K MrC Rainbow
CWPPCDebug Y N N N N
CWPPCRelease Y N N N N
MCPPCDebug N N N Y N
MCPPCRelease N N N Y N
RBPPCDebug N N N N Y
RBPPCRelease N N N N Y
CW68KDebug N Y N N N
CW68kRelease N Y N N N
SC68KDebug N N Y N N
SC68KRelease N N Y N N
SL68KDebug N Y Y N N
SL68KRelease N Y Y N N
SLPPCDebug Y N N Y Y
SLPPCRelease Y N N Y Y
2) Copy the CodeWarrior plugin tools to your CodeWarrior Plugins folder.
In order to compile ODF resource files (.fr extension) and IDL files (.idl extension) using CodeWarrior, you must install the ODFRC and SOMobjects™ TS plugin tools. These tools are located in the 'CodeWarrior Plugins:Compilers' folder. Copy all of the files in this folder to the 'CodeWarrior Plugins:Compilers' folder in your CodeWarrior development environment.
3) Copy the stationery files for the ODF example parts to your Stationery folder. (optional)
If you want to run the ODF sample parts, you will need to copy the stationery files for these parts into your Stationery folder. The stationery files are located in the 'ODF Sample Parts:Stationery' folder.
4) Copy any desired reference materials to your local hard drive. (optional)
ODF comes with several documents and tools, such as the ODF Class Reference and MacBrowse, that can make it easier to navigate through the ODF code. You can copy any of these to your local hard drive.
The 'Documentation' folder contains the ODF Class Reference, which is a QuickView database that allows you to quickly search for the documentation for a particular class or method. Make sure that the QuickView application and the ODF Class Reference document are in the same folder when you launch the application.
The 'Tools & Goodies:MacBrowse' folder contains the MacBrowse application that enables you to browse the ODF source code directly. It also contains a subfolder with the MacParse tool, which you can use to create parsed files for use with MacBrowse.
The 'Tools & Goodies:Object Master™' folder contains an empty ObjectMaster project, which you can use to create a browsable set of the ODF source code.
5) Make an alias to the ODF library.
To make debugging with ODF easier, you need to make an alias to the debug version of the ODF shared library and put the alias into your Editors folder. If your ODF environment is on a different volume than your system folder, you can create an Editors folder at the root level of your development hard drive and put the alias there. (OpenDoc does not allow you to put aliases to files on different volumes in the Editors folder.)
Note: The ODFLibrary (or an alias to it) must be located in your Editors folder. Part editors that were built with ODF require the existence of this library and will not run without it.
The debug version of the ODF shared library (ODFLibrary) is already built and is located in the 'ODFDev:ODF:SLPPCDebug:Bin:' folder for PPC and in the 'ODFDev:ODF:SL68KDebug:Bin:' for 68K.
For convenience, you can also make an alias to the symbol files for the ODFLibrary (ODFLibrary.xSYM) and put it on your desktop. When you want to load the symbol file into the CodeWarrior debugger, you can double-click on the alias.
IMPORTANT: Make sure that the release version of the ODFLibrary or any of the ODF sample parts are not installed on your machine while you are attempting to trace through either the ODFLibrary or sample parts. The chances are good that you will not get the right library. OpenDoc searches for the first part editor and library that matches its search parameters. The release version of the ODF libraries and samples are simply optimized versions that do not have internal debugging information, such as Macsbug symbols or assertions.
6) Copy the ODF Sample Parts. (optional)
Copy the ODF sample parts from the 'ODF Sample Parts' folder to your Editors folder.
Installing Cyberdog Support
ODF provides some preliminary Cyberdog support in the 'ODF & Cyberdog' folder. This support has not been fully integrated into ODF yet, so it's currently provided in a separate folder. If you want to support Cyberdog in your sample parts, you need to install this code into your ODFDev folder as follows:
1) Copy the FWCyber folder to your ODFDev folder.
2) Copy the ODF CyberStarter example to your ODFDev folder. (optional)
3) Install Cyberdog headers and stub libraries. (Not Provided)
1) Copy the "ODFCyberLibrary" folder to your ODFDev folder.
Copy this folder to the root level of your ODFDev folder.
2) Copy the CyberStarter examples to your ODFDev folder. (optional)
If you want to build the Cyberdog samples, then you should also copy the CyberStarter sample part from the "ODF & Cyberdog" folder to the root level of your ODFDev folder.
3) Install the Cyberdog headers and stub library into CodeWarrior’s Headers folder. (Not Provided)
You need to install the Cyberdog headers and stub library into the CodeWarrior's headers folder.
Creating a New Part
Whenever you want to create a new part, use PartMaker to generate your initial project. PartMaker is located in the PartMaker folder and contains five templates: two for creating a non-embedding part based on the ODFHello and ODFNothing examples, and three for creating an embedding part based on ODFContainer, ODFEmbed, and ODFTable.
1) Use PartMaker to generate a new project.
2) Add any new files to your project.
3) Update your Binding resources.
Note: Any parts you make must be created in the ODFDev folder. This is because the CodeWarrior projects generated by PartMaker contain relative paths (in the Access Paths Preferences panel) to ODF header files. If your project is not located in ODFDev, these access paths will be wrong. The build scripts assume your project is in this location.
Using PartMaker
ATTENTION: you must use the PartMaker 4.4.1 provided in the PartMaker folder. Earlier version of PartMaker will not work correctly with the ODF Release 1 templates.
Simply double-click one of the PartMaker templates, and PartMaker will prompt you for information about your new part. Specify the name of your new part and your company name and click on the "Create Part" button. PartMaker will prompt you for the name and location of your new project folder (Save File As:) and then create the project files.
Once you create your part, you should not change the part or company name. PartMaker uses this information in the source code to uniquely identify your part to OpenDoc. If you need to change the name of the part, use PartMaker again to create a new part and copy any new material you had written to the new project.
Once you have your new project (and before you add any new material to the part), open the project in CodeWarrior and build the part. This step allows you to verify that the part was generated correctly and does run. It also allows you to make an alias to the resulting part editor and add it to your Editors folder. See the section Building Your Part, later in this file, for more information on building your part editor.
Adding New Files to Your Project
Once you have a new project, you can add new source files to this project just as you would for any CodeWarrior project. In addition, using the CodeWarrior plugins provided with ODF, you can use CodeWarrior to compile ODF resource files (.fr extension) and IDL files (.idl extension).
Adding ODF Resource Files
ODF resource files are normal text files that have an .fr extension. The ODFRC plugin compiles these files into resources, which then get linked into your part editor.
Using AppMaker for Visual Editing of Views: See the AppMaker folder inside "Tools & Goodies" for a demo version of Bowers Development's AppMaker and information on how to use it with PartMaker to create your part's interface.
Adding IDL Files
The only time you should add IDL files is if your part defines an extension. You should NEVER modify ODF's IDL files, or the IDL files that were generated by PartMaker; use C++ to modify the functionality of your part instead. If you are creating an extension for your part, you can do the following to compile your IDL files:
1) Add the IDL file(s) to your CodeWarrior project.
2) Compile each IDL file individually by selecting the file and pressing Command-K.
3) Add the SOM-generated .cpp file(s) to your CodeWarrior project.
In order to compile IDL files, you have to have ToolServer set up for your CodeWarrior environment. The SOMobjects™ TS plugin is not a stand-alone compiler, but only coordinates the interactions between CodeWarrior and ToolServer to compile your IDL files.
Make sure you have ToolServer installed for your CodeWarrior environment. You must also make sure that you have installed the SOM headers and tools in your ToolServer environment.
Updating Your 'nmap' Resources
Whenever you create a new part, PartMaker creates a set of 'nmap' resources for your part. However, because the content of your part is likely to be different than the default content of the PartMaker part, you must change these resources to reflect your part's content. See the 'nmap', Icon, & Part Signature document in the "Documentation:Development Notes:" folder for more information on how to do this.
Building Your Part
For development, you will want to use the CodeWarrior project that supports debugging. In your project folder, you will find a folder for each of the possible project configurations. To build a debug version of your part for PowerPC, open the project file in the CWPPCDebug folder and choose Make from the Project menu. To build a debug version of your part for 68K, open the project file in the CW68KDebug folder and choose Make. You can build release versions of your part by building the project in the corresponding Release folder.
After CodeWarrior builds your part, make an alias to your part editor and put the alias in your Editors folder. If you do this, you will not have to copy your part to the Editors folder each time you recompile. The alias will automatically lead OpenDoc to the updated part editor file.
Note: Remember that you also have to have the ODFLibrary (or an alias to it) in your Editors folder as well. ODF parts will not run without this library being present.
Running Your Part
To run your part, you need to first create a stationery file for your part editor. You do this by dropping your part editor onto the OpenDoc launcher located inside your system Extensions folder. OpenDoc creates a new stationery file for your part and puts it into your Stationery folder.
To debug your part, open the symbol file for your part in the MW debugger. You may also want to open the symbol file for the ODFLibrary in the debugger as well. You can set breakpoints and the debugger will automatically target your part when it hits the breakpoints.
Double click your part's stationery file to launch your part in a new document. Or, drag your part’s stationery into a containing part (such as ODFDraw) to launch it as an embedded part.
When you ship your part, include the (release) ODFLibrary with it. Users can copy this library into their Exensions folder; users should copy your part editor into their Editors folder. The use of aliases is only for developers to alleviate the need to copy the part editor to the Editors folder after each compile.
Debugging Note: You should be using the MW Debug/MacOS version 1.4.1 or later.
Building ODF
Although ODF is supplied pre-built, you should rebuild it once anyway to create symbol files which are correct for your hard drive. Symbol files contain full paths, and correct ones will make your debugging easier.
To rebuild ODF, run the ODF Builder (CW) application, located in the ODFDev folder. By default it will rebuild debug and release PPC of ODF and all the examples. You can make it also rebuild 68K projects, or not rebuild the examples.
There is another situation where you will need to rebuild ODF: to use CW’s exception handling and Runtime Type Information (RTTI). ODF is set up to use its “emulated” exception handling mechanism and RTTI. This ODF emulated exception mechanism is slower than compiler-generated code, but the CW exceptions cost you around a 10% increase in code size, which we consider unacceptable. If you have code which is speed-critical and are entering try blocks often, try using native exceptions. To use them you need to set the "Enable C++ Exceptions" and "Enable RTTI" checkboxes in the CW project preferences for your part. You also need to rebuild ODF with this same setting. The "Use CW Exceptions & RTTI…" menu item in the ODF Builder will do this step for you. See the "ODF vs Native Exceptions" document for more details.
Remember, you are only rebuilding the ODFLibrary for debugging convenience (to make the MW debugger not ask you where ODF files are located). When you ship your part, you must include the ODFLibrary from the CD, not the one you were building.
