newton c++ tools user’s guide

7/29/2019 Newton C++ Tools Users Guide

1/42

N e w t o n A p p l i c a t i o nD e v e l o p m e n t

Newton C++ Tools Users Guide

Apple Computer, Inc. 1997


2/42

Apple Computer, Inc. 1997 Apple Computer, Inc.All rights reserved.

No part of this publication or thesoftware described in it may bereproduced, stored in a retrievalsystem, or transmitted, in any formor by any means, mechanical,electronic, photocopying,recording, or otherwise, withoutprior written permission of AppleComputer, Inc., except in thenormal use of the software or tomake a backup copy of thesoftware and any documentationprovided on CD-ROM. Printed inthe United States of America.

The Apple logo is a registeredtrademark of Apple Computer, Inc.Use of the keyboard Apple logo(Option-Shift-K) for commercialpurposes without the prior writtenconsent of Apple may constitutetrademark infringement and unfaircompetition in violation of federaland state laws.

No licenses, express or implied, aregranted with respect to any of thetechnology described in this book.Apple retains all intellectualproperty rights associated with thetechnology described in this book.

This book is intended to assistapplication developers to developapplications only for licensedNewton platforms.

Every effort has been made toensure that the information in thismanual is accurate. Apple is notresponsible for printing or clericalerrors.

Apple Computer, Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, AppleTalk,

eMate, Espy, LaserWriter, the lightbulb logo, Macintosh, MessagePad,

Newton, Newton Connection Kit,and New York are trademarks ofApple Computer, Inc., registered inthe United States and other

countries.Geneva, NewtonScript, NewtonToolkit, and QuickDraw aretrademarks of Apple Computer, Inc.

Acrobat, Adobe Illustrator, andPostScript are trademarks of AdobeSystems Incorporated, which may

be registered in certainjurisdictions.

CompuServe is a registered servicemark of CompuServe, Inc.

FrameMaker is a registeredtrademark of Frame TechnologyCorporation.

Helvetica and Palatino areregistered trademarks ofLinotype-Hell AG and/or itssubsidiaries.

ITC Zapf Dingbats is a registeredtrademark of InternationalTypeface Corporation.

Microsoft is a registered trademarkof Microsoft Corporation.Windows is a trademark ofMicrosoft Corporation.

QuickView is licensed fromAltura 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 thismanual, 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

modification, 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 specific legal rights,

and you may also have other rights

which vary from state to state.


3/42

iii

Preface

About This Book

v

Conventions Used in This Book vSpecial Fonts v

Chapter 1

Introduction

1-1

Porting C++ Code to the Newton 1-2Files and Folders 1-2

File and Folder Naming Conventions 1-2Folders 1-3The Contents of the Project Folders 1-3

Chapter 2

Installing the Newton C++ Tools

2-1

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

Chapter 3

How to Use the Newton C++ Tools

3-1

Starting the C++ Tools for the First Time 3-1Creating a Project 3-2

Creating an _NCT Folder and a Project Folder 3-3Making a Project the Current Project 3-4Setting Up the FilesInBuild File 3-5Keeping Code in Sub-Folders 3-5

Defining a Function 3-6

Defining the NewtonScript Interface to a Function 3-7Creating a Makefile 3-7Building the C++ Source 3-8Importing a C++ Code Module Into an NTK Project 3-8Trying Out Project Demos 3-10Debugging 3-10Customizing the Newton C++ Tools 3-11

Contents


4/42

iv

Chapter 4

The Newton C++ Tools MPW Environment

4-1

The Newton C++ Tools Menu 4-1Build Current Project 4-2Build with Debug 4-2Build with NoDebug 4-3Build Project Makefile 4-3Open Project Makefile 4-3Launch Newtsbug Using... 4-3Select NCT Root Directory 4-3Reinitialize NCT System 4-4Update NCT System From... 4-4Create _NCT Folder... 4-4Create New Project... 4-4

Additional Commands in the Find Menu 4-4Search Current Directory For... 4-5

Search Current Directory 4-5Search {Active} Folder For... 4-5Search {Active} Folder For 4-6Search Current Project For... 4-6Search Current Project 4-6Search Includes For... 4-6Search Includes For 4-6Search All NCT Projects For... 4-6Search All NCT Projects For 4-6Search All NCT Folders For... 4-6Search All NCT Folders For 4-7

Chapter 5

MPW Tools

