John B. Matthews, M.D.
Return home.
Download sample Ada code in .hqx format.
Download GNAT 3.13p for MacOS 9.
Ada is now available for MacOS X.
MacOS Bindings for GNAT under MachTen/CodeBuilder
Welcome to GNAT on the Mac! This document describes the components of a thin Ada binding to the core MacOS ToolBox. Using these bindings, it is possible to invoke MacOS routines from the Code Builder or MachTen command line interface as well as in stand-alone Mac applications. These bindings are based on Apple's Universal Interfaces 2.1 for use with Tenon MachTen 4.1.1 or CodeBuilder 1.1.2, and GNAT 3.12p.
The following MacOS ToolBox Managers are supported: Aliases, AppleEvents, AppleTalk, Controls, Devices, Dialogs, EPPC, Errors, Events, Files, Folders, Fonts, Gestalt, IntlResources, Lists, Memory, Menus, MixedMode, Notification, OSUtils, Palettes, PPCToolBox, Processes, QDOffscreen, Quickdraw, QuickdrawText, Resources, SegLoad, StandardFile, TextEdit, TextUtils, ToolUtils, Types, and Windows. Additional ToolBox bindings are provided in preliminary form only (see Custom Bindings below).
Components
| Path | Description |
| /usr/include/ada/MacOS | Ada/MacOS bindings (source). |
| /usr/lib/ada/MacOS | Ada/MacOS libraries (object). |
| /usr/lib/MacOS | stand-alone Mac libraries. |
| /usr/lib/MacOS/InterfaceLib.a | Apple's MacOS interface code. |
| /usr/lib/MacOS/StdCLib.a | Apple's standard C library. |
| /usr/bin/macmake | gnatmake script for stand-alone app. |
Several examples are in /home/cbuser/sample_code/Ada/mac-team/mac-specific/
| Folder | Description |
| cli | command line Mac examples. |
| hello | stand-alone Mac example. |
| fractals | multi-window sample application. |
| list | list manager demo with UPP call-back. |
| mandel | simple Mandelbrodt set display. |
| modal | simple modal dialog. |
| rescopy | PathToFSSpec example. |
| shell | stand-alone animation demo. |
| silly | stand-alone color Quickdraw demo. |
Installation
The bindings and libraries required to build stand-alone MacOS applications are already installed in CodeBuilder. If you modify the bindings or need to rebuild them for some reason, simply compile all the files at once:
cd /usr/lib/ada/MacOS
gcc -c -O3 /usr/include/ada/MacOS/*.ads
gcc -c -O3 /usr/include/ada/MacOS/*.adb
Most of the examples have short Makefile scripts that may be invoked by entering the command "make" on the command line. By default, the finished application is stored in the directory from which make was invoked. When building is finished, applications are stored in /hfs/APPL/; to the MacOS, they appear in CodeBuilder:CodeBuilder_HFS:APPL:.
Stand-Alone Applications
Standard MacOS applications may be constructed using the macmake script to invoke gnatmake with the appropriate libraries and options. For example,
macmake <file>
invokes gnatmake for <file>.adb and generates the corresponding stand-alone application. If the application has resources, it must be built in a MacOS HFS or HFS+ partition. When compiling from an FFS partition, use the -copy option to build the application in /hfs/APPL/. The macmake script also merges any resources in the file <file>.rsrc by calling the restool utility.
Macmake accepts several options:
-copy build application in /hfs/APPL
-g debug option
-O[0-3] optimization level (0-3)
-sa merge necessary shared libraries into application
-stack # desired stack size (default 32767 bytes)
-u load for running under CodeBuilder
-v verbose flag
Command-Line Tools
MacOS routines may be called from programs that use the CodeBuilder command-line interface; the programs in "cli" show how. A typical gnatmake command might be:
gnatmake <file> -largs /usr/lib/MacOS/InterfaceLib.a
Normal MacOS Toolbox initialization should be avoided, as the MacOS has already been initialized by the CodeBuilder terminal program itself. If you open a window, it is important to preserve the current GrafPort and restore it after your program exits. This technique is demonstrated in the program "cli/sftest.adb". If your program has it's own event loop, it should handle all update events before disposing of it's window. In addition, the CodeBuilder Quickdraw global variables are inaccessible.
Custom Bindings
The basic binding technique is to use the pragma Import statement to equate an Ada procedure (or function or variable) name with an external library object, as described in the Ada 95 Reference Manual, Annex B. The type declarations and formal parameter lists use elements from the packages Interfaces.C and PStrings (or Interfaces.C.Strings). Parameters that are passed by reference (Pascal var parameters and ordinary parameters greater than four bytes in size) should be represented by simple pointers. Care should be taken to avoid defining access type parameters that are implemented in GNAT using 64 bit pointers: they include a pointer to the array bounds as well as a pointer to the array data itself.
Because Pascal style strings (length byte followed by data) are used throughout the Toolbox, the package PStrings offers methods to interconvert Ada and Pascal style strings. The package routines are modeled after Interfaces.C and Interfaces.C.Strings. The package specification describes each routine, and the usage of several routines is demonstrated in the command line examples.
The Toolbox also includes routines that accept C style (null terminated) strings. The linker sees these as having the same names, but all lowercase. The Ada compiler does not distinguish these identifiers by case, but it can differentiate them by their formal parameter lists. The example "over.adb" shows how overload resolution can be made to apply to imported procedures by appropriate renaming. The list manager exaplpe uses this technique (see list/readme.txt). CAUTION: The preliminary bindings have NOT been edited in this way.
For convenience, many overloaded routines permit Ada strings as actual parameters:
| File | Type | Name |
| controls.adb | function | newcontrol |
| controls.adb | procedure | setcontroltitle |
| dialogs.adb | function | newdialog |
| dialogs.adb | function | newcolordialog |
| dialogs.adb | procedure | paramtext |
| dialogs.adb | procedure | setdialogitemtext |
| files.adb | function | fsopen |
| files.adb | function | getfinfo |
| files.adb | function | setvol |
| files.adb | function | unmountvol |
| files.adb | function | eject |
| files.adb | function | flushvol |
| files.adb | function | create |
| files.adb | function | fsdelete |
| files.adb | function | openrf |
| files.adb | function | fsrename |
| files.adb | function | setfinfo |
| files.adb | function | setflock |
| files.adb | function | rstflock |
| fonts.adb | procedure | getfnum |
| menus.adb | function | newmenu |
| menus.adb | procedure | appendmenu |
| menus.adb | procedure | insertmenuitem |
| menus.adb | procedure | setmenuitemtext |
| quickdraw.adb | procedure | stuffhex |
| quickdrawtext.adb | function | stringwidth |
| quickdrawtext.adb | procedure | drawstring |
| resources.adb | function | getnamedresource |
| resources.adb | function | get1namedresource |
| resources.adb | function | openrfperm |
| resources.adb | function | openresfile |
| resources.adb | procedure | createresfile |
| resources.adb | procedure | setresinfo |
| resources.adb | procedure | addresource |
| standardfile.adb | procedure | sfpputfile |
| standardfile.adb | procedure | sfgetfile |
| standardfile.adb | procedure | sfpgetfile |
| standardfile.adb | procedure | sfputfile |
| textutils.adb | function | equalstring |
| textutils.adb | function | relstring |
| textutils.adb | function | newstring |
| textutils.adb | function | iucompstring |
| textutils.adb | function | iuequalstring |
| textutils.adb | function | iustringorder |
| textutils.adb | procedure | setstring |
| textutils.adb | procedure | stringtonum |
| types.adb | procedure | debugstr |
| windows.adb | function | newwindow |
| windows.adb | function | newcwindow |
| windows.adb | procedure | setwtitle |
Don't Panic
It would be impossible to exhaustively test all the routines presented in this binding. Moreover, these bindings will evolve over time as more managers are included, as more routines are added to the MacOS API, and as users add additional "thick" bindings. Users are encouraged to share their findings with others on GNAT chat or the Tenon mailing list.
There are several debugging strategies. The low-level debugger, Macsbug, is available on the CodeBuilder CD. Although it is not specialized to examine Ada data structures, it can display strings via the Types.DebugStr procedures in stand-alone code. Command line oriented code may use Ada.Text_IO for debugging, and the GNU debugger "gdb" can be used to step through the code and display variables.
Revisions
3120: GNAT 3.12p & CodeBuilder 1.1.2 update; new macmake; fixed Sierpinski in fractals; new list manager demo.
3112: GNAT 3.11p & CodeBuilder 1.1 update.
2031: GNAT 3.10 update; revise Lists.ads and add more constants.
1218: GNAT 3.09 update; extend PStrings & add constants to several bindings.
1129: CodeBuilder 1.0
1108: added appletalk, eppc, ppctoolbox & processes.
0918: GNAT 3.07 update; revise Amaclib/MakeLib & Modal example.
0915: added more managers, sample code & bug fixes.
0805: moved the library files to standard locations and generalized gnatmake.
0621: several changes with regard to Pascal strings:
1) Types.Str255 is now a general access type.
2) All formal parameters that were of type StringPtr or Str255Param are now "access Str255" parameters. This allows stack based (local variable) and heap based (New_String) Pascal strings to be used with equal facility.
3) The function PStrings.To_Pascal now returns a Str255 rather than a PString. This is more convenient for those used to a functional coding style. The procedure PStrings.Update is slightly more efficient, since it updates the string in place.
4) Range checking has been improved. See cli/ptest.adb for examples.
0620: first public release
0612: first beta release
0603: first alpha release
Legal Stuff
Copyright 1996-2000, John B. Matthews, M.D.. The example applications are copyrighted by the authors and made available under the GNU Public License (GPL) or Library GPL (LGPL), as noted.
The interface files from which these bindings derive and the associated libraries are the property of Apple Computer, Inc. and distributed with permission.
THE AUTHORS EXPRESSLY DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. MOREOVER, THE AUTHORS DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET YOUR REQUIREMENTS, OR THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR FREE, OR THAT DEFECTS IN THE SOFTWARE WILL BE CORRECTED. IN NO EVENT SHALL THE AUTHORS' TOTAL LIABILITY TO YOU FOR DAMAGES, LOSSES, AND CAUSES FOR ACTION EXCEED THE AMOUNT PAID BY YOU TO THE AUTHORS FOR THIS SOFTWARE. SOME STATES DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU.
Return home.