Checking out and building OpenImageIO

From OpenImageIO Wiki

Jump to: navigation, search

There is a separate page on Building OpenImageIO on Windows.


Contents

Checking out the code

OpenImageIO is maintained by Subversion, with our server at http://svn.openimageio.org .

Main project: development trunk

You can check out a copy of the OpenImageIO development trunk with this command: 

    svn checkout http://svn.openimageio.org/oiio/trunk oiio-trunk


Release Branches

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: 

    svn ls http://svn.openimageio.org/oiio/branches

The ones that are named RB-x.y are release branches. The one with the highest number is the current release branch.

You can check out a copy of a release branch with this command: 

    svn checkout http://svn.openimageio.org/oiio/branches/RB-0.8 oiio-0.8

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 trunk, which often has new features added, bugs unintentionally introduced, and may sometimes change APIs in a non-back-compatible way.)


External programs

We have a separate svn project containing snapshots of most of the external (3rd party) open source libraries that OpenImageIO depends on. This makes things very convenient for developers, since you can be assured that you are using the same versions of these libraries as the other OIIO developers, without worrying about separately building and installing each of those dependency libraries, or what versions are on your system.

You can check out and build the external packages like this: 

    svn checkout http://svn.openimageio.org/external/trunk external
    cd external
    make

Fully making all of these packages may take quite some time. The compiled packages will all end up in external/dist/ARCH, where ARCH is the name of the platform you are building for (linux, linux64, macosx, or windows).

You will need to set the environment variable THIRD_PARTY_TOOLS_HOME to the dist area of the external tools, in order for the OIIO build to recognize it. For example, on Linux or OS X, with bash/ksh, try: 

    export THIRD_PARTY_TOOLS_HOME=/path/to/external/dist/ARCH

(where, again, ARCH is replaced with the name of the architecture you built).


There is one additional dependency which is not part of the external project -- Qt4. You can download it from Qt download page, if it's not already on your system.

No external project

You don't have to check out and build the external project. OIIO's build system will try to find all the packages it needs on your system. But in such a case, your system needs to have the following packages installed in the usual places: Boost, GLEW, IlmBase, Jpeg-6b, libpng, OpenEXR, libtiff, and zlib. And you'd better hope the versions of all these are sufficiently recent. And you still need Qt4.


Building OpenImageIO

Platforms Supported

We know that OpenImageIO builds correctly on:

Building

1. Check out a development branch of OpenImageIO, for example: 

    svn checkout http://svn.openimageio.org/oiio/trunk oiio-trunk

2. Check out and build the "external" project (see the instructions above). The "external" project and the OIIO project ("oiio-trunk", in the example above) should be sibling directories. If your system doesn't already have Qt4, you'll need to download it from Qt download page.

3. If you're on one of the platforms we are already supporting, you should be able to do a build like this: 

   cd oiio-trunk
   make

Assuming the build succeeds, you will find a complete OpenImageIO distribution tree in oiio-trunk/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, and doc 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 lib subdirectory.

We have a Build Troubleshooting page to check if you run into trouble.


Build modes and options

There are a few make commands and targets you should know about:

make help
Print all the make targets.
make
Build OpenImageIO in optimized mode, storing the results in dist/ARCH. Temporary files (object files, etc.) will be stored in build/ARCH.
make debug
Build OpenImageIO in debug mode, storing the results in dist/ARCH.debug. Temporary files (object files, etc.) will be stored in build/ARCH.debug. This is equivalent to "make DEBUG=1".
make clean
Delete the temporary files in build/ARCH, but leave the fully-built libraries and binaries in dist/ARCH. To similarly clear the debug version, try "make DEBUG=1 clean".
make realclean
Delete both build/ARCH and dist/ARCH. To similarly clear the debug version, try "make DEBUG=1 clean".
make nuke
Delete dist and build areas for all architectures and build modes (equivalent to "rm -rf build dist").
make test
Run the OpenImageIO test suite (requires ../oiio-testimages to be installed -- see the following section).
make SHOWCOMMANDS=1
Do a build (with optional targets) showing the exact compile and link commands. This can be useful for debugging the makefiles themselves.
make EMBEDPLUGINS=1
Builds OpenImageIO (with optional targets) in a special mode where the ImageIO plugins are built into libOpenImageIO.so so that at runtime, the separate plugins are not needed, and there is no need for users to set the IMAGEIO_LIBRARY_PATH environment variable. Some uses of OpenImageIO may prefer this setup.
make USE_OPENGL=0
Builds only the part of OpenImageIO that doesn't need OpenGL (i.e., builds everything but iv). Use this if you don't have OpenGL but want to build everything but the viewer. This is also handy if you lack Qt, because iv is also the only part of OpenImageIO that needs Qt.

Test images

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. 

    svn checkout http://svn.openimageio.org/oiio-testimages/trunk 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 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").

See also

Retrieved from "http://openimageio.org/wiki/index.php?title=Checking_out_and_building_OpenImageIO"