5-1

AIFtoNTK 5-1DumpAIF 5-3


5/42

v

P R E F A C E

About This Book

This book, Newton C++ Tools Users Guide

, describes programmer softwareused to prepare C++ code for inclusion in NewtonScript programs. It has thefollowing chapters:

s

Chapter 1, Introduction, gives background information.

s

Chapter 2, Installing the Newton C++ Tools, tells you how to install theNewton C++ Tools.

s

Chapter 3, How to Use the Newton C++ Tools, steps you through usingthe C++ Tools, and includes a tutorial example.

s

Chapter 4, The Newton C++ Tools MPW Environment, describes themenu commands that the Newton C++ Tools adds to MPW.

s

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 ofinformation.

Special Fonts

This book uses the following special fonts:

s

Boldface

. Key terms and concepts appear in boldface on first use.

s

Courier typeface

. Code listings, code snippets, and special identifiersin the text such as slot names, function names, method names, symbols,and constants are shown in the Courier typeface to distinguish them fromregular body text. If you are programming, items that appear in Couriershould be typed exactly as shown.

s

Italic typeface

. Italic typeface is used in code to indicate replace-able items, such as the names of function parameters, which you mustreplace with your own names. The names of other books are also shown initalic type, and rarely

, this style is used for emphasis.


6/42

vi

P R E F A C E


7/42

1-1

Introduction 1

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 canuse this product.

In order to use the C++ Tools, you need:

s

Newton Toolkit (NTK)

s

Apple Macintosh or other Mac OS-based personal computer with a 68030 or laterprocessor, 33Mhz or faster. Any PowerPC Mac OS-based computer will work.

s

Mac OS version 7.1 or later.

s

At least 12 megabytes of RAM. If you have a PowerPC computer, 20 megabytes arerecommended. You need 20 megabytes to use MPW, NTK, and Newtsbugsimultaneously.

s

A CD-ROM drive

s

A hard disk with at least 25MB of available space

s

A Newton device running the Newton operating system version 2.0 or later

s

Newton Connection Kit for Macintosh v2.0 - Serial cable or Macintosh SystemPeripheral 8-Cable (M0197LL/B)

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 youwant 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 canorder MPW, NTK, or any other ADC product through these telephone numbers andaddresses:

From the USA 1-800-282-2732

From Canada 1-800-637-0029

From other Countries (716)871-6555

Figure 1-0Table 1-0


8/42

Introduction

1-2

Porting C++ Code to the Newton

Porting C++ Code to the Newton 1

You can use the C++ Tools to help port programs to the Newton. However, onlycomputational 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, soyou generally cannot port user interface code. Similarly, Newton devices do not have afile system in the same sense desktop computers do, and memory management issuesare somewhat different. In order to take advantage of the Newtons built-in software forthe user interface, data storage, and memory management, you generally need to writethe 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 1

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

File and Folder Naming Conventions 1

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

MPW can be confused by certain characters. In general you should limit your folder andfile 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

definitely are not. See the MPW documentation for information if you want to useunusual characters.

Fax (716)871-6511

AppleLink ADC

Internet [email protected]

CompuServe 76666,2405America Online ADCorder

Regular Mail ADCApple Computer, Inc.P.O. Box 319Buffalo, NY 14207-0319USA


9/42

Introduction

Files and Folders

1-3

Folders 1

The C++ Tools files and folders go into your MPW folder in the places indicated byChapter 2, Installing the Newton C++ Tools.

You can place the Newtsbug folder anywhere you want. We recommend, though, thatyou do not put it in the MPW folder. However, Newtsbug has to be in the MPWcommand path. The easiest way to make sure it is is to put an alias to Newtsbug in theMPW:NCT_Folder:Tools folder, as specified in the installation instructions. The name ofthis alias must be Newtsbug.

Your code goes into another folder structure that is contained within a root folder. Theroot folder that is included with the C++ Tools is the NCT_Projects folder. You normallydo 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 first level consists of_NCT folders which have names like Calculator_NCT andMaps_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 isset up to have your C++ projects set up in this way.

The Contents of the Project Folders 1

The project folders contain:

s

C++ code files

s

NTK files that specify Newton applications (layout files and project files)

IMPORTANT

Development of the NTK part of a project needs to take place in thesame folder as you use for C++ development, so that the debugger canfind the files it needs.

v

s

