How To use Dynamic Libraries in Xcode 3.1 (using FMOD)
I am writing this article to help people running Xcode on Mac OS X get around the dreaded FMOD dynamic libary not found error from happening at runtime:
dyld: Library not loaded: @loader_path/../Frameworks/libfmodex.dylib
Referenced from: /Users/brock/Game/Debug/mine.app/Contents/MacOS/mine
Reason: image not found
So here we go, the first step is to install FMOD Ex Programmers API. You can download it here:
http://www.fmod.org/index.php/download
Once you have downloaded it, run the FMOD Installer.
Once installed, all FMOD resources should be located:
/Developer/FMOD Programmers API/
The dynamic libraries that you will need to include with your application will be located in:
/Developer/FMOD Programmers API/api/lib/
You should drag the library you wish to use into your Xcode project"s Framework folder so that it looks like:
Once you have completed your FMOD coded application in Xcode, you will need to create a shell script that Xcode will automatically run upon completion of building your .app bundle.
If you are compiling a shell tool, which doesn"t encapsulate all the project"s code, this will still work, but you will need to modify the code below by removing the .app path stuff where appropriate.
In order to get rid of the dreaded dylib not found error, then you will need to run the otool command as well as creating a script for Xcode to run after everything is built. The otool command will tell you where your application is expecting to find the libraries and frameworks that it looks for at runtime.
So, type this:
otool -L /path/to/AppName.app/Contents/MacOS/AppName
which should produce something like:
./libfmodex.dylib (compatibility version 1.0.0, current version 1.0.0)
/System/Library/Frameworks/GLUT.framework/Versions/A/GLUT (compatibility version 1.0.0, current version 1.0.0)
/System/Library/Frameworks/OpenGL.framework/Versions/A/OpenGL (compatibility version 1.0.0, current version 1.0.0)
@executable_path/../Frameworks/SDL.framework/Versions/A/SDL (compatibility version 1.0.0, current version 1.0.0)
/System/Library/Frameworks/OpenAL.framework/Versions/A/OpenAL (compatibility version 1.0.0, current version 1.0.0)
/usr/lib/libstdc++.6.dylib (compatibility version 7.0.0, current version 7.4.0)
/usr/lib/libgcc_s.1.dylib (compatibility version 1.0.0, current version 1.0.0)
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 111.0.0)
Notice the top line, this means that the application expects to find:
"./libfmodex.dylib". Which is our FMOD dylib file.
However this will not exist at runtime, so we have to get Xcode to copy this file into the app bundle as well as modify the binary to look in its new location:
So, in Xcode, right-click on your target and choose:
Add > New Build Phase > New Run Script Build Phase
You should see a new item under the target called "Run Script":
Now, Double-click the "Run Script" folder and paste in the following command:
WARNING! If you are copy pasting this be sure to change the the curly quotes " " into normal quotes by simply re-typing them.
mkdir "$TARGET_BUILD_DIR/$PRODUCT_NAME.app/Contents/Frameworks"
cp -f /Developer/FMOD Programmers API/api/lib/libfmodex.dylib "$TARGET_BUILD_DIR/$PRODUCT_NAME.app/Contents/Frameworks/libfmodex.dylib"install_name_tool -change ./libfmodex.dylib @loader_path/../Frameworks/libfmodex.dylib "$TARGET_BUILD_DIR/$PRODUCT_NAME.app/Contents/MacOS/$PRODUCT_NAME"
You will need to modify this script according to your own setup.
Xcode will also inform you of any errors with your script in the Build Warning and Errors window when you build your project.
You should do a clean then do a build. After the build is complete Xcode will run the script.
Step by step what this script does it:
1) Creates a new directory called "Frameworks" inside the application"s bundle
2) Copies the "libfmodex.dylib" file from the FMOD developer folder to the /Frameworks directory that was just created.
3) And lastly the install_name_tool command will modify the application binary to look for the library in the new location.
Thanks for reading my little tutorial on this. This process was really not as straight forward as it ought to be so I wanted others to benefit from this (as well as myself should I ever forget how to do this!). Any questions or if you would like me to change anything please login and leave a comment.
If you liked this article and would like to download a copy for reference you can download it:
Cheers
Brock
