Jan 23, 2011

How to Build OpenCV Static Libraries Mac OS X (10.5 compatible!)

ITP student Patrick Hebron and I have been working on a new Processing video library built on top of OpenCV (with the goal of no vdig on windows and better movie playback support all around.) This is all a bit obscure, but it was such a struggle to build stand-alone static libraries for OpenCV on Mac OS X (backwards compatible to 10.5) that we could link to via JNI that I thought I would document the process in case this comes up for anyone else in the future.

First of all, what is a static library and why should I care?

Some reading: http://en.wikipedia.org/wiki/Library_(computing)

Let’s say you are familiar with mac ports or homebrew or you’ve read some cryptic instructions online about how to download an open source project from a repository and built it via the command line. Most likely, you built that project and installed some files to usr/lib or opt/local/lib, etc. Most likely these files were “dynamic” or “shared” library files, meaning they can be used by various applications on your computer. This is a good thing and saves you from having multiple copies of libraries, one for each application that uses say, openCV or FFMPEG or something like that.

A static library is the opposite and cannot be shared. It is a library that is used for building a target application and essentially becomes embedded into that application. If you are an openFrameworks or Cinder user, you may have encountered static libraries. They are the .a files that are referenced by your xcode project. For example:

In the case of building a Processing library (or compiling an OF or Cinder application), we’re looking to distribute something that does not require a separate install. We don’t want to say, here is some code you can use but before you can use it, take a whole day to figure out how to build opencv from the source and install it to this strange directory on your machine.

So, if you need to build OpenCV from source to static libraries to link from an xcode project, here is how you do it.

Step 1. Get the OpenCV source

You can download it from here:

http://sourceforge.net/projects/opencvlibrary/

or use the command line to get it via SVN:

cd ~/wherever/you/want/to/put/it
svn co https://code.ros.org/svn/opencv/trunk

Step 2. Use the CMake GUI to create “make” files

You can do all this with unix commands via terminal, but I found the Cmake Gui to be quite useful. You can download it here:

http://www.cmake.org/cmake/resources/software.html

When you run CMake, you have to select two directories. “Where is the source code” — browse to the directory where you downloaded OpenCV. “Where to build the binaries” — pick a directory where you want to build the shared libraries. Here’s what it looks like on my machine:

Now press the “configure” button.

You’ll then be asked to specify a generator. If you prefer to use an IDE, select “Xcode.” If you’d like to build it via terminal, select “Unix Make files.” For the purposes of this tutorial, I’ll pick Xcode.

Once you hit ok (and wait a minute or so), all of the build options will suddenly appear in the center of the CMake window. Here’s where things get a little tricky and what you need to select can be an “it depends” on what exactly you are doing this for. Here are the settings I am using:

• Uncheck “BUILD_NEW_PYTHON_SUPPORT” (I don’t need python)
• Uncheck “BUILD_SHARED_LIBRARIES” (This is important, this will cause it to build the static libraries instead of shared!)
• Uncheck “BUILD_TESTS” (Don’t need these)
• Add “I386″ to CMAKE_OSX_ARCHITECTURES. I’m looking for these static libraries to be backwards compatible to 32-bit systems and Leopard (and Processing runs in 32-bit only) so this is the architecture I’m using, but you might choose some different.
• Change “CMAKE_OSX_SYSROOT” to /Developer/SDKs/MacOSX10.5.sdk. Same thing as previous item.
• Uncheck “WITH_FFMPEG”. You’ll get errors unless you have FFMPEG on your system
• Uncheck “WITH_D1394″. Same thing, you’ll get errors unless you have D1394 on your system.
• Check “WITH_QUICKTIME”. You may want to leave this out. For me, I need to use QUICKTIME (instead of the newer QTKit) because of a weird threading error that happens with Java. I’m hoping to eventually sort this threading error out so that we can use the QTKit framework.

After you have finished your settings, press “Configure” again. Then press “Generate”.

Step 3. Build the static libs!

If you picked “Xcode”, you’ll now have an XCode project in your directory that you can open!

If you used Unix make, you can then browse to the directory via terminal and type “make”!

Once you build the project, you’ll see you have the following static libs in these directorys:

/lib/libopencv_calib3d.a
/lib/libopencv_flann.a
/lib/libopencv_imgproc.a
/lib/libopencv_video.a
/lib/libopencv_contrib.a
/lib/libopencv_gpu.a
/lib/libopencv_legacy.a
/lib/libopencv_core.a
/lib/libopencv_haartraining_engine.a
/lib/libopencv_ml.a
/lib/libopencv_features2d.a
/lib/libopencv_highgui.a
/lib/libopencv_objdetect.a
/3rdparty/lib/liblibjasper.a
/3rdparty/lib/liblibjpeg.a
/3rdparty/lib/liblibpng.a
/3rdparty/lib/liblibtiff.a
/3rdparty/lib/libopencv_lapack.a
/3rdparty/lib/libzlib.a

Here are some good additional references I used:

For building OpenCV 1.0
http://ildan.blogspot.com/2009/11/creating-universal-static-opencv.html

Some backwards compatibility tips:
http://cocoawithlove.com/2009/09/building-for-earlier-os-versions-in.html

OF Forum discussion:
http://www.openframeworks.cc/forum/viewtopic.php?f=10&t=4943

Cinder forum discussion:
http://forum.libcinder.org/topic/opencv-status

Questions, comments, things I missed? Let me know!