Items that the Newton C++ Tools uses to build the package. Those items are:

s

FilesInBuild. This file lists the files that are in the build. It is used by the BuildProject Makefile command to create a makefile for the project. If you create yourown makefile, you do not need this file.

s

Project

.exp. (The first part of the name is the same as the name of the project folder.)You put in information in this file that identifies the functions you want to call fromNewtonScript.

s

Objects. This folder is used for the object files created and used in your build.

s

Makefile. This is the makefile for the project.

When you use the Create New Project command from the Newton C++ Tools menu inMPW, the Newton C++ Tools creates prototypes for FilesInBuild andproject

.exp and alsocreates the Objects folder. The Build Project Makefile creates the makefile.


10/42

Introduction

1-4

Files and Folders

Notes

The Newton C++ Tools menu in MPW lists all the C++ Tools projects inthe current projects folder. The build system finds those by looking forfolders in the current projects folder that end in _NCT and then lookingin each sub-folder for a FilesInBuild file or a Makefile. It lists only thosefolders that contain one or both of those files.

In addition, the build system looks in the projects folder for anDebugger_Images folder. It lists Newtsbug images in that folder underthe Launch Newtsbug using... command in the Newton C++ Toolsmenu.

x


11/42

2-1

Installing the Newton C++ Tools 2

