NewtonApplication Development

Newton C++ Tools Users Guide

Apple Computer, Inc. 1997

Apple Computer, Inc. 1997 Apple Computer, Inc. All rights reserved. No part of this publication or the software described in it may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Computer, Inc., except in the normal use of the software or to make a backup copy of the software and any documentation provided on CD-ROM. Printed in the United States of America. The Apple logo is a registered trademark of Apple Computer, Inc. Use of the keyboard Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this book. Apple retains all intellectual property rights associated with the technology described in this book. This book is intended to assist application developers to develop applications only for licensed Newton platforms. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. Apple Computer, Inc. 1 Innite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, AppleTalk, eMate, Espy, LaserWriter, the light bulb logo, Macintosh, MessagePad,

Newton, Newton Connection Kit, and New York are trademarks of Apple Computer, Inc., registered in the United States and other countries. Geneva, NewtonScript, Newton Toolkit, and QuickDraw are trademarks of Apple Computer, Inc. Acrobat, Adobe Illustrator, and PostScript are trademarks of Adobe Systems Incorporated, which may be registered in certain jurisdictions. CompuServe is a registered service mark of CompuServe, Inc. FrameMaker is a registered trademark of Frame Technology Corporation. Helvetica and Palatino are registered trademarks of Linotype-Hell AG and/or its subsidiaries. ITC Zapf Dingbats is a registered trademark of International Typeface Corporation. Microsoft is a registered trademark of Microsoft Corporation. Windows is a trademark of Microsoft Corporation. QuickView is licensed from Altura Software, Inc. Simultaneously published in the United States and Canada.
LIMITED WARRANTY ON MEDIA AND REPLACEMENT If you discover physical defects in the manual or in the media on which a software product is distributed, ADC will replace the media or manual at no charge to you provided you return the item to be replaced with proof of purchase to ADC. ALL IMPLIED WARRANTIES ON THIS MANUAL, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE

LIMITED IN DURATION TO NINETY (90) DAYS FROM THE DATE OF THE ORIGINAL RETAIL PURCHASE OF THIS PRODUCT. Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS MANUAL IS SOLD AS IS, AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modication, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specic legal rights, and you may also have other rights which vary from state to state.

Contents

Preface

About This Book

Conventions Used in This Book Special Fonts

v v v

Chapter 1

Introduction
Porting C++ Code to the Newton Files and Folders File and Folder Naming Conventions Folders The Contents of the Project Folders

1-1 1-2 1-2 1-2 1-3 1-3

Chapter 2

Installing the Newton C++ Tools

Installation Overview Installing MPW Adding the Newton C++ Tools to an Existing MPW Installing Newtsbug Updating Newton Toolkit

2-1 2-2 2-2 2-3 2-3 2-4

Chapter 3

How to Use the Newton C++ Tools

Starting the C++ Tools for the First Time Creating a Project Creating an _NCT Folder and a Project Folder Making a Project the Current Project Setting Up the FilesInBuild File Keeping Code in Sub-Folders Dening a Function Dening the NewtonScript Interface to a Function Creating a Makele Building the C++ Source Importing a C++ Code Module Into an NTK Project Trying Out Project Demos Debugging Customizing the Newton C++ Tools

3-1 3-1 3-2 3-3 3-4 3-5 3-5 3-6 3-7 3-7 3-8 3-8 3-10 3-10 3-11

iii

Chapter 4

The Newton C++ Tools MPW Environment

The Newton C++ Tools Menu Build Current Project Build with Debug Build with NoDebug Build Project Makele Open Project Makele Launch Newtsbug Using... Select NCT Root Directory Reinitialize NCT System Update NCT System From... Create _NCT Folder... Create New Project... Additional Commands in the Find Menu Search Current Directory For... Search Current Directory Search {Active} Folder For... Search {Active} Folder For Search Current Project For... Search Current Project Search Includes For... Search Includes For Search All NCT Projects For... Search All NCT Projects For Search All NCT Folders For... Search All NCT Folders For

4-1 4-1 4-2 4-2 4-3 4-3 4-3 4-3 4-3 4-4 4-4 4-4 4-4 4-4 4-5 4-5 4-5 4-6 4-6 4-6 4-6 4-6 4-6 4-6 4-6 4-7

Chapter 5

MPW Tools
AIFtoNTK DumpAIF

5-1 5-1 5-3

iv

P R E F A C E

About This Book

This book, Newton C++ Tools Users Guide, describes programmer software used to prepare C++ code for inclusion in NewtonScript programs. It has the following chapters:
s s

Chapter 1, Introduction, gives background information. Chapter 2, Installing the Newton C++ Tools, tells you how to install the Newton C++ Tools. Chapter 3, How to Use the Newton C++ Tools, steps you through using the C++ Tools, and includes a tutorial example. Chapter 4, The Newton C++ Tools MPW Environment, describes the menu commands that the Newton C++ Tools adds to MPW. Chapter 5, MPW Tools, discusses the MPW tools included with the C++ Tools.

Conventions Used in This Book

This book uses the following conventions to present various kinds of information.

Special Fonts
This book uses the following special fonts:
s s

Boldface. Key terms and concepts appear in boldface on rst use. Courier typeface. Code listings, code snippets, and special identifiers in the text such as slot names, function names, method names, symbols, and constants are shown in the Courier typeface to distinguish them from regular body text. If you are programming, items that appear in Courier should be typed exactly as shown. Italic typeface. Italic typeface is used in code to indicate replaceable items, such as the names of function parameters, which you must replace with your own names. The names of other books are also shown in italic type, and rarely, this style is used for emphasis.

P R E F A C E

vi

Figure 1-0 Table 1-0

Introduction

Newton C++ Tools allows you to write C++ code that can be called from a NewtonScript program. You need to understand how Newton devices are programmed before you can use this product. In order to use the C++ Tools, you need:
s s

