OpenDoc Development Framework Build Guide for CodeWarrior ODF Release 2 This document gives instructions for creating new parts and building them with Metrowerks CodeWarrior. Table of Contents ------------------------- ¥ Creating a New Part ¥ Using PartMaker Pro ¥ Adding New Files to Your Project ¥ Adding ODF Resource Files ¥ Adding IDL Files ¥ Updating Your 'nmap' Resources ¥ Building Your Part ¥ Running Your Part Creating a New Part Whenever you want to create a new part, use PartMaker Pro to generate your initial project. PartMaker Pro is located in the PartMaker folder and contains seven templates: three for creating non-embedding parts based on the ODFHello, ODFForm, and ODFNothing examples; three for creating embedding parts based on ODFContainer, ODFEmbed, and ODFTable; and one to create a Cyberdog-savvy part. Choose the template whose features most closely match your part and do the following: 1) Use PartMaker Pro 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 paths in the generated project assume that your project is located there. Using PartMaker Pro PartMaker Pro 1.2, distributed with this release of ODF, requires the presence of StuffIt Expanderª from Aladdin Systems. StuffItExpander can be downloaded from the Aladdin Systems website at . To generate a part from a template, simply double-click the PartMaker Pro application and follow the on-screen information. For more details you can read the 'PartMaker ReadMe' document located in the same folder. Once you create your part, you should not change the part or company name. PartMaker Pro 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 Pro 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), 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. Note: the two files called 'Part.Cust' and 'Part.Info' can be deleted. They are used by PartMaker Pro to generate your project and are not used after that. 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, in conjunction with 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's shared library. Adding IDL Files The only time you should add IDL files to your project is when 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 merely 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. Please see the document "Compiling IDL Files" located in the "Documentation:Development Notes:" folder for information about IDL files and setting up the SOM compiler. 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 must also have the ODFLibrary (or an alias to it) in your Editors folder. ODF parts will not run without this library being present. Running Your Part To run your part, you need to create a stationery file for your part editor. To do this, drop your part editor onto the OpenDoc launcher located inside the "System Folder:Extensions:OpenDoc Libraries" folder of your machine. 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. If you set breakpoints in your part's code, 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 official ODFLibrary (release, fat version) 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. © 1993 - 1996 Apple Computer, Inc. All rights reserved. Apple, the Apple Logo, Macintosh, and OpenDoc are trademarks of Apple Computer, Inc., registered in the United States and other countries.