How you install the Newton C++ Tools depends on whether or not you already haveMPW 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 onlyneed install the contents of Newton C++ Tools with MPW (if you do not already haveMPW) or C++ Tools as Additions for MPW (if you already have a full installation ofMPW 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:

Figure 2-0Table 2-0


12/42


2-2

Installation Overview

s

Newton C++ Tools with MPW

. Contains all of the C++ tools, interfaces, libraries, andsample projects pre-assembled with a minimal version of MPW for a quick-start,drag-and-drop installation.

s

Newton Toolkit 1.6.3 Updater

. Contains the latest patch to update Newton Toolkit 1.6

for use with Newton C++ Tools.s

Documentation

. Contains the Acrobat

.pdf documentation files for the C++Programmers Reference and for this manual.

s

Debugging

. Contains Newtsbug, a Macintosh-hosted, serial-link Newton debugger,the user manual for Newtsbug, and Newtsbug Connection, the debugging modestart-up package.

s

ROM Images for C++ Tools

. Contains the ROM image files used with Newtsbug forvarious Newton 2.0 devices.

s

C++ Tools as Additions for MPW

. A duplicate set of just the required MPW additionsyou can use if you already have a full installation of MPW on your system that youwant to extend with the Newton C++ Tools.

IMPORTANT

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

v

Installation Overview 2

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 2

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 foldersmust be in the same folder.


13/42


Adding the Newton C++ Tools to an Existing MPW

2-3

IMPORTANT

The MPWforNCT folder must NOT be placed inside any folder(s) withnames 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 tostep 5 below. If you have a PowerPC computer, you need to install an extension to useMPW 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 filewill 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 theNCT_Projects folder.

6. Momentarily, you will see a Newton C++ Tools menu with a pull-right menu for theDemos project at the bottom; select the sub-menu item Demos and you are readyto go.

Adding the Newton C++ Tools to an Existing MPW 2

If you have a pre-existing installation of MPW on your system, you can add NewtonC++ 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 directorycontaining your MPW folder.

3. Drag NCTBuild

UserPrefs, UserStartup

NewtonC++Tools, and NCT_Folder intoyour MPW folder.

4. Type the following line in your MPW Worksheet:

execute {MPW}UserStartup

NewtonC++Tools

Installing Newtsbug 2

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 find in the NCT_Folder.


14/42


2-4

Updating Newton Toolkit

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

Updating Newton Toolkit 2

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.


15/42

Starting the C++ Tools for the First Time

3-1

How to Use the Newton C++Tools 3

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

s Create a small C++ function

s Combine it with a Newton application that calls the function

Starting the C++ Tools for the First Time 3

The C++ Tools MPW start-up files 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 thattells you you need to select a root folder. The C++ Tools needs a root directory. It looksin 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 file dialog box.

Figure 3-0Table 3-0


16/42


3-2 Creating a Project

6. Find the NCT_Projects folder and choose it.

The C++ Tools start-up files continue processing. They build the Newton C++ Toolsmenu. When processing is done, the menu should look like the one shown inFigure 3-2.

Figure 3-2 Newton C++ Tools Menu

Creating a Project 3

The basic unit of Newton application development is a project. A project containsvarious files used and produced by NTK as well as the files used and produced by theC++ Tools. You do all C++ and NewtonScript development for an application within asingle project.

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

s The top level of the hierarchy is the root directory, which was the folder you chose inthe preceding section; if you want to create an additional root directory, do it from theMac OS Finder. You normally just use the NCT_Projects folder, because it contains the

includes and Library files that you need.s 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 amenu command described in this section to create these folders.

s The lowest level of the hierarchy is made up of project folders. You use a menucommand described in this section to create those folders, also.


17/42


Creating a Project 3-3

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

Creating an _NCT Folder and a Project Folder 3

You now need to create a new _NCT folder to hold the new example application, andthen 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 dialogin Figure 3-3. The dialog tells you what the C++ Tools has done and gives generaldirections for what you need to do to continue.

Figure 3-3 New Project Dialog


18/42


3-4 Creating a Project

Every C++ Tools project needs a .exp file. That file lists your module name andfunction names, and defines the interface used to call your functions fromNewtonScript.

The FilesInBuild file lists the files that make up the C++ part of your project. You need

to have this file in order to use the C++ Tools command that creates the buildinstructions (makefile) for your project.

When you create a new project, the C++ Tools creates prototypes for these files. Theycontain instructions that tell you how to place your information in the files.

8. Click OK to dismiss the dialog.

Making a Project the Current Project 3

C++ Tools commands apply to the current project. To make the new project the currentproject:

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 nowunderlined, which indicates that Example is the current project. In addition to makingthis project the C++ Tools current project, choosing a project in this way sets the MPWcurrent directory to be the project directory.


19/42


Creating a Project 3-5

Setting Up the FilesInBuild File 3

As mentioned before, the FilesInBuild file lists the files that make up the C++ part ofyour project. You need to have this file in order to use the C++ Tools command thatcreates the build instructions for your project. To set up FilesInBuild for the exampleapplication:

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 file has comments that tell you where to put your information.

2. Type Example.cp in the place where the comments indicate source file names shouldgo, which is indicated by the arrow in Figure 3-5.

Figure 3-5 Default FilesInBuild File

3. Save and close the file.

Keeping Code in Sub-Folders 3You can have code in sub-folders in your project folder. In that case, you need to give thefolder names in the FilesInBuild file. 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 calledMyCode. Modify the line so that it looks like this:

Add

file

names

here


20/42


3-6 Defining a Function

-srcdirs ': :MyCode:'

Notice that the list of folders is surrounded by single quote marks. Suppose you havetwo 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-quotemarks like this:

-srcdirs ': :MyCode1: :MyCode2: ":MyCode Additions:"'

Defining a Function 3

To define the function for this example:

1. Use the New command in the File menu to create a new file.

2. Type this code in the new files window:

#include "objects.h"

extern "C"

Ref SillyString(RefArg)

{

RefVar num = MakeInt(49);

return num;

}

Note

You should generally define your functions as extern "C". If you donot do this, the compiler issues a mangled name for the function. Youthen need to specify the mangled name in the Example.exp file, which isdiscussed 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 overloadedfunctions. A mangled name includes the function name plus its classname and arguments.) You may use mangled names if you wish, butsince the mangled names are compiler-dependent andfunction-signature dependent, you will have to discover and maintainthe mangled names yourself; the DumpAOF tool is useful for displayingsuch names. x

3. Save the file as Example.cp.

4. Close the file.


21/42


Defining the NewtonScript Interface to a Function 3-7

Defining the NewtonScript Interface to a Function 3

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

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

Figure 3-6 Example.exp File

The first line gives the module name. The C++ Tools build system assumes themodule name is the same as the project name. You can change this line if you want touse a different module name. Each .exp file, and therefore each project, can onlycontain one module.

In .exp files, 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 file for interface functions, type:

SillyString

Press Return. You must always have a return character at the end of every line in thisfile. If you omit this trailing carriage return, you will get a link error for the lastsymbol in your module minus its last character.

3. Close and save the file.

Creating a Makefile 3The MPW make tool uses makefiles to govern building programs.

1. Select the Newton C++ Tools menu item Build Project Makefile .

A window named BuildResults opens and the scripts to create an MPW makefilebegin executing.


22/42


3-8 Building the C++ Source

2. Close the BuildResults window.