Newton Toolkit (NTK) Apple Macintosh or other Mac OS-based personal computer with a 68030 or later processor, 33Mhz or faster. Any PowerPC Mac OS-based computer will work. Mac OS version 7.1 or later. At least 12 megabytes of RAM. If you have a PowerPC computer, 20 megabytes are recommended. You need 20 megabytes to use MPW, NTK, and Newtsbug simultaneously. A CD-ROM drive A hard disk with at least 25MB of available space A Newton device running the Newton operating system version 2.0 or later Newton Connection Kit for Macintosh v2.0 - Serial cable or Macintosh System Peripheral 8-Cable (M0197LL/B)

s s

s s s s

You develop C++ code using MPW. You then add the code into an NTK project. The C++ functions can then be called from NewtonScript. The C++ Tools package is designed so that you do not need to know much about MPW. If you want to know more, MPW documentation is included on the C++ Tools CD. If you want to use all of the capabilities of MPW, you should order a full version of MPW, including documentation, from ADC (Apples source for developer tools). You can order MPW, NTK, or any other ADC product through these telephone numbers and addresses: From the USA From Canada From other Countries 1-800-282-2732 1-800-637-0029 (716)871-6555

1-1

Introduction

Fax AppleLink Internet CompuServe America Online Regular Mail

(716)871-6511 ADC ADC@applelink.apple.com 76666,2405 ADCorder ADC Apple Computer, Inc. P.O. Box 319 Buffalo, NY 14207-0319 USA

Porting C++ Code to the Newton

You can use the C++ Tools to help port programs to the Newton. However, only computational code can generally be ported to the Newton in the form of C++ code. Newton devices have a user interface that is quite different from desktop computers, so you generally cannot port user interface code. Similarly, Newton devices do not have a le system in the same sense desktop computers do, and memory management issues are somewhat different. In order to take advantage of the Newtons built-in software for the user interface, data storage, and memory management, you generally need to write the code for those portions of your application in NewtonScript. There are also limitations in how C++ code can be written. See the manual Newton C++ Tools Programmers Reference for more information on those limitations.

Files and Folders

The C++ Tools and MPW require certain file and folder names and a certain folder structure in order to operate properly. You may want to come back to this section after installing the Newton C++ Tools and going through the tutorial in Chapter 3, How to Use the Newton C++ Tools.

File and Folder Naming Conventions

The MPW scripts require that les containing C code end in .c, while les containing C++ code end in .cp.

MPW can be confused by certain characters. In general you should limit your folder and le names to letters, digits, spaces, underscores, minus signs, asterisks (*), (option-8), and (option-p). Some other characters are also allowable, but certain ones such as ", ', and denitely are not. See the MPW documentation for information if you want to use unusual characters.

1-2

Porting C++ Code to the Newton

Introduction

Folders
The C++ Tools les and folders go into your MPW folder in the places indicated by Chapter 2, Installing the Newton C++ Tools. You can place the Newtsbug folder anywhere you want. We recommend, though, that you do not put it in the MPW folder. However, Newtsbug has to be in the MPW command path. The easiest way to make sure it is is to put an alias to Newtsbug in the MPW:NCT_Folder:Tools folder, as specied in the installation instructions. The name of this alias must be Newtsbug.

Your code goes into another folder structure that is contained within a root folder. The root folder that is included with the C++ Tools is the NCT_Projects folder. You normally do your code development in the folder hierarchy contained in the NCT_Projects folder. The C++ Tools build system allows you to build a two-level structure inside a root folder. The rst level consists of _NCT folders which have names like Calculator_NCT and Maps_NCT. Each _NCT folder contains one or more projects. The contents of project folders are described in the next section. You do not have to organize your NTK projects this way, but the Newton C++ Tools is set up to have your C++ projects set up in this way.

The Contents of the Project Folders

The project folders contain:
s s

C++ code les NTK les that specify Newton applications (layout les and project les)

IMPORTANT

Development of the NTK part of a project needs to take place in the same folder as you use for C++ development, so that the debugger can nd the les it needs. v
s

Items that the Newton C++ Tools uses to build the package. Those items are: FilesInBuild. This le lists the les that are in the build. It is used by the Build Project Makele command to create a makele for the project. If you create your own makele, you do not need this le. Project.exp. (The first part of the name is the same as the name of the project folder.) You put in information in this le that identies the functions you want to call from NewtonScript. Objects. This folder is used for the object les created and used in your build. Makele. This is the makele for the project.
n

When you use the Create New Project command from the Newton C++ Tools menu in MPW, the Newton C++ Tools creates prototypes for FilesInBuild and project.exp and also creates the Objects folder. The Build Project Makele creates the makele.

Files and Folders

1-3

Introduction

Notes

The Newton C++ Tools menu in MPW lists all the C++ Tools projects in the current projects folder. The build system finds those by looking for folders in the current projects folder that end in _NCT and then looking in each sub-folder for a FilesInBuild le or a Makele. It lists only those folders that contain one or both of those les. In addition, the build system looks in the projects folder for an Debugger_Images folder. It lists Newtsbug images in that folder under the Launch Newtsbug using... command in the Newton C++ Tools menu. x

1-4

Files and Folders

Figure 2-0 Table 2-0

Installing the Newton C++ Tools 2

How you install the Newton C++ Tools depends on whether or not you already have MPW installed. We recommend MPW version 3.4.1 or later. The complete release of Newton C++ Tools includes the six folders shown in Figure 2-1. Note that not all of the folders shown are required for installation. For example, you only need install the contents of Newton C++ Tools with MPW (if you do not already have MPW) or C++ Tools as Additions for MPW (if you already have a full installation of MPW on your system.)

Figure 2-1

Newton C++ Tools Folders

