How to: get irrlicht 1.5.1 working in an .app file on Mac OS

[torleif]

The current tutorials on compiling on MacOSX are a bit dated. This is how to get the latest and greatest irrlicht using Xcode.

Requirements: Apple xcode dmg

First step: build irrlicht

1. Download the latest irrlicht 1.5.1. Navigate to the source/Irrlicht/MacOSX folder. Open MacOSX.xcodeproj in Xcode.
2. In the top dropdown, switch to “Release” Active Configuration. In the top right search for IrrCompileConfig header file and open it. Scroll down a few pages until you see the Joy stick enable marco, and comment out #define _IRR_COMPILE_WITH_JOYSTICK_EVENTS_
   
3. Push Build and Go. Grab a cup of tea or something; this will take a few minutes.
4. Copy the folder include to /usr/include/irrlicht. It’s easy to do this with terminal with this command: sudo cp irrlicht1.5/include /usr/include/

Second step: build your own hello world

1. Open Xcode. New Project > Other > Empty Project
2. Call it HelloWorld and save it inside the 01-HelloWorld folder
3. Project > new Target. Select Carbon > Application. Call it HelloWorld too.
4. It should popup with project settings (in the Project Menu) . add “/usr/X11R6/include /usr/include/irrlicht” to your Header Search Path
   
5. Add the libraries you need. Drag the new libIrrlicht.a you created from source/Irrlicht/MacOSX/release/ into your project. Then click the Action (gear wheel) next to the drop down and goto Add -> add Existing Framework. Add Carbon, Cocoa and OpenGL.
6. Add the resources needed for your .app file. Drag Sydney.bmp and Sydney.md2 into your project in the Products folder. Drag the main.cpp in there as well.
7. Modify main.cpp. after #include <irrlicht.h>, add:

Code: Select all

#ifdef _IRR_OSX_PLATFORM_
#include <OpenGL/OpenGL.h>
#pragma comment(lib, "libIrrlicht.a")
#endif

A lot of people are having trouble with figuring out where the paths are, MacOSX, .app programs have their own self-contained file structure. You must navigate to there if you want to add the files you dragged in earlier.

After you create your device, navigate to your Resources folder inside your app file.

Code: Select all

#ifdef _IRR_OSX_PLATFORM_
	device->getFileSystem ()->changeWorkingDirectoryTo ("HelloWorld.app");
	device->getFileSystem ()->changeWorkingDirectoryTo ("Contents");
	device->getFileSystem ()->changeWorkingDirectoryTo ("Resources");
#endif
	

And now if you’ve done everything right, when you hit Build and Go, you should see sydeny waiving hi to you.


Troubleshooting:

Code: Select all

"_IOServiceGetMatchingServices", referenced from:
      irr::CIrrDeviceMacOSX::activateJoysticks(irr::core::array<irr::SJoystickInfo, irr::core::irrAllocator<irr::SJoystickInfo> >&)in libIrrlicht.a(CIrrDeviceMacOSX.o)

etc means that you compiled irrlicht in debug mode. Recompile in Release

Code: Select all

"_IORegistryEntryGetParentEntry", referenced from:
      getJoystickDeviceInfo(unsigned int, __CFDictionary*, JoystickInfo*)in libIrrlicht.a(CIrrDeviceMacOSX.o)
      getJoystickDeviceInfo(unsigned int, __CFDictionary*, JoystickInfo*)in libIrrlicht.a(CIrrDeviceMacOSX.o)

This means you forgot to uncomment the _IRR_COMPILE_WITH_JOYSTICK_EVENTS_ marco. (It would be fantastic to know why MacOSX does not support joysticks)

File could not be found or my screen is blank

You are not navigating to the .app folder directory. You must use changeWorkingDirectoryTo to get to the right folder, use device->getFileSystem()->getWorkingDirectory() to debug where your current folder is.

TODO:

Figure out how MacOSX handles missing lib files (does the app need to contain the .a file?)

[bitplane]

Nice work, thanks for this

(It would be fantastic to know why MacOSX does not support joysticks)

This works for me. What version of OSX are you running?

Code: Select all

#ifdef _IRR_OSX_PLATFORM_
   device->getFileSystem ()->changeWorkingDirectoryTo ("HelloWorld2.app");
   device->getFileSystem ()->changeWorkingDirectoryTo ("Contents");
   device->getFileSystem ()->changeWorkingDirectoryTo ("Resources");
#endif 

Nice catch, we should probably add the .app dir as a folder archive by default! I do the same thing but constructed the resources dir manually, I don't know how valid it is so never added it by default.

Figure out how MacOSX handles missing lib files (does the app need to contain the .a file?)

No, it's static linked so it's actually in the binary. Apple shared objects are (supposed to be) compiled into .frameworks, which are packages containing the shared object, all the headers and some additional version info. You drop the .framework into your project rather than adding the headers and libs manually, there's one for OpenGL. I assume there's also one for X11 and the other libs you mention.
We really need to release Irrlicht as a framework, then users can just drop Irrlicht-1.5.framework into their project and won't need to do anything else to get it working.