Note

The file shown in the BuildResults window is not automatically saved

when you close it. If you want to save the position and size of thewindow, you can use the Save command to save the file. If there isanything in the window, though, anything new will be appended to thewindows contents. Therefore, in order to save the position and size ofthe window, delete the contents of the window before using the Savecommand. x

Building the C++ Source 3

This step uses the makefile 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 aMakeout window opens as the source is compiled and linked .

You now have the file Example_NCT:Example:Objects:Example.ntkc which has beenrebuilt 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 thesame folder as you use for C++ development, so that the debugger canfind the files it needs. v

Importing a C++ Code Module Into an NTK Project 3

You need to have NTK installed on your hard disk. See NTK documentation forinformation 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 GuideTutorial.

3. Select the Example.t and Example. files and drag them into the Example folder

which you created earlier..These are files that define the NewtonScript part of a small application that you aregoing to use to call SillyString.

4. Double click Example..

NTK starts and opens the Example project. The project shows only one file: Example.t.(Example.t is the layout file. See the NTK documentation for information on layoutfiles.)


23/42


Importing a C++ Code Module Into an NTK Project 3-9

5. Select the Add file... menu item from the Project menu.

6. Navigate to the Objects folder and select the file Example.ntkc. Click on Add.

This adds the C++ code module file to the NTK project.7. Click on the Example.ntkc file 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 NewtonScriptmodule.

8. Choose the Open command.

9. Select Example.t, and click on Open.

This is the layout file 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 anddownloaded 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 file.

15. From the Project menu, select the Build Package item.

This command builds the project including the .ntkc module. If you have your NTKpreferences set to automatically download after building and you connected aNewton device to the Mac OS-based computer, NTK attempts to download the Testpackage to your Newton device. Alternatively, if you have loaded the Toolkit Appinto the Newton device, you can select it from the Extras drawer and download yourTest package.

16. Once you have downloaded the package you can run the package. It displays asimple message that contains the number 49.

When you are building interface functions to be called from NewtonScript with the C++compiler, you should define 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 fromNewtonScript. (C++ uses mangled names to accommodate methods and overloadedfunctions. A mangled name includes the function name plus its class name andarguments.) In addition, when you do not used mangled function names, the NewtonC++ Tools build process determines the number ofRefArg arguments that eachinterface function requires automatically and passes this information to NTK. If you use


24/42


3-10 Trying Out Project Demos

mangled function names, the function name will change if the number of argumentschanges.

You may use mangled names if you wish, but since the mangled names arecompiler-dependent and function-signature dependent, you will have to discover and

maintain the mangled names yourself; the DumpAOF tool is useful for displaying suchnames.

Trying Out Project Demos 3

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

s Make it the current project as shown in Making a Project the Current Project onpage 3-4

s Create a makefile as shown in Creating a Makefile on page 3-7

s Build it as shown in Building the C++ Source on page 3-8

s Start NTK, add the .ntkc file to the NTK project, build the NTK project, and downloadthe resulting package, as shown in Importing a C++ Code Module Into an NTKProject on page 3-8

Debugging 3

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 todebug 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 notinterconnect.

In order to set up to use Newtsbug, create an alias of the package file that is produced byNTK and place the alias in the Newtsbug folder. The package file ends with theextension .pkg.

See the Newtsbug Users Guide for more information.


25/42


Customizing the Newton C++ Tools 3-11

Note

You need to read this note only if you write your own makefiles or movethe package file that NTK produces. Newtsbug needs to have symbolinformation in order to debug a package. Symbol information isgenerated by the compiler whether you compile with debugging on oroff, and is contained in the .sym file. The package file containsinformation that defines where the .sym file is located, using a pathrelative to the .pkg file. The makefiles created by the Newton C++ Toolsplace .sym files in the Objects folder that is in the project folder.Therefore, although you can move the .pkg file and the .sym file afteryou build your package, you must keep the relative path from the .pkgfile to the .sym file the same if you want to use Newtsbug. In otherwords, the folder that contains the .pkg file should contain an Objectsfolder, and the .sym file should be in that folder. v

Customizing the Newton C++ Tools 3In the MPW folder, there is an MPW shell file called NCTBuildUserPrefs that containsvarious things that an expert MPW user might want to change. You can look at that filefor information. In general, before making any changes, you should make a copy of theoriginal so you can restore it if necessary.

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


26/42


