Building an Aimsun Next API Application with Xcode

Developing a C++ Aimsun Next API Next Extension (microscopic or mesoscopic) in Mac OS X requires the use of Xcode. This guide will cover all the steps to install Xcode, create a new project, then run and debug the extension.

Installing Xcode

Xcode is a free install available from the Mac OS X App Store.

Creating a Project

Start Xcode. From the File menu choose: New, then Project. This will open the template chooser. Select the template Library from OS X, Framework & Library.

Give a name to the product, an organization identifier (the domain of your organization in reverse order for example) and select the STL (C++ Library) and Dynamic settings.

Select a folder to contain the project.

Adding source files

Xcode adds three files with the extensions hpp and cpp. Copy in the same location the 6 files included in the cpp folder from the Aimsun DMG file named: - AAPI.cxx - AAPI.h - AAPI_Util.h - AKIProxie.h - ANGConProxie.h - CIProxie.h

Use the Show in Finder option to locate the folder.

After copying the files, add them to the project using the command Add Files to...

Finally, remove the three files created automatically by Xcode. After that, the new project will contain 6 files.

Adding the Aimsun Next Kernel library

Before compiling our code, inform Xcode where the Aimsun libraries are held. Select the top entry in the Project navigator. On the right select "Build Settings" and press All.

Scroll down to the Linking group. Edit the Other Linker Flags setting to contain the next text:

-L/"Applications/Aimsun Next.app/Contents/PlugIns" -la2kernel -lacontrol

Changing the Build Location

It is recommended, but not required, to change the build location to be side by side with the extension source code. To do so, follow this guide.

Setting the location to Custom, then Relative to Workspace is recommended.

Building and Executing

Press the Play arrow in the top left corner of Xcode to compile the extension. Use Show in Finder over your dylib to locate it.

Open Aimsun Next, load the Aimsun document, go to Scenario Editor: Aimsun Next API tab. In the API box, press Add and locate the extension (DYLIB file).

Run the simulation to use the extension.

Debugging

To debug the new extension, start Aimsun Next and load the Aimsun document. Before starting the simulation, go to Xcode and select the option Attach to Process from the Debug menu.

Set breakpoints as required and, when ready, start the simulation.