[torleif]

Hey bitplane, thanks for the positive feedback

I'm using Mac OS X 10.5.8. I don't know why irrlicht joystick code failed to link. One guess is the newer SDK might not have the traditional references, or perhaps the newer build simply is broken. I'm using the 10.5 SDK.

Me and others have gotten frustrated over why their application isn't working due to the simple folder problem (it's quite misleading, the running directory is actually correct). It would be fantastic if the user is compiling an .app the engine would automagically navigate to the correct place. There's probably an apple dev page about the proper way to navigate the .app folder so it can be done by the book

Your idea of compiling irrlicht into a framework is fantastic. It's good to know how the binary libraries are handled in MacOSX, saves me from DLL Hell

[FuzzYspo0N]

hey, yea this is a cool post. Its cool to see some more osx activity, bitplane and i are working on upstepping the osx side and ill be making better more consistent , easier to use project which links hand in hand with the iphone stuff as well (so devloping for both is easier).

Thanks for the meaningful contributions!

[jdavidbakr]

Slight modification for 1.5.1 - with the framework:

1) You don't need to compile anything from the MacOSX folder. Start with "Second step: build your own hello world"

2) Don't need to change anything in the header files option

3) In step 5, add the Irrlicht framework (which is going to be in /Library/Frameworks, not /System/Library/Frameworks which is where the others are)

4) To use the framework, change the

Code: Select all

#include <irrlicht.h>

to

Code: Select all

#include <Irrlicht/irrlicht.h>

- this will force it to pull from the framework. You don't need to do step 7 because you didn't compile libIrrlicht.a

5) I'm not 100% sure exactly what the correct method to get the Resources folder to work, but I changed the following two lines:

Code: Select all

	//IAnimatedMesh* mesh = smgr->getMesh("../../media/sydney.md2");
	IAnimatedMesh* mesh = smgr->getMesh("sydney.md2");

Code: Select all

		//node->setMaterialTexture( 0, driver->getTexture("../../media/sydney.bmp") );
		node->setMaterialTexture( 0, driver->getTexture("sydney.bmp") );

With that I was able to get Sydney's hello wave. I was unable to get it to work using just the changeWorkingDirectoryTo() function, I had to change the actual path as well...

There's probably some good practices to make it cross-platform compilable. I haven't looked at the MacOSX project in the distro, but that will compile and play the HelloWorld.cpp file without the above modifications.

[torleif]

jdavidbakr: Thanks for your reply. You'll have to do a different set of steps if you want an external framework.

I've tried both to see how easy it is for both, and seems to be a bit better, as you don't have to compile it yourself. The Irrlicht framework is available for download from apple.

Distribution wise internally is better, as its filesize is 5megs compared to an 11meg framework. (and if you make an app, you only have to swap that file around instead of making an installer package)

[bitplane]

4) To use the framework, change the

Code: Select all

#include <irrlicht.h>

to

Code: Select all

#include <Irrlicht/irrlicht.h>

- this will force it to pull from the framework.

I use put the full path to the framework's Headers dir in the project to avoid editing the examples.

Regarding making an installer, Varmint tells me that the easiest way to work around this is to actually put the framework into your .app's dir. It's probably better to compile as a static library if you only have one binary though.
I hope to write some (the bare minimum) OSX specific docs for the next release.

[Xilon]

After you create your device, navigate to your Resources folder inside your app file.

Code: Select all

#ifdef _IRR_OSX_PLATFORM_
	device->getFileSystem ()->changeWorkingDirectoryTo ("HelloWorld.app");
	device->getFileSystem ()->changeWorkingDirectoryTo ("Contents");
	device->getFileSystem ()->changeWorkingDirectoryTo ("Resources");
#endif
	

a better way to do this (in Objective-C++) would probably be:

Code: Select all

NSString *resourcePath = [[NSBundle mainBundle] resourcePath];
device->getFileSystem()->changeWorkingDirectoryTo([resourcePath UTF8String]);

Note: code not tested, but it should work in theory.

[JustinBowles]

Hey bitplane, thanks for the positive feedback

I'm using Proextender daily and Mac OS X 10.5.8. I don't know why irrlicht joystick code failed to link. One guess is the newer SDK might not have the traditional references, or perhaps the newer build simply is broken. I'm using the 10.5 SDK.

Me and others have gotten frustrated over why their application isn't working due to the simple folder problem (it's quite misleading, the running directory is actually correct). It would be fantastic if the user is compiling an .app the engine would automagically navigate to the correct place. There's probably an apple dev page about the proper way to navigate the .app folder so it can be done by the book

Your idea of compiling irrlicht into a framework is fantastic. It's good to know how the binary libraries are handled in MacOSX, saves me from DLL Hell

Thanks alot for taking the time to post this tutorial. Very helpful as a Mac user.

Justin

[mordaneous]

Hi, great tutorial. I cant find Add target >> Carbon >> application on my install of XCode. I'm quite new to coding especially on Macs so am I missing something?!