The contents of each of the folders shown in Figure 2-1 are as follows:

2-1

Installing the Newton C++ Tools

Newton C++ Tools with MPW. Contains all of the C++ tools, interfaces, libraries, and sample projects pre-assembled with a minimal version of MPW for a quick-start, drag-and-drop installation. Newton Toolkit 1.6.3 Updater. Contains the latest patch to update Newton Toolkit 1.6 for use with Newton C++ Tools. Documentation. Contains the Acrobat .pdf documentation les for the C++ Programmers Reference and for this manual. Debugging. Contains Newtsbug, a Macintosh-hosted, serial-link Newton debugger, the user manual for Newtsbug, and Newtsbug Connection, the debugging mode start-up package. ROM Images for C++ Tools. Contains the ROM image les used with Newtsbug for various Newton 2.0 devices. C++ Tools as Additions for MPW. A duplicate set of just the required MPW additions you can use if you already have a full installation of MPW on your system that you want to extend with the Newton C++ Tools.

IMPORTANT

The Newton C++ Tools is an add-on product to NTK. You must have NTK installed in order to use Newton C++ Tools. v

Installation Overview
Installation consists of the following procedures: 1. Install MPW and Newton C++ Tools. (If you already have a full installation of MPW on your system, refer to the section Adding C++ Tools to an Existing MPW.) 2. Install Newtsbug. 3. Update NTK to NTK 1.6.3 (if necessary.)

Installing MPW and Newton C++ Tools

To install MPW and Newton C++ Tools: 1. Open the Newton C++ Tools with MPW folder. It contains three folders: MPWforNCT, NCT_Projects, and System Extensions for MPW. 2. Drag the folders MPWforNCT and NCT_Projects to your hard disk. These folders must be in the same folder.

2-2

Installation Overview

Installing the Newton C++ Tools

IMPORTANT

The MPWforNCT folder must NOT be placed inside any folder(s) with names that contain any special characters such as spaces, quote marks, and so on. v If you do not have a PowerPC computer you are done with installing MPW - proceed to step 5 below. If you have a PowerPC computer, you need to install an extension to use MPW as described in steps 1-3: 1. Open the folder System Extensions for MPW. 2. Open the folder Required for Power Macintosh. 3. Drag the extension in that folder, StdCLibInit, to your closed System Folder (the le will be put in Extensions.) 4. Restart your computer. 5. Launch the MPW shell. It will ask you so specify the root directory for NCT: select the NCT_Projects folder. 6. Momentarily, you will see a Newton C++ Tools menu with a pull-right menu for the Demos project at the bottom; select the sub-menu item Demos and you are ready to go.

Adding the Newton C++ Tools to an Existing MPW

If you have a pre-existing installation of MPW on your system, you can add Newton C++ Tools to that environment using the following steps: 1. Open the C++ Tools as Additions for MPW folder. 2. Drag the NCT_Projects folder to your hard disk and put it in the same directory containing your MPW folder. 3. Drag NCTBuildUserPrefs, UserStartupNewtonC++Tools, and NCT_Folder into your MPW folder. 4. Type the following line in your MPW Worksheet: execute {MPW}UserStartupNewtonC++Tools

Installing Newtsbug
You use Newtsbug to debug C++ programs on the Newton. To install Newtsbug: 1. Drag the Debugging folder to your hard disk. 2. On your hard disk, make an alias to the Newtsbug program that is in that folder. 3. Open the NCT_Folder on your hard disk. 4. Drag the alias to Newtsbug into the Tools folder that you nd in the NCT_Folder.

Adding the Newton C++ Tools to an Existing MPW

2-3

Installing the Newton C++ Tools

The Newton C++ Tools build system is now installed.

Updating Newton Toolkit

The Newton Toolkit (NTK) must be version 1.6.3 or later to be used with Newton C++ Tools. If necessary, run the Newton Toolkit 1.6.3 Updater.

2-4

Updating Newton Toolkit

Figure 3-0 Table 3-0

How to Use the Newton C++ Tools

This chapter steps you through using the C++ Tools, MPW, and NTK to:
s s

Create a small C++ function Combine it with a Newton application that calls the function

Starting the C++ Tools for the First Time

The C++ Tools MPW start-up les need to know where on your disk youll be working. It uses that information to build its menus. 1. Find the MPW folder and open it.

2. Double-click on the MPW icon. The start-up script begins executing. After a few moments, you see a dialog box that tells you you need to select a root folder. The C++ Tools needs a root directory. It looks in that directory for your projects. 3. Click OK to dismiss the dialog box. 4. Pull down the NCTSetup menu. It is shown in Figure 3-1.

Figure 3-1

NCTSetup Menu

5. Choose the Select Root Directory command. MPW displays a standard le dialog box.

Starting the C++ Tools for the First Time

3-1

How to Use the Newton C++ Tools

6. Find the NCT_Projects folder and choose it. The C++ Tools start-up les continue processing. They build the Newton C++ Tools menu. When processing is done, the menu should look like the one shown in Figure 3-2.

Figure 3-2

Newton C++ Tools Menu

Creating a Project
The basic unit of Newton application development is a project. A project contains various les used and produced by NTK as well as the les used and produced by the C++ Tools. You do all C++ and NewtonScript development for an application within a single project.

Before you create a project, you need to create a place to put it. The C++ Tools allows for a three-level hierarchy, which is intended to help you keep multiple projects neatly organized:
s

The top level of the hierarchy is the root directory, which was the folder you chose in the preceding section; if you want to create an additional root directory, do it from the Mac OS Finder. You normally just use the NCT_Projects folder, because it contains the includes and Library les that you need. The second level of the hierarchy is made up of folders with names that end in _NCT. These folders have special meaning to the C++ Tools, as you will soon see. You use a menu command described in this section to create these folders. The lowest level of the hierarchy is made up of project folders. You use a menu command described in this section to create those folders, also.

