Prerequisites¶

Make sure these are installed on your system before building OpenEXR:

• OpenEXR requires CMake version 3.14 or newer

• C++ compiler that supports C++17

• Imath (auto-fetched by CMake if not found) (https://github.com/AcademySoftwareFoundation/Imath)

• libdeflate (internal copy used by CMake if not found forv3.4+; auto-fetched in v3.3 and before) (https://github.com/ebiggers/libdeflate)

• openjph (auto-fetched by CMake if not found; new in v3.4) (https://github.com/aous72/OpenJPH)

• (optional) Intel’s Thread Building Blocks library (TBB)

The instructions that follow describe building OpenEXR with CMake.

Note that as of OpenEXR 3, the Gnu autoconf bootstrap/configure buildsystem is no longer supported.

OpenEXR/Imath Version Compatibility¶

In most circumstances, follow this best practice:

• When building OpenEXR v3.4+, use Imath v3.2

• When building OpenEXR v3.3 or before, use Imath v3.1.

OpenEXR v3.X isfunctionally compatible with any v3.Y release ofImath. Therefore, if you have control over how OpenEXR and Imath arebuilt in your application or facility, any combination of OpenEXR v3.Xand Imath v3.Y can be built successfully from source.

However, an OpenEXR v3.X distibution (i.e. compiledlibOpenEXRlibrary) built against a specific v3.Y minor release of Imathrequires that minor Imath release as both a build-time and run-timedependency. Furthermore, application code compilation units that usea specific OpenEXR v3.X distibution must be built using the associatedImath release.

OpenEXR uses Imath symbols in its public API, and both Imath andOpenEXR use suffixed namespaces that embed the minor releaseversion. For example, theV3fAttribute class in a distribution ofOpenEXR v3.4 built against Imath v3.2 is a template instantiation ofImf_3_4::TypedAttribute<Imath_3_2::Vec3<float>>, while thecorresponding class for a distribution of OpenEXR v3.4 built againstImath v3.1 will beImf_3_4::TypedAttribute<Imath_3_1::Vec3<float>>, a differentsymbol.

This means thatit is insufficient to identify a distribution ofOpenEXR by its ``major.minor`` release numbers alone. Youmustfurther identify the distribution of Imath that it was built against,e.g. “OpenEXR v3.4 w/Imath v3.2”.

It is problematic for a single application to use, for example,OpenEXR v3.4 compiled against Imath v3.2, while simultaneously using adistribution of OpenEXR v3.4 built against Imath v3.1. Both sets ofOpenEXR symbols would reside in a single namespace(i.e.Imf_3_4::), but the Imath types would differ between the two(i.e.Imath_3_2:: vsImath_3_1::). It is also problematic forapplication compilation units to use Imath classes directly,independent of OpenEXR, if they also include OpenEXR headers from adistribution built with a different Imath version.

Linux/macOS¶

To build via CMake, you need to first identify three directories:

1. The source directory, i.e. the top-level directory of thedownloaded source archive or cloned repo, referred to below as$srcdir

2. A temporary directory to hold the build artifacts, referred to below as$builddir

3. A destination directory into which to install thelibraries and headers, referred to below as$installdir.

To build:

% cd $builddir% cmake $srcdir --install-prefix $installdir% cmake --build $builddir --target install --config Release

Note that the CMake configuration prefers to apply an out-of-treebuild process, since there may be multiple build configurations(i.e. debug and release), one per folder, all pointing at once sourcetree, hence the$builddir noted above, referred to in CMakeparlance as thebuild directory. You can place this directorywherever you like.

See the CMake Configuration Options section below for the most commonconfiguration options especially the install directory. Note that withno arguments, as above,makeinstall installs the header files in/usr/local/include, the object libraries in/usr/local/lib, and theexecutable programs in/usr/local/bin.

Windows¶

Under Windows, if you are using a command line-based setup, such ascygwin, you can of course follow the above. For Visual Studio, cmakegenerators are “multiple configuration”, so you don’t even have to setthe build type, although you will most likely need to specify theinstall location. Install Directory By default,makeinstallinstalls the headers, libraries, and programs into/usr/local, but youcan specify a local install directory to cmake via theCMAKE_INSTALL_PREFIX variable:

% cmake .. -DCMAKE_INSTALL_PREFIX=$openexr_install_directory

Library Suffix¶

TheOPENEXR_LIB_SUFFIX CMake option designates a suffix for thelibrary and appears between the library base name and the.so. This defaults to encode the major and minor version, as in-3_1:

libOpenEXR.so->libOpenEXR-3_1.solibOpenEXR-3_1.so->libOpenEXR-3_1.so.30libOpenEXR-3_1.so.30->libOpenEXR-3_1.so.30.3.2.0libOpenEXR-3_1.so.30.3.2.0(thesharedobjectfile)

Uninstall¶

If you did a binary install of OpenEXR via a package manager(apt-get,yum,port,brew, etc), use the package manager touninstall.

If you have installed from source,and you still have the buildtree from which you installed, you can uninstall via:

% cmake --build $builddir --target uninstall

or if usingmake:

%makeuninstall

Theuninstall relies on CMake’sinstall_manifest.txt for the recordof what was installed.

Library Naming Options¶

• OPENEXR_LIB_SUFFIX

  Append the given string to the end of all the OpenEXRlibraries. Default is-<major>_<minor> version string. Pleasesee the section on library names

Imath Dependency¶

• CMAKE_PREFIX_PATH

  The standard CMake path in which to search for dependencies, Imathin particular. A comma-separated path. Add the root directory whereImath is installed.

• Imath_DIR

  The config directory where Imath is installed. An alternative tousingCMAKE_PREFIX_PATH. Note thatImath_DIR shouldbe set to the directory that includes theImathConfig.cmakefile, which is typically thelib/cmake/Imath folder of the rootinstall directory.

• OPENEXR_IMATH_REPO andOPENEXR_IMATH_TAG

  The github Imath repo to auto-fetch if an installed library cannotbe found, and the tag to sync it to. The default repo ishttps://github.com/AcademySoftwareFoundation/Imath.git and thetag is specific to the OpenEXR release. The internal build isconfigured as a CMake subproject.

• OPENEXR_FORCE_INTERNAL_IMATH

  If set toON, force auto-fetching and internal building of ImathusingOPENEXR_IMATH_REPO andOPENEXR_IMATH_TAG. This meansdonot use any existing installation of Imath.

libdeflate Dependency¶

As of OpenEXR release v3.2, OpenEXR depends onlibdeflate forDEFLATE-based compression. Previous OpenEXR releases relied onzlib.

As of OpenEXR release v3.4, OpenEXR ships with an internal “vendored”copy of thelibdeflate compression code. At configuration time, ifCMake finds an external installation oflibdeflate, it will useit. If it fails to find an installation, it will use the internalcopy. To force use of the internal copy, configure with-DOPENEXR_USE_INTERNAL_DEFLATE=ON.

OpenEXR release v3.2 and v3.3 auto-fetch thelibdeflate source andbuild it internally if cmake does not find an externalinstallation. The internal build is linked statically, so no extrashared object is produced. Configuration options are:

• OPENEXR_DEFLATE_REPO andOPENEXR_DEFLATE_TAG

  The GitHublibdeflate repo to auto-fetch if an installed library cannotbe found, and the tag to sync it to. The default repo ishttps://github.com/ebiggers/libdeflate.git and the tag isv1.18. The internal build is configured as a CMake subproject.

• OPENEXR_FORCE_INTERNAL_DEFLATE

  If set toON, force auto-fetching and internal building oflibdeflate usingOPENEXR_DEFLATE_REPO andOPENEXR_DEFLATE_TAG. This means donot use any existinginstallation oflibdeflate.

TBB Dependency¶

OpenEXR can optionally use the TBB library as the default globalthread pool as a thread provider. This allows applications which alsouse TBB for other purposes to lower the number of active threads. Withhigh core count machines more prevalent, this can significantly lowerthe number of active threads and so the improve available resourcesespecially when compiling with a static library and using pluginswhich use OpenEXR.

This is disabled by default, but when turned on, assumes the OneAPIversion of TBB which provides cmake modules. This ONLY changes theglobal thread pool as otherwise this can cause mutex deadlocks if youcreate other ThreadPools thinking that they are separate threads (i.e.the previous use case), but TBB shares actual threads and uses anarena to control thread usage.

To enable this, set the flag during config:

cmake-DOPENEXR_USE_TBB=ON...

Namespace Options¶

• OPENEXR_IMF_NAMESPACE

  Public namespace alias for OpenEXR. Default isImf.

• OPENEXR_INTERNAL_IMF_NAMESPACE

  Real namespace for OpenEXR that will end up in compiledsymbols. Default isImf_<major>_<minor>.

• OPENEXR_NAMESPACE_CUSTOM

  Whether the namespace has been customized (so external users know)

• IEX_NAMESPACE

  Public namespace alias for Iex. Default isIex.

• IEX_INTERNAL_NAMESPACE

  Real namespace for Iex that will end up in compiled symbols. DefaultisIex_<major>_<minor>.

• IEX_NAMESPACE_CUSTOM

  Whether the namespace has been customized (so external users know)

• ILMTHREAD_NAMESPACE

  Public namespace alias for IlmThread. Default isIlmThread.

• ILMTHREAD_INTERNAL_NAMESPACE

  Real namespace for IlmThread that will end up in compiledsymbols. Default isIlmThread_<major>_<minor>.

• ILMTHREAD_NAMESPACE_CUSTOM

  Whether the namespace has been customized (so external users know)

Component Options¶

• BUILD_TESTING

  Build the testing tree. Default isON. Note thatthis causes the test suite to be compiled, but it is notexecuted. To execute the suite, run “make test”.

• OPENEXR_RUN_FUZZ_TESTS

  Controls whether to include the fuzz tests (very slow). Default isOFF.

• OPENEXR_BUILD_TOOLS

  Build the binary programs (exrheader, exrinfo,exrmakepreview, etc). Default isON.

• OPENEXR_INSTALL_TOOLS

  Install the binary programs (exrheader, exrinfo,exrmakepreview, etc). Default isON.

• OPENEXR_INSTALL_DEVELOPER_TOOLS

  Install the binary programs useful for developingand/or debugging OpenEXR itself (e.g. exrcheck).Default isOFF.

• OPENEXR_BUILD_EXAMPLES

  Build the example code. Default isON.

Additional CMake Options¶

See the CMake documentation for more information (https://cmake.org/cmake/help/v3.12/).

• CMAKE_BUILD_TYPE

  For builds when not using a multi-configuration generator. Availablevalues:Debug,Release,RelWithDebInfo,MinSizeRel

• BUILD_SHARED_LIBS

  This is the primary control whether to build static libraries orshared libraries / dlls (side note: technically a convention, hencenot an officialCMAKE_ variable, it is defined within cmake andused everywhere to control this static / shared behavior)

• OPENEXR_CXX_STANDARD

  C++ standard to compile against. This obeys the globalCMAKE_CXX_STANDARD but doesn’t force the global setting toenable sub-project inclusion. Default is17.

• CMAKE_CXX_COMPILER

  The C++ compiler.

• CMAKE_C_COMPILER

  The C compiler.

• CMAKE_INSTALL_RPATH

  For non-standard install locations where you don’t want to have tosetLD_LIBRARY_PATH to use them

• CMAKE_EXPORT_COMPILE_COMMANDS

  Enable/Disable output of compile commands during generation. DefaultisOFF.

• CMAKE_VERBOSE_MAKEFILE

  Echo all compile commands during make. Default isOFF.