Installing Ikaros on OS X

Building Ikaros

Building Ikaros is very easy. You need to perform three steps:

Install XCode. You can also get it from the Mac App Store.
Install jpeglib and pnglib. The simplest way to fo this is to use the installer distributed by Ethan Tira-Thompson.
Double click on the project file "IKAROS.xcodeproj" in the OS_X directory. To compile, press the "Build" button in XCode.

Possible problems

The compiler may try (and fail) to build modules not intended for OS X. This is most likely due to explicit setting of the wrong target system in IKAROS_System.h in the root directory. Starting with version 0.8.0, the OS X version defines "MAC_OS_X" as a compiler flag in Xcode. If you compile Ikaros from the command line, be sure to specify -DMAC_OS_X or edit the IKAROS_System.h file.
The compiler may not find libjpeg or libpng. These are probably installed in /usr/local. You can add this path to the project or drag the files libjpeg.dylib and libpng.dylib into the Framework group in the project

Running Ikaros

To run Ikaros you can either run it directly from XCode or use the Terminal application. In either case, Ikaros is given an ikc file which describes which Ikaros modules to run.

Running from XCode

Using XCode 4, the ikc file should be specifying as an "Argument" in the Scheme window. This window is opened by selecting "Edit scheme…" from the Product menu or by using the IKAROS menu next to the stop button"

It is best to use a relative path to the ikc file here, for example: "../Examples/WebUI-Demos/web_ui_objects.ikc", since this allows the project to be moved around. To see the result in a web browser, also add the argument -w.

In XCode, press the "Run" button to start Ikaros. Ikaros will run the WebUI Demo and will start up with that file and wait for a web browser to connect to port 127.0.0.1:8000. Enter this URL into Chrome or Safari. This will show the user interface in the browser. Press the run button to start Ikaros. More information on the interface in the Web browser is available in the WebUI documentation.

Running from the command line

At the shell prompt write the following:

> ikaros experimentfile.ikc

Here, "experimentfile.ikc" is the path to the experiment you want to run. You must set up your search path so that it includes the directory with the Ikaros binaries. This is usually the directory IKAROS/Bin. Command line options can also be specified here.

Note that the Ikaros binary must be placed at the correct location relative to the Source directory. If you move the binary from the Ikaros/Bin directory or set up your path so that Ikaros/Bin in in your search path, you need to change IKAROSPATH in IKAROS_System.h to point to the absolute location of the Ikaros directory.

Adding a module

While quite easy to add another module to the simulator it does involve a few steps. The idea is to create a new folder to hold the module, add the folder to the project, add a bit of documentation (you will thank yourself for doing this), and tell the system to add the module to the Ikaros.

Create a new folder in UserModules. The easiest way to do this is to go to UserModules and copy the 'MyModule' folder; do not forget to rename the folder as well.
Add your code as appropriate.
Edit the ikc-file to add documentation.
Add the module to 'UserModules.h', i. e. add the .h file and a line with the AddClass call. Copy and rename one of the lines.

An example on how to write an IKAROS module can be found here.

Creating a new XCode project for Ikaros

If you prefer to create you own project for Ikaros you will need to add the follwing frameworks and libraries to the project:

In addition, it is necessary to set a few variables in the project settings. The most important ones are the Header Search Path and the MAC_OS_X flag in Other C++ Flags. Here are the standard settings:

Software used when creating this document

External libaries

A combined installer for libjpeg and libpng is available here. (Note that these libraries have been compiled with debug information cases a number of warnings to printed on start up. These warnings can be removed using the "strip -S" command on the libraries).

libpng.org
http://www.libpng.org/
libpng v1.2.17

Independent JPEG Group
http://www.ijg.org/
libjpeg 6b