3-12 Customizing the Newton C++ Tools


27/42

The Newton C++ Tools Menu 4-1

The Newton C++ Tools MPWEnvironment 4

You develop and process code for the C++ Tools using MPW. MPW is a programmingenvironment that is similar in many ways to UNIX, in that it uses a command-line shelland has a fairly complex shell programming language. The C++ Tools build systemincludes scripts written in this shell language that simplify the process of buildingprojects. These scripts are executed using commands in the Newton C++ Tools menu.

When you start up MPW with the Newton C++ Tools start-up files included in the MPWfolder, the start-up files add the Newton C++ Tools menu and also add some commandsto the Find menu. These menu commands are described in this chapter.

See the MPW documentation for more information. The MPW documents are includedon the Newton C++ Tools release CD.

The Newton C++ Tools Menu 4

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

Figure 4-0Table 4-0


28/42


4-2 The Newton C++ Tools Menu

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 isunderlined in the submenu. You change the current project by selecting a new one fromthe 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 4

When you choose this command, MPW uses the makefile to build the project. (You mustalready have a makefile, of course. You can create one using the Build Project Makefilecommand.)

Build with Debug 4

This menu item sets the makefile so that when you build the project again it is built withthe compilers debug switch on. This switch is used by the compilers preprocessor. Youcan 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.


29/42


The Newton C++ Tools Menu 4-3

Note

Whenever you use DebugPrint and printf, those functions should be enclosedwithin #ifdefforDebug and #endif. If you do not do that, compilation will failwhen you build with NoDebug. x

Build with NoDebug 4

This menu item sets the makefile so that when you build the project it is built with thecompilers debug switch off, which excludes the parts marked with #ifdefforDebugand #endif.

Symbol information that is used by the debugger, Newtsbug, is still included in theobject file.

The object file is placed in the folder ObjectsNoDebug, instead of the Objects folder.(ObjectsNoDebug is created, if necessary.) After you build with NoDebug, you need touse the NTK Add File command to add the NoDebug version of the .ntkc file to the

project.

Build Project Makefile 4

This menu item creates a makefile for the current project. In general, you do not need tomodify the resulting makefile.

Open Project Makefile 4

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

Launch Newtsbug Using... 4

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

Note

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

Select NCT Root Directory 4

This menu item sets the root directory. MPW rebuilds the last menu items to reflect theprojects 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 directoriesbecause, for example, they are on different volumes.


30/42


4-4 Additional Commands in the Find Menu

Reinitialize NCT System 4

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

Update NCT System From... 4

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

Create _NCT Folder... 4

This menu item lets you create subfolders in your top-level NCT_Projects folder, so thatyou 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_Projectsfolder. Dont include the suffix _NCT; that is automatically added for you.

_NCT folders are intended to be used to organize your projects. You put groups ofrelated projects in a single _NCT folder.

Create New Project... 4

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 withthat name. Within that folder, it creates prototypes for the files and folders that you need.Specifically, this command creates a prototype FilesInBuild file, an Objects folder, and aprototype .exp file. See The Contents of the Project Folders on page 1-3 forinformation on these items.

Additional Commands in the Find Menu 4

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


31/42


Additional Commands in the Find Menu 4-5

Figure 4-2 The Find Menu

The additional commands are not specific to the C++ Tools, but are powerful and helpfulsearch commands.

v W A R N I N G

You should not enter search strings that contain MPW escape characterssuch as (option-d). This character can cause problems with searching;for example, n causes the search commands to go into an infiniteloop. v

Search Current Directory For... 4

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

Search Current Directory 4

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

Search {Active} Folder For... 4

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


32/42



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

Search {Active} Folder For 4

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

Search Current Project For... 4

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

Search Current Project 4

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

Search Includes For... 4

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

Search Includes For 4

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

Search All NCT Projects For... 4

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

Search All NCT Projects For 4

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... 4

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


33/42


Additional Commands in the Find Menu 4-7

Search All NCT Folders For 4

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


34/42




35/42

AIFtoNTK 5-1

MPW Tools 5

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 amake file 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 file into a form that can be incorporated in aNewton program. See AIFtoNTK below for information.

s ARM6asm assembler. See the ARM documentation for information.

s ARM6c C compiler. See the ARM documentation for information.

s ARMCpp C++ compiler. See the ARM documentation for information.

s ARMLink linker. . See the ARM documentation for information.

