MacTel - a Step-by-Step Guide

This document will show you how to create an ArchiCAD add-on from scratch, or by using the ArchiCAD Add-On template.

Creating a new Carbon Bundle

Here is the step by step guide how to create a working project. The starting folder in path references is always the APIDevKit folder. The working project from which we present here the examples comes from the 'Examples' subfolder of the APIDevKit folder.

Create a new Carbon Bundle project:
Add a new 'Run Script Build Phase' to the current Target and set the script as follows: "/usr/bin/perl RFIX.mac/compileGRCs.pl"
Add a new 'Build ResourceManager Resources Build Phase' and add the .r file to this phase
Set the project file build settings
1. In the 'Architectures' section set 'Architectures' to i386
2. In the 'Build Locations' section set the Base SDK Path to /Developer/SDKs/MacOSX10.4u.sdk
3. In the 'Search Paths' section set the following:
  - Framework Search Paths: $(FRAMEWORK_SEARCH_PATHS) ../../Support/Frameworks
  - Header Search Path : /Developer/Headers/FlatCarbon
  - Library Search Paths : $(LIBRARY_SEARCH_PATHS) $(SRCROOT)/../../Support/Lib/Mactel
  - Rez Search Paths : RO ../../Support/Inc ../../Support/Modules/DGLib
  - User Header Search Path : ../../Support/Inc ../../Support/Modules/** (the '/**' means 'recursive')
4. In the 'Rez' section of the group add the 'macintosh=1' macro to the 'Prepocessor Defines' settings.
5. In the GCC 4.0 - Preprocessing section add the 'macintosh=1 ACExtension' macros to the 'Prepocessing Macros' settings. In the same section set the 'Compile Sources as' setting to 'C++'.
6. In the 'GCC 4.0 - Warnings' section set the following:
  - Check Mismatched return type
  - Check Typecheck Calls to printf/scanf
  - Other warning flags : -Wno-multichar
Add your own source files to the 'Source' group
Add the libACAP_STAT.a file from Support/Lib/Mactel folder to the 'External Frameworks and Libraries' group
Add the necessary frameworks (at minimum GSRoot, GSZlib and InputOutput) from Support/Frameworks folder to the 'External Frameworks and Libraries' group

The resulting project is quite similar to the one you can create with the Add-On template, so you can find the final customized settings on the pictures below. The main difference is that the source (.c*, .h*), resource (.r, .grc, Info.plist) files and the compileGRCs.pl script are placed in subfolders for all example projects. The template places them into the same folder where the project file (.xcodeproj) is.

Using the ArchiCAD Add-On template

Installation

See the ReadMe.txt file in the $(APIDevKit)/Support/Tools/OSX/Xcode goodies folder. Basically you have to copy the contents of that folder into $(HOME)/Library/Application Support/Developer/3.0/Xcode folder (create the folder if it doesn't exist).

Usage

The ArchiCAD Add-On template is a customized version of the Carbon Bundle template. The modifications were only exercised in the project settings, but not in the target settings.

The template assumes that you create the add-on in the Examples folder of the API DevKit.

Xcode handles template projects much better than Xcode, it understands many keywords which can be replaced during the instantiation of the template project. One of those keywords («ORGANIZATIONNAME» – used in the .r file) has to be set before you create your first project. Type the following into a new Terminal window (don't forget to replace the appropriate part):

defaults write com.apple.Xcode PBXCustomTemplateMacroDefinitions '{ "ORGANIZATIONNAME" = "Your Company Name" ; }'

Now, create a new ArchiCAD Add-On project:

The typical layout of an ArchiCAD add-on can be seen in the figure below.
New ArchiCAD Add-On

Let's take a look at the characteristics of the various parts of the project.

The Resources group contains the default add-on icon, the .grc, .r, and Info.plist files. Note that only the icon is part of the Copy Bundle Resources build step.
The External Frameworks and Libraries group contains the static API library, and at least the Carbon, GSRoot, GSZLib and the InputOutput frameworks.
In the Targets section, the Sample group shows two additional build steps:
- the Run Script phase calls the compileGRCs.pl script, which in turn converts the .grc files into the format understood by the Rez compiler.
- the Build Resource Manager Resources phase compiles .r rez file. That file may include the result of the .grc file conversion and other resources as well.

The typical settings of an ArchiCAD add-on project can be seen in the figure below. Double-click on the project icon (the one with the Xcode icon in front) to see this dialog.

As you can see the values are set for all configurations. Only the customized parameters are shown here, all the others are using their default values. Let's take a look at the more important variables:

Setting Value Notes

Base SDK Path /Developer/SDKs/MacOSX10.4u.sdk MacTel machines work with OS X 10.4 and above, so you'll have to use this SDK

Header Search Paths /Developer/Headers/FlatCarbon This makes non-framework style system header includes valid, e.g.:
#include <Carbon.h>
can be used instead of
#include <Carbon/Carbon.h>

User Header Search Paths ../../Support/Inc/** ../../Support/Modules/** Defines recursive search paths where the API and module headers can be found.
These relative paths assume that your add-on is placed within the Examples folder in the devkit.
(e.g. the path to the project file is: Examples/Sample/Sample.xcodeproj)

Library Search Paths ../../Support/Lib/Mactel The path to the libACAP_STAT.a static library.

Framework Search Paths ../../Support/Frameworks All the modules are shipped as frameworks (well, sort of, as the headers are in the separate Modules folder), this is where they are stored.

Rez Search Paths RO ../../Support/Inc ../../Support/Modules/DGLib RO contains the compiled .grc files
Inc contains the resource template for the MDID resource
DGLib is needed only if you use grc-based dialogs in your add-on

Info.plist file Info.plist Path of the Info.plist file; in the example add-ons its value is RFIX.mac/Info.plist.

Compile Sources as C++ Even if your files have .c extension, compile at least those as C++ which include any API header. The API headers include GSRoot.hpp, and that file cannot be compiled as C.

Typecheck Calls to printf To avoid garbled output. (e.g. the format string "%Ld" in GCC tries to print a long double, and if you pass a normal double, you'll get garbage because of the byte order.

Other Warning Flags -Wno-multichar Turn off warnings for multi-character constants found in GSRoot, for example
enum PlatformSign { Mactel_Platform_Sign = 'mm' };

Preprocessor Macros macintosh=1 ACExtension Macros for the source file compilation.

Preprocessor Defines macintosh=1 Macros for the resource file compilation.

Setting	Value	Notes
Base SDK Path	/Developer/SDKs/MacOSX10.4u.sdk	MacTel machines work with OS X 10.4 and above, so you'll have to use this SDK
Header Search Paths	/Developer/Headers/FlatCarbon	This makes non-framework style system header includes valid, e.g.: `#include <Carbon.h>` can be used instead of `#include <Carbon/Carbon.h>`
User Header Search Paths	../../Support/Inc/ ../../Support/Modules/	Defines recursive search paths where the API and module headers can be found. These relative paths assume that your add-on is placed within the Examples folder in the devkit. (e.g. the path to the project file is: `Examples/Sample/Sample.xcodeproj`)
Library Search Paths	../../Support/Lib/Mactel	The path to the `libACAP_STAT.a` static library.
Framework Search Paths	../../Support/Frameworks	All the modules are shipped as frameworks (well, sort of, as the headers are in the separate `Modules` folder), this is where they are stored.
Rez Search Paths	RO ../../Support/Inc ../../Support/Modules/DGLib	`RO` contains the compiled .grc files `Inc` contains the resource template for the `MDID` resource `DGLib` is needed only if you use grc-based dialogs in your add-on
Info.plist file	Info.plist	Path of the `Info.plist` file; in the example add-ons its value is `RFIX.mac/Info.plist`.
Compile Sources as	C++	Even if your files have `.c` extension, compile at least those as C++ which include any API header. The API headers include `GSRoot.hpp`, and that file cannot be compiled as C.
Typecheck Calls to printf		To avoid garbled output. (e.g. the format string `"%Ld"` in GCC tries to print a long double, and if you pass a normal double, you'll get garbage because of the byte order.
Other Warning Flags	-Wno-multichar	Turn off warnings for multi-character constants found in GSRoot, for example `enum PlatformSign { Mactel_Platform_Sign = 'mm' };`
Preprocessor Macros	macintosh=1 ACExtension	Macros for the source file compilation.
Preprocessor Defines	macintosh=1	Macros for the resource file compilation.

The typical settings of an ArchiCAD add-on target can be seen in the figure below. Double-click on Sample beside the small lego block icon (in the Targets section of the project. This dialog shows the customized target settings only – those which have different values from the settings defined for the project (see above). All other values are inherited from the project settings. The changes here are introduced by the project target type (Carbon bundle), and not by the API.

You find the resulting add-on in the build folder beside the Xcode project file.

This add-on has .bundle extension; if you'd like to remove that, add a PkgInfo file to the bundle itself. Issue the following command in a new Terminal window (after changing to the appropriate build directory:

    echo ".APXGSAP" > Sample.bundle/Contents/PkgInfo

where Sample.bundle is the name of your add-on.