Sometimes, you may want to change the OpenCV itself, for example, to add some new cool feature, or to fix a bug. OpenCV's BSD-like license allows you to modify the library, and we'll learn how one can build a custom version of OpenCV.
There is no source code for this recipe, as we're going to build OpenCV. You will need a Git command-line client, CMake (Version 2.8.11 or higher), and Python 2.7 installed. Usually, Python is already installed on Mac OS, but the CMake tool needs to be downloaded from http://cmake.org. And, you don't need an iOS device, because the compilation is done on a host computer (so-called cross-compilation).
The following are the steps required to get your custom OpenCV build:
Create a new directory and clone OpenCV's source code repository there.
Check out the proper Git branch or tag.
Create a symbolic link to Xcode.
Run the Python script to build the iOS framework.
Update your project(s) to link to a new framework.
Modify the OpenCV code and rebuild the framework if needed.
Let's implement the described steps:
Almost all operations in this recipe should be executed on the Terminal. So, create a new Terminal window and create a new working directory for our experiments:
$ mkdir ~/<working_directory> $ cd <working_directory>
Then we need to clone OpenCV sources, and we'll use the GitHub repository for that:
$ git clone https://github.com/Itseez/opencv.gitWhen complete, we have to check out the branch or tag, which we're going to use as a starting point. Let's imagine we want to build the latest state of the 2.4 branch, which is used for the OpenCV 2.4.x releases' preparation:
$ cd opencv $ git checkout 2.4
Now, let's create a symbolic link to Xcode, so the build script can see the compiler, header files, and so on:
$ cd / $ sudo ln -s /Applications/Xcode.app/Contents/Developer Developer
We're now ready to build the framework. Please be patient, because it will take a while. OpenCV is going to be built in three different configurations, and it may take a couple of minutes:
$ cd ~/<working_directory> $ python opencv/platforms/ios/build_framework.py build_ios
After the process is complete, your framework will be available at
~/<my_working_directory>/build_ios/opencv2.framework. You can now add this framework to your Xcode projects, as we did before. When rebuilt, your projects will use this new version of OpenCV.If you want to change something in OpenCV, you can edit its code and rerun the script. If that is possible, unchanged binaries from the previous build will be used, and the compilation will be faster than it was the first time.
As we mentioned before, iOS frameworks are a better way to distribute your static libraries. In its core, they are simple libraries and headers, but they may contain binary code for several architectures (such as armv7, armv7s, and i386 in our example). That makes them more convenient to link from Xcode projects, because you need not think about linker configuration, rather, you can simply add a reference to the framework.
So, the only interesting moment in this recipe is how the build_framework.py script constructs the OpenCV framework. You can actually study its source code to get complete understanding. For every architecture (old and new iOS devices, plus Simulator), it generates an Xcode project using CMake and executes Xcode in order to build it. When all three configurations are built, script forms the ~/<my_working_directory>/build_ios/opencv2.framework directory properly, so it becomes a valid iOS framework.
When the script finishes its work, you can use the built framework as a normal OpenCV distribution.
Despite the fact that it is quite easy to create your custom version of OpenCV, we encourage you to use the official one. The library is always in active development; new versions are rolled out regularly, so if you don't want to waste too much time merging your changes, better to stick to the official distribution.
All new source code should be developed outside of the library itself, as we did with the CvEffects project. And, if your development grows into something stable and useful, you can always contribute your code as a new OpenCV module, or as an extension to the existing one.
In case you've found a bug, you can live with your custom build for some time. But you should submit a GitHub pull request with the fix, so it is integrated into the development branches as soon as possible. The same rule applies to performance optimizations. If your code is faster, but still generic enough (you have tested it on multiple platforms and with different parameters), you can submit a pull request. This way we will have an even more stable and efficient library!
More information on the contribution process is available on the official website at http://opencv.org/contribute.html.