s

DumpAOF, which emits code in ARM Object Format. Sophisticated programmersmay find this useful for debugging code. See the ARM documentation for information.

s DumpAIF, which dumps the output format from the linker, and is analogous to theMPW tool DumpCode. See DumpAIF on page 5-3 for information.

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 tosee the help information.

AIFtoNTK 5

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

Figure 5-0Table 5-0


36/42

MPW Tools

5-2 AIFtoNTK

AIFtoNTK [-p] -via exportsFile -o outputFileinputFile

This tool converts an ARM Image Format (AIF) file into an NTK streamed frame file.

-p This is an optional parameter that requests the display of progress

messages to Dev:Stderr.-via exportsFile Specifies the path of an exports list file. When you use the C++

Tools menu commands, they build a prototype exports file; you fillin the file with the information you need. The exports file is anormal text file that contains lines of text. The first line must containthe module name. Subsequent lines each contain a single functionname. These are the names of functions that you want to be able tocall from NewtonScript. Each function name must be the firstnon-blank text on the line and there must be one function name perline. You can also have comment lines that begin with a semicolon(;); those lines are ignored.

You use the module name in NewtonScript call statements wheninvoking a function in the module. For example:

call modulename.function1 with (....)

-o outputFile Specifies the path of the output file to be created. If the file alreadyexists, its contents will be destroyed. The normal convention is touse the same name as the input file with the suffix .ntkc added .

inputFile Specifies the path of the input file to be converted into a .ntkc filefor use by Newton Toolkit. You can only give one input file. Youmust give an input file; AIFtoNTK ignores standard input.

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 file created by the ARMLink toolinto a streamed frame format file which is accepted as input by the NTK. The binaryimage of the read-only code and the table of relocations or fix ups are converted into

binary objects within the streamed frame.

The tool checks for signatures in the file data fork to verify that the input file is an ARMImage Format file.

AIFtoNTK can return the following status codes.

0 no errors; output file created.

1 usage, syntax or missing or invalid parameter error.

2 execution error; usually invalid data encountered in input file

3 internal or fatal error; usually system or memory overflow


37/42

MPW Tools

DumpAIF 5-3

Here is an example of the use of this tool:

AIFtoNTK -via mymodule.exp -o mymodule.ntkc mymodule

DumpAIF 5

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 filefilename. The -s option adds a symboltable.


38/42

MPW Tools

5-4 DumpAIF


39/42

IN-1

Index

Symbols

#ifdef forDebug 4-2_NCT folder

creating 3-3name 3-3position in hierarchy 1-3project folders 3-3shown in the Newton C++ Tools menu 4-2

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

B

Boldface typemeaning v

Build Current Project command 3-8, 4-2Build Package command in NTK 3-9Build Project Makefile command 3-7,4-3BuildResults window 3-8Build with Debug command 4-2Build with NoDebug command 4-3

C

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

C++ Toolsand NTK 2-2customizing 3-11file names expected 1-2installing 2-3 to ??project hierarchy 3-2reinitializing 4-4starting 3-1updating 4-4

calling a C++ function from NewtonScript 3-7, 3-9C compiler 5-1choosing the ROM image used by Newtsbug 4-3

code fileslocation 1-3conditional compilation for debugging 4-2Courier typeface

meaning vCreate _NCT Folder... command 3-3, 4-4Create New Project... command 3-3, 4-4current directory

searching 4-5current project 3-4

changing 4-2shown in Newton C++ Tools menu 4-2

current selectionsearching for 4-5 to 4-7

D

debugger see Newtsbugdebugging

using conditional compilation 4-2using printf and DebugPrint 4-3

Demossample program 3-10

directory names and structure 1-3DumpAIF 5-3DumpAOF 5-1

to see mangled names 3-6

E

escape charactersin MPW search strings 4-5

existing C++ code, porting 1-2
http://-/?-http://-/?-


40/42

I N D E X

IN-2

.exp filecomment lines 3-7requirement for 3-4using 3-7

extern "C" 3-6,3-9

F

File menu 3-5, 3-6file names expected by C++ Tools and MPW 1-2FilesInBuild file

description 3-4opening 3-5setting up 3-5using to specify sub-folders 3-5

Find Menu 4-4 to 4-7folders

names and structure 1-2 to 1-3searching 4-5 to 4-7