3-2

Creating a Project

How to Use the Newton C++ Tools

Look again at the menu in Figure 3-2. The last item in the menu is Demos_NCT. This is an NCT folder that contains the Demos application, which is a sample Newton application you can build and use. If you look at the submenu contained in the Demos_NCT item, you will see that it contains one project, Demos.

Creating an _NCT Folder and a Project Folder

You now need to create a new _NCT folder to hold the new example application, and then create a project for the application. 1. Choose the Create _NCT Folder... command from the Newton C++ Tools menu. A dialog box displays. 2. In the dialog box, type: Example Notice that you do not type the _NCT endingthe C++ Tools adds that for you. You can have any number of _NCT folders. 3. Click in the OK button. 4. Choose the Create New Project... command from the Newton C++ Tools menu. A dialog box displays. 5. In the dialog box, type: Example This name doesnt have to be the same as the _NCT folder name. 6. Click in the OK button. 7. A dialog box asks you where to put the new project. Choose Example_NCT. Youve created a new project. Each _NCT folder can contain any number of projects. The C++ Tools informs you that youve created a new project by showing the dialog in Figure 3-3. The dialog tells you what the C++ Tools has done and gives general directions for what you need to do to continue.

Figure 3-3

New Project Dialog

Creating a Project

3-3

How to Use the Newton C++ Tools

Every C++ Tools project needs a .exp le. That le lists your module name and function names, and denes the interface used to call your functions from NewtonScript. The FilesInBuild le lists the les that make up the C++ part of your project. You need to have this le in order to use the C++ Tools command that creates the build instructions (makele) for your project. When you create a new project, the C++ Tools creates prototypes for these les. They contain instructions that tell you how to place your information in the les. 8. Click OK to dismiss the dialog.

Making a Project the Current Project

C++ Tools commands apply to the current project. To make the new project the current project: 1. Pull down the Newton C++ Tools menu. You will see an Example_NCT item at the bottom of the menu. 2. Pull down until you select Example_NCT. Youll see a menu item that says Example, as shown in Figure 3-4.

Figure 3-4

Menu Showing New _NCT Folder

3. Choose Example. If you pull down the menu again, youll see that Example_NCT and Example are now underlined, which indicates that Example is the current project. In addition to making this project the C++ Tools current project, choosing a project in this way sets the MPW current directory to be the project directory.

3-4

Creating a Project

How to Use the Newton C++ Tools

Setting Up the FilesInBuild File

As mentioned before, the FilesInBuild le lists the les that make up the C++ part of your project. You need to have this le in order to use the C++ Tools command that creates the build instructions for your project. To set up FilesInBuild for the example application:

