Windows users have a special page on Building OIIO on Windows.
You can clone a read-only copy our git repository: git clone git://github.com/OpenImageIO/oiio.git oiio
If you are using OpenImageIO for mission-critical uses, you probably want to be insulated from the day-to-day changes of the development trunk. There are a variety of other stable branches available, and you can see them with this command:
If you are are cloning our repository or forking on GitHub, be aware of the following branch names:
Release branches are well tested and very stable -- we only modify them to add critical bug fixes and never break backwards-compatibility of the APIs within a release branch. (In contrast to the "master" branch, aka trunk, which often has new features added, bugs unintentionally introduced, and may sometimes change APIs in a non-back-compatible way.)
We have a number of dependencies (some required, some optional). In general, the optional ones will be noticed at build time not to be present, and the build will exclude just the parts of OIIO that require them (such as support for a particular image file format that requires a specific library). Packages that OIIO wants include Boost, GLEW, IlmBase and OpenEXR, IJG's libjpeg, libpng, libtiff, zlib, and Qt. You should just use your usual system package installer to get all the dependent packages installed in the usual places on your system.
It's also possible to have dependent packages installed in some nonstandard location, which you may indicate by setting the environment variable THIRD_PARTY_TOOLS_HOME to the directory of the external tools.
We know that OpenImageIO builds correctly on:
1. Check out a development branch of OpenImageIO, as explained above.
2. Install required dependencies, Boost, libtiff and OpenEXR using your favorite package manager or installers (apt for Ubuntu, MacPorts or Homebrew for OSX).
3. (Optional) Install dependencies required to build the image viewer, iv: Qt, OpenGL and GLEW. For example, on OSX "port install qt4-mac" for MacPorts or "brew update; brew doctor; brew install qt" for Homebrew.
4. For any dependencies installed in non-standard locations, create appropriate environment variables to inform CMake (e.g. QTDIR).
5. If you're on one of the platforms we are already supporting, you should be able to do a build like this:
Assuming the build succeeds, you will find a complete OpenImageIO distribution tree in oiio/dist/ARCH, where ARCH is the code for the build platform (linux, linux64, macosx, or windows). Underneath this dist area, you will of course find bin, lib, include, anddoc subdirectories.
Currently, we don't have a formal "install" command -- you'll have to copy this dist area (or its contents) wherever you want them to go. To successfully use the resulting build, users should ensure that the bin directory is part of their execution $PATH, the lib directory is in their LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH, on OS X), and that the environment variable IMAGEIO_LIBRARY_PATH also points to the libsubdirectory.
We have a Build Troubleshooting page to check if you run into trouble.
There are a few make commands and targets you should know about:
We have yet another SVN project just for containing a set of sample images for testing OpenImageIO. We split test images into a separate SVN project in order to make the main source code tree smaller and simpler for people who don't need the test suite. The images should be installed into a sibling directory to the oiio repository called oiio-testimages.
Also, there are collections of images for some of the file formats we support, and make test expects them to also be present. To run full tests, you will need to download and unpack the test image collections into oiio-testimages from:
You do not need any of these packages in order to build or use OpenImageIO. But if you are going to contribute to OpenImageIO development, you probably want them, since it is required for executing OpenImageIO's test suite (when you run "make test").