functioncalling from NewtonScript 3-9defining 3-6defining how it is called from NewtonScript 3-7extern "C" 3-6mangled names 3-6

I

Includes

searching 4-6installing

C++ Tools 2-3 to ??MPW 2-2Newtsbug 2-3, 2-4

Italic typefacemeaning v

L

Latest MPW folder 2-2Launch Newtsbug Using... command 4-3

linker 5-1viewing output code 5-3

M

makefilecreating 3-7 to 3-8,4-3opening 4-3

use in building the project (Build Current Projectcommand) 3-8,4-2

mangled names 3-6,3-9module name

defined in .exp file 3-7MPW 4-1 to 4-7

and Newtsbug 1-3characters usable in file and folder names 1-2command path 1-3customizing 3-11escape characters in search strings 4-5file names expected 1-2folder 2-2installing 2-2

version recommended 2-1MPW Additions folder 2-3multiple projects, organizing 3-2

N

NCT_Projects folder 2-3, 3-2adding projects 4-4

NCTBuildUserPrefs 2-3,3-11NCTSetup menu 3-1New command 3-6Newton C++ Tools menu 3-2,3-3, 3-4,3-7, 4-1 to 4-4

_NCT folders shown in 4-2showing current project 4-2

NewtonScript interface to a functiondefining 3-7using 3-9

Newtsbug 3-10 to 3-11alias to 1-3choosing the ROM image used 4-3installing 2-3,2-4location 1-3need to find files 3-8setting up 1-3

NTK 3-8and C++ Tools 2-2

downloading a package 3-9location of files 1-3

O

Open command 3-5
http://-/?-http://-/?-


41/42

I N D E X

IN-3

Open Project Makefile command 4-3

P

packagedownloading 3-9

porting C++ code 1-2printf

using 4-3Process Earlier command in NTK 3-9project 1-3,3-2

creating 4-4how the current one is indicated 4-2searching 4-6setting the current project 4-2

project folderand project name 1-3

contents 1-3creating 3-3having sub-folders 3-5position in folder hierarchy 3-2setting current project 3-4

project hierarchy 3-2Project menu in NTK 3-9

R

recommended version of MPW 2-1Reinitialize NCT System command 4-4

Required for MPW folder 2-3ROM image

choosing which Newtsbug uses 4-3root directory

changing 4-3choosing 3-1place in project hierarchy 3-2

S

sample functionbuilding 3-7

calling from NewtonScript 3-9defining 3-6defining the NewtonScript interface 3-7downloading 3-9

sample programDemos 3-10

Save command 3-8Search {Active} Folder For command 4-6

Search {Active} Folder For... command 4-5Search All NCT Folders For command 4-7Search All NCT Folders For... command 4-6Search All NCT Projects For command 4-6Search All NCT Projects For... command 4-6

Search Current Directory command 4-5Search Current Directory For... command 4-5Search Current Project command 4-6Search Current Project For... command 4-6Search Includes For command 4-6Search Includes For... command 4-6selection

searching for 4-5 to 4-7Select NCT Root Directory command 4-3Select Root Directory command 3-1semicolon

use in .exp files for comments 3-7SillyString

calling from NewtonScript 3-9

defining 3-6defining the NewtonScript interface 3-7downloading 3-9

starting the C++ Tools 3-1StdCLibInit 2-3System Additions folder 2-2

T

Toolkit App 3-9tools

seeing options of 5-1

Tools folder 2-3typefaces

meanings v

U

update CDupdating an existing C++ installation 4-4

Update NCT System From... command 4-4UserStartupNewtonC++Tools 2-3
http://-/?-http://-/?-


42/42

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 publishingsystem using Apple Macintoshcomputers and FrameMaker software.

Proof pages were created on an AppleLaserWriter Pro 630 printer. Final pagenegatives were output directly from thetext and graphics files. Line art wascreated using Adobe Illustrator.PostScript, the page-descriptionlanguage for the LaserWriter, wasdeveloped by Adobe SystemsIncorporated.

Text type is Palatino and display type isHelvetica. Bullets are ITC ZapfDingbats. Some elements, such asprogram listings, are set in Apple Courier.

WRITER

Jonathan Simonoff

ILLUSTRATORPeggy Kunz

EDITOR

MP McKowen

PRODUCTION EDITOR

Gerry Kane

PROJECT MANAGER

Gerry Kane

.

newton c++ tools user’s guide

Documents