1. Use the File menus Open command to open FilesInBuild. What you see should look like Figure 3-5. Comment lines begin with a pound sign (#). Notice that the le has comments that tell you where to put your information. 2. Type Example.cp in the place where the comments indicate source le names should go, which is indicated by the arrow in Figure 3-5.

Figure 3-5

Default FilesInBuild File

Add file names here

3. Save and close the le.

Keeping Code in Sub-Folders

You can have code in sub-folders in your project folder. In that case, you need to give the folder names in the FilesInBuild le. Notice the line in Figure 3-5 that looks like this: -srcdirs ':' You need to list your subfolders in this line. Suppose you have a single subfolder called MyCode. Modify the line so that it looks like this:

Creating a Project

3-5

How to Use the Newton C++ Tools

-srcdirs ': :MyCode:' Notice that the list of folders is surrounded by single quote marks. Suppose you have two subfolders. You separate their names with a space: -srcdirs ': :MyCode1: :MyCode2:' If a folder name contains spaces, you need to surround the name with double-quote marks like this: -srcdirs ': :MyCode1: :MyCode2: ":MyCode Additions:"'

Dening a Function
To dene the function for this example: 1. Use the New command in the File menu to create a new le. 2. Type this code in the new les window: #include "objects.h" extern "C" Ref SillyString(RefArg) { RefVar num = MakeInt(49); return num; }
Note

You should generally dene your functions as extern "C". If you do not do this, the compiler issues a mangled name for the function. You then need to specify the mangled name in the Example.exp le, which is discussed in the next section. You would also have to use the C++ mangled names when calling the functions from NewtonScript. (C++ uses mangled names to accommodate methods and overloaded functions. A mangled name includes the function name plus its class name and arguments.) You may use mangled names if you wish, but since the mangled names are compiler-dependent and function-signature dependent, you will have to discover and maintain the mangled names yourself; the DumpAOF tool is useful for displaying such names. x 3. Save the le as Example.cp. 4. Close the le.

3-6

Dening a Function

How to Use the Newton C++ Tools

Dening the NewtonScript Interface to a Function

You need to tell the build system which functions can be called from NewtonScript. You do that using the .exp le.

1. Use the File menus Open command to open the Example.exp le. It looks like the le shown in Figure 3-6.

Figure 3-6

Example.exp File

The rst line gives the module name. The C++ Tools build system assumes the module name is the same as the project name. You can change this line if you want to use a different module name. Each .exp le, and therefore each project, can only contain one module. In .exp les, comment lines begin with a semicolon (;). Notice that the comments tell you where to add the names of your NewtonScript interface functions. 2. In the place indicated in the le for interface functions, type: SillyString Press Return. You must always have a return character at the end of every line in this le. If you omit this trailing carriage return, you will get a link error for the last symbol in your module minus its last character. 3. Close and save the le.

Creating a Makele
The MPW make tool uses makeles to govern building programs. 1. Select the Newton C++ Tools menu item Build Project Makele . A window named BuildResults opens and the scripts to create an MPW makele begin executing.

Dening the NewtonScript Interface to a Function

3-7

How to Use the Newton C++ Tools

2. Close the BuildResults window.

Note

The le shown in the BuildResults window is not automatically saved when you close it. If you want to save the position and size of the window, you can use the Save command to save the le. If there is anything in the window, though, anything new will be appended to the windows contents. Therefore, in order to save the position and size of the window, delete the contents of the window before using the Save command. x

Building the C++ Source

This step uses the makele to build the project: 1. From the Newton C++ Tools menu select the menu item Build Current Project . The Build Results window appears again; messages begin as the Newton C++ Tools build system caches your prior results in the folder YourOldBuildResults: and then a Makeout window opens as the source is compiled and linked . You now have the le Example_NCT:Example:Objects:Example.ntkc which has been rebuilt with a new value for the C function called from the NTK application.
IMPORTANT

Development of the NTK part of a project needs to take place in the same folder as you use for C++ development, so that the debugger can nd the les it needs. v

Importing a C++ Code Module Into an NTK Project

You need to have NTK installed on your hard disk. See NTK documentation for information on using NTK and on developing NewtonScript applications. 1. Select the Finder. 2. Open the NCT_Projects folder and then the enclosed folder Files for Users Guide Tutorial. 3. Select the Example.t and Example. les and drag them into the Example folder which you created earlier.. These are les that dene the NewtonScript part of a small application that you are going to use to call SillyString.

4. Double click Example.. NTK starts and opens the Example project. The project shows only one le: Example.t. (Example.t is the layout le. See the NTK documentation for information on layout les.)

3-8

Building the C++ Source

How to Use the Newton C++ Tools

5. Select the Add le... menu item from the Project menu. 6. Navigate to the Objects folder and select the le Example.ntkc. Click on Add. This adds the C++ code module le to the NTK project. 7. Click on the Example.ntkc le to select it and then choose the Process Earlier command from the Project menu. This command makes sure that the C++ module is processed before the NewtonScript module. 8. Choose the Open command. 9. Select Example.t, and click on Open. This is the layout le for this project. An Example.t Browser window opens. 10. In the browser window, choose clView: Top. The right side of the window shows the slots of clView. 11. Select viewSetupFormScript. In the lower part of the browser, you can see the code for viewSetupFormScript. 12. Notice where in the code the number 42 appears. If you built the package now and downloaded it to a Newton, the application would print the number 42. 13. Replace the number 42 with: call Example.SillyString with (); This is the way you call a C++ function from NewtonScript: moduleName.functionName with (arguments) 14. Close and save the le. 15. From the Project menu, select the Build Package item. This command builds the project including the .ntkc module. If you have your NTK preferences set to automatically download after building and you connected a Newton device to the Mac OS-based computer, NTK attempts to download the Test package to your Newton device. Alternatively, if you have loaded the Toolkit App into the Newton device, you can select it from the Extras drawer and download your Test package. 16. Once you have downloaded the package you can run the package. It displays a simple message that contains the number 49. When you are building interface functions to be called from NewtonScript with the C++ compiler, you should dene those functions as extern "C". If you do not, the C++ compiler will mangle the function names and you must enter the mangled names in the project.exp file and must use the C++ mangled names when calling the functions from NewtonScript. (C++ uses mangled names to accommodate methods and overloaded functions. A mangled name includes the function name plus its class name and arguments.) In addition, when you do not used mangled function names, the Newton C++ Tools build process determines the number of RefArg arguments that each interface function requires automatically and passes this information to NTK. If you use

Importing a C++ Code Module Into an NTK Project

3-9

How to Use the Newton C++ Tools

mangled function names, the function name will change if the number of arguments changes. You may use mangled names if you wish, but since the mangled names are compiler-dependent and function-signature dependent, you will have to discover and maintain the mangled names yourself; the DumpAOF tool is useful for displaying such names.

Trying Out Project Demos

Demos is a more complex sample program that is included in NCT_Projects. It already has all the code it needs and has a make le. To try it out, you just need to:
s

Make it the current project as shown in Making a Project the Current Project on page 3-4 Create a makele as shown in Creating a Makele on page 3-7 Build it as shown in Building the C++ Source on page 3-8 Start NTK, add the .ntkc le to the NTK project, build the NTK project, and download the resulting package, as shown in Importing a C++ Code Module Into an NTK Project on page 3-8

s s s

Debugging

You use the NTK Inspector to debug the NewtonScript portions of your program, but you cannot use it for the C++ portions. Instead, you use Newtsbug, which allows you to debug code at the ARM assembler level. Newtsbug is included with the C++ Tools. Newtsbug and the Inspector are two independent debugging systems, and they do not interconnect. In order to set up to use Newtsbug, create an alias of the package le that is produced by NTK and place the alias in the Newtsbug folder. The package le ends with the extension .pkg. See the Newtsbug Users Guide for more information.

3-10

Trying Out Project Demos

How to Use the Newton C++ Tools

Note

You need to read this note only if you write your own makeles or move the package le that NTK produces. Newtsbug needs to have symbol information in order to debug a package. Symbol information is generated by the compiler whether you compile with debugging on or off, and is contained in the .sym le. The package le contains information that denes where the .sym le is located, using a path relative to the .pkg le. The makeles created by the Newton C++ Tools place .sym les in the Objects folder that is in the project folder. Therefore, although you can move the .pkg le and the .sym le after you build your package, you must keep the relative path from the .pkg le to the .sym le the same if you want to use Newtsbug. In other words, the folder that contains the .pkg le should contain an Objects folder, and the .sym le should be in that folder. v

Customizing the Newton C++ Tools

In the MPW folder, there is an MPW shell le called NCTBuildUserPrefs that contains various things that an expert MPW user might want to change. You can look at that le for information. In general, before making any changes, you should make a copy of the original so you can restore it if necessary.

One thing in the le is information on the SendAE tool, which you can use to send Apple events from MPW to other applications, such as NTK. This allows you to have MPW tell NTK to automatically re-build the NTK project when you re-build the MPW project.

Customizing the Newton C++ Tools

3-11

How to Use the Newton C++ Tools

3-12

Customizing the Newton C++ Tools

Figure 4-0 Table 4-0

The Newton C++ Tools MPW Environment

You develop and process code for the C++ Tools using MPW. MPW is a programming environment that is similar in many ways to UNIX, in that it uses a command-line shell and has a fairly complex shell programming language. The C++ Tools build system includes scripts written in this shell language that simplify the process of building projects. These scripts are executed using commands in the Newton C++ Tools menu. When you start up MPW with the Newton C++ Tools start-up les included in the MPW folder, the start-up les add the Newton C++ Tools menu and also add some commands to the Find menu. These menu commands are described in this chapter. See the MPW documentation for more information. The MPW documents are included on the Newton C++ Tools release CD.

The Newton C++ Tools Menu

The Newton C++ Tools MPW start-up les add a menu to MPW. Figure 4-1 shows the menu.

The Newton C++ Tools Menu

4-1

The Newton C++ Tools MPW Environment

Figure 4-1

The Newton C++ Tools Menu

The menu items in the last division of the menu vary; that division shows all of the _NCT folders in the root directory. The _NCT folder that contains the current project is underlined in the submenu. You change the current project by selecting a new one from the submenu. The rest of this section describes the menu commands. You may want to see Chapter 3, How to Use the Newton C++ Tools, for information on using these commands.

Build Current Project

When you choose this command, MPW uses the makele to build the project. (You must already have a makele, of course. You can create one using the Build Project Makele command.)

Build with Debug

This menu item sets the makele so that when you build the project again it is built with the compilers debug switch on. This switch is used by the compilers preprocessor. You can have sections of your code that begin with: #ifdef forDebug These sections should end with: #endif When you build with debug, these sections are included in the compilation. This is the initial mode.

4-2

The Newton C++ Tools Menu

The Newton C++ Tools MPW Environment

Note

Whenever you use DebugPrint and printf, those functions should be enclosed within #ifdef forDebug and #endif. If you do not do that, compilation will fail when you build with NoDebug. x

Build with NoDebug

This menu item sets the makele so that when you build the project it is built with the compilers debug switch off, which excludes the parts marked with #ifdef forDebug and #endif. Symbol information that is used by the debugger, Newtsbug, is still included in the object le. The object le is placed in the folder ObjectsNoDebug, instead of the Objects folder. (ObjectsNoDebug is created, if necessary.) After you build with NoDebug, you need to use the NTK Add File command to add the NoDebug version of the .ntkc le to the project.

Build Project Makele

This menu item creates a makele for the current project. In general, you do not need to modify the resulting makele.

Open Project Makele

This menu item opens a window showing the current projects makele.

Launch Newtsbug Using...

This menu item has a submenu that lets you choose the ROM image to use and then runs Newtsbug, the debugger that you use with the Newton C++ Tools. See the Newtsbug Users Guide for information on using Newtsbug.
Note

There needs to be an alias to Newtsbug in the Tools folder, as described in Installing Newtsbug on page 2-3. x

Select NCT Root Directory

This menu item sets the root directory. MPW rebuilds the last menu items to reect the projects that are in that directory. You dont usually need to use this command; you just need to use it if you have your project folders grouped under different root directories because, for example, they are on different volumes.

The Newton C++ Tools Menu

4-3

The Newton C++ Tools MPW Environment

Reinitialize NCT System

This menu item reruns the MPW start-up le that sets up the Newton C++ Tools system. You only need to use this command when youve added new start-up les without re-starting MPW.

Update NCT System From...

This menu item lets you update your C++ Tools build system from an update CD. It displays a standard le dialog box. You navigate to the Newton C++ Tools CD and locate the folder named MPW Additions. When you click on Open, the installed version of C++ Tools is updated.

Create _NCT Folder...

This menu item lets you create subfolders in your top-level NCT_Projects folder, so that you can divide your projects into convenient groups. Enter the name of the projects folder you wish to create and a subfolder of that name is added to your NCT_Projects folder. Dont include the sufx _NCT; that is automatically added for you. _NCT folders are intended to be used to organize your projects. You put groups of related projects in a single _NCT folder.

Create New Project...

Use this to create a new project folder within the current projects folder. The project name must not contain any spaces, because the name will be used as a C++ module name.

The Newton C++ Tools build system creates the folder, unless one already exists with that name. Within that folder, it creates prototypes for the les and folders that you need. Specically, this command creates a prototype FilesInBuild le, an Objects folder, and a prototype .exp le. See The Contents of the Project Folders on page 1-3 for information on these items.

Additional Commands in the Find Menu

Figure 4-2 shows the Find menu. The commands in the top two divisions are standard MPW commands; see the MPW documentation for information on those commands.

4-4

Additional Commands in the Find Menu

The Newton C++ Tools MPW Environment

Figure 4-2

The Find Menu

The additional commands are not specic to the C++ Tools, but are powerful and helpful search commands. v WA R N I N G You should not enter search strings that contain MPW escape characters such as (option-d). This character can cause problems with searching; for example, n causes the search commands to go into an innite loop. v

Search Current Directory For...

This menu command puts up a dialog box that asks for text to search for. The search is limited to the current directory. It does not search sub-directories.

Search Current Directory

The symbol refers to the current selection. This menu command searches the current directory for other occurrences of the current selection. It does not search sub-directories.

Search {Active} Folder For...

This menu command puts up a dialog box that asks for text to search for. The search is limited to the currently active folder, which is the folder containing the le that is shown

Additional Commands in the Find Menu

4-5

The Newton C++ Tools MPW Environment

in the active window. (Technically, this is the folder whose name is contained in the MPW variable {Active}. See the MPW documentation for more information on MPW variables.) This command does not search sub-directories.

Search {Active} Folder For

This menu command searches the active directory for other occurrences of the current selection. It does not search sub-directories.

Search Current Project For...

This menu command puts up a dialog box that asks for text to search for. It searches the current projects directory, including sub-directories.

Search Current Project

This menu command searches for other occurrences of the current selection in the current projects directory, including sub-directories.

Search Includes For...

This menu command puts up a dialog box that asks for text to search for. It searches the Includes directory, including sub-directories.

Search Includes For

This menu command searches for other occurrences of the current selection in the Include directory, including sub-directories.

Search All NCT Projects For...

This menu command puts up a dialog box that asks for text to search for. It searches all project directories in the current _NCT directory, including sub-directories.

Search All NCT Projects For

This menu command searches for other occurrences of the current selection in all project directories in the current _NCT directory, including sub-directories.

Search All NCT Folders For...

This menu command puts up a dialog box that asks for text to search for. It searches all directories in the current root directory, including sub-directories.

4-6

Additional Commands in the Find Menu

The Newton C++ Tools MPW Environment

Search All NCT Folders For

This menu command searches for other occurrences of the current selection in all project directories in the current root, including sub-directories.

Additional Commands in the Find Menu

4-7

The Newton C++ Tools MPW Environment

4-8

Additional Commands in the Find Menu

Figure 5-0 Table 5-0

MPW Tools

The Newton C++ Tools contains a number of MPW tools. You generally do not have to know that much about these tools; the Newton C++ Tools menu commands build a make le that calls these tools for you. See the Tools folder for the complete set of tools. The most important are:
s

AIFtoNTK, which converts the link le into a form that can be incorporated in a Newton program. See AIFtoNTK below for information. ARM6asm assembler. See the ARM documentation for information. ARM6c C compiler. See the ARM documentation for information. ARMCpp C++ compiler. See the ARM documentation for information. ARMLink linker. . See the ARM documentation for information. DumpAOF, which emits code in ARM Object Format. Sophisticated programmers may nd this useful for debugging code. See the ARM documentation for information. DumpAIF, which dumps the output format from the linker, and is analogous to the MPW tool DumpCode. See DumpAIF on page 5-3 for information.

s s s s s

If you want to see the available options (and short descriptions) for most of the tools, you can execute: toolname -help on the MPW worksheet. For some tools, you can also simply give an invalid option to see the help information.

AIFtoNTK
This tool is invoked for you by the Newton C++ Tools scripts, and you should not need to understand its options yourself. This section is informational only.

AIFtoNTK

5-1

MPW Tools

AIFtoNTK [-p] -via exportsFile -o outputFile inputFile This tool converts an ARM Image Format (AIF) le into an NTK streamed frame le. -p -via exportsFile This is an optional parameter that requests the display of progress messages to Dev:Stderr. Species the path of an exports list le. When you use the C++ Tools menu commands, they build a prototype exports le; you ll in the le with the information you need. The exports le is a normal text le that contains lines of text. The rst line must contain the module name. Subsequent lines each contain a single function name. These are the names of functions that you want to be able to call from NewtonScript. Each function name must be the rst non-blank text on the line and there must be one function name per line. You can also have comment lines that begin with a semicolon (;); those lines are ignored. You use the module name in NewtonScript call statements when invoking a function in the module. For example: call modulename.function1 with (....) -o outputFile Species the path of the output le to be created. If the le already exists, its contents will be destroyed. The normal convention is to use the same name as the input le with the sufx .ntkc added . Species the path of the input le to be converted into a .ntkc le for use by Newton Toolkit. You can only give one input le. You must give an input le; AIFtoNTK ignores standard input.

inputFile

None of the parameter pathnames can contain aliases; the tool will not resolve the aliases. The AIFtoNTK tool converts the data fork of the AIF le created by the ARMLink tool into a streamed frame format le which is accepted as input by the NTK. The binary image of the read-only code and the table of relocations or x ups are converted into binary objects within the streamed frame. The tool checks for signatures in the le data fork to verify that the input le is an ARM Image Format le. AIFtoNTK can return the following status codes. 0 1 2 3 no errors; output le created. usage, syntax or missing or invalid parameter error. execution error; usually invalid data encountered in input le internal or fatal error; usually system or memory overow

5-2

AIFtoNTK

MPW Tools

Here is an example of the use of this tool: AIFtoNTK -via mymodule.exp -o mymodule.ntkc mymodule

DumpAIF
This is a tool for advanced users who want to see the linker output code. DumpAIF [-s] filename

The command displays the contents of the AIF le filename. The -s option adds a symbol table.

DumpAIF

5-3

MPW Tools

5-4

DumpAIF

Index
Symbols
#ifdef forDebug 4-2 _NCT folder creating 3-3 name 3-3 position in hierarchy 1-3 project folders 3-3 shown in the Newton C++ Tools menu 4-2 C++ Tools and NTK 2-2 customizing 3-11 le names expected 1-2 installing 2-3 to ?? project hierarchy 3-2 reinitializing 4-4 starting 3-1 updating 4-4 calling a C++ function from NewtonScript 3-7, 3-9 C compiler 5-1 choosing the ROM image used by Newtsbug 4-3 code les location 1-3 conditional compilation for debugging 4-2 Courier typeface meaning v Create _NCT Folder... command 3-3, 4-4 Create New Project... command 3-3, 4-4 current directory searching 4-5 current project 3-4 changing 4-2 shown in Newton C++ Tools menu 4-2 current selection searching for 4-5 to 4-7

A
Add le... command in NTK 3-9 AIFtoNTK 5-1 to 5-3 alias to Newtsbug 2-3 ARM6asm assembler 5-1 ARM6c C compiler 5-1 ARMCpp C++ compiler 5-1 ARM Image Format (AIF) le 5-2 ARMLink linker 5-1

B
Boldface type meaning v Build Current Project command 3-8, 4-2 Build Package command in NTK 3-9 Build Project Makele command 3-7, 4-3 BuildResults window 3-8 Build with Debug command 4-2 Build with NoDebug command 4-3

D
debugger see Newtsbug debugging using conditional compilation 4-2 using printf and DebugPrint 4-3 Demos sample program 3-10 directory names and structure 1-3 DumpAIF 5-3 DumpAOF 5-1 to see mangled names 3-6

C
C++ building the source le 3-8 calling from NewtonScript 3-7, 3-9 compiler 5-1 mangled names 3-6

E
escape characters in MPW search strings 4-5 existing C++ code, porting 1-2

IN-1

I N D E X

.exp le comment lines 3-7 requirement for 3-4 using 3-7 extern "C" 3-6, 3-9

M
makele creating 3-7 to 3-8, 4-3 opening 4-3 use in building the project (Build Current Project command) 3-8, 4-2 mangled names 3-6, 3-9 module name dened in .exp le 3-7 MPW 4-1 to 4-7 and Newtsbug 1-3 characters usable in le and folder names 1-2 command path 1-3 customizing 3-11 escape characters in search strings 4-5 le names expected 1-2 folder 2-2 installing 2-2 version recommended 2-1 MPW Additions folder 2-3 multiple projects, organizing 3-2

F
File menu 3-5, 3-6 le names expected by C++ Tools and MPW 1-2 FilesInBuild le description 3-4 opening 3-5 setting up 3-5 using to specify sub-folders 3-5 Find Menu 4-4 to 4-7 folders names and structure 1-2 to 1-3 searching 4-5 to 4-7 function calling from NewtonScript 3-9 dening 3-6 dening how it is called from NewtonScript 3-7 extern "C" 3-6 mangled names 3-6

N
NCT_Projects folder 2-3, 3-2 adding projects 4-4 NCTBuildUserPrefs 2-3, 3-11 NCTSetup menu 3-1 New command 3-6 Newton C++ Tools menu 3-2, 3-3, 3-4, 3-7, 4-1 to 4-4 _NCT folders shown in 4-2 showing current project 4-2 NewtonScript interface to a function dening 3-7 using 3-9 Newtsbug 3-10 to 3-11 alias to 1-3 choosing the ROM image used 4-3 installing 2-3, 2-4 location 1-3 need to nd les 3-8 setting up 1-3 NTK 3-8 and C++ Tools 2-2 downloading a package 3-9 location of les 1-3

I
Includes searching 4-6 installing C++ Tools 2-3 to ?? MPW 2-2 Newtsbug 2-3, 2-4 Italic typeface meaning v

L
Latest MPW folder 2-2 Launch Newtsbug Using... command 4-3 linker 5-1 viewing output code 5-3

O
Open command 3-5

IN-2

I N D E X

Open Project Makele command 4-3

P
package downloading 3-9 porting C++ code 1-2 printf using 4-3 Process Earlier command in NTK 3-9 project 1-3, 3-2 creating 4-4 how the current one is indicated 4-2 searching 4-6 setting the current project 4-2 project folder and project name 1-3 contents 1-3 creating 3-3 having sub-folders 3-5 position in folder hierarchy 3-2 setting current project 3-4 project hierarchy 3-2 Project menu in NTK 3-9

Search {Active} Folder For... command 4-5 Search All NCT Folders For command 4-7 Search All NCT Folders For... command 4-6 Search All NCT Projects For command 4-6 Search All NCT Projects For... command 4-6 Search Current Directory command 4-5 Search Current Directory For... command 4-5 Search Current Project command 4-6 Search Current Project For... command 4-6 Search Includes For command 4-6 Search Includes For... command 4-6 selection searching for 4-5 to 4-7 Select NCT Root Directory command 4-3 Select Root Directory command 3-1 semicolon use in .exp les for comments 3-7 SillyString calling from NewtonScript 3-9 dening 3-6 dening the NewtonScript interface 3-7 downloading 3-9 starting the C++ Tools 3-1 StdCLibInit 2-3 System Additions folder 2-2

R
recommended version of MPW 2-1 Reinitialize NCT System command 4-4 Required for MPW folder 2-3 ROM image choosing which Newtsbug uses 4-3 root directory changing 4-3 choosing 3-1 place in project hierarchy 3-2

T
Toolkit App 3-9 tools seeing options of 5-1 Tools folder 2-3 typefaces meanings v

U
update CD updating an existing C++ installation 4-4 Update NCT System From... command 4-4 UserStartupNewtonC++Tools 2-3

S
sample function building 3-7 calling from NewtonScript 3-9 dening 3-6 dening the NewtonScript interface 3-7 downloading 3-9 sample program Demos 3-10 Save command 3-8 Search {Active} Folder For command 4-6

IN-3

T H E

A P P L E

P U B L I S H I N G

S Y S T E M

This Apple manual was written, edited, and composed on a desktop publishing system using Apple Macintosh computers and FrameMaker software. Proof pages were created on an Apple LaserWriter Pro 630 printer. Final page negatives were output directly from the text and graphics les. Line art was created using Adobe Illustrator. PostScript, the page-description language for the LaserWriter, was developed by Adobe Systems Incorporated. Text type is Palatino and display type is Helvetica. Bullets are ITC Zapf Dingbats. Some elements, such as program listings, are set in Apple Courier.
WRITER

Jonathan Simonoff
ILLUSTRATOR

Peggy Kunz
EDITOR

MP McKowen
PRODUCTION EDITOR

Gerry Kane
PROJECT MANAGER

Gerry Kane