Install¶
The Imath library is available for download and installation in binary form via package managers on many Linux distributions. See https://pkgs.org/download/Imath for a complete list. The common ones that generally provide current releases include:
Beware that some distributions are out of date and only provide distributions of outdated releases OpenEXR. We recommend against using OpenEXR v2, and we strongly recommend against using OpenEXR v1.
On macOS, we do not recommend installation via HomeBrew because the distribution is outdated.
Please note that pip install openexr
installs the openexrpython module, which is not
affiliated with the OpenEXR project or the ASWF. Please direct
questions there.
Build from Source¶
Imath builds on Linux, macOS, Microsoft Windows via CMake, and is cross-compilable on other systems.
Download the source from the GitHub releases page page, or clone the repo.
The release
branch of the repo always points to the most advanced
release.
Prerequisites¶
Make sure these are installed on your system before building Imath:
Imath requires CMake version 3.12 or newer
C++ compiler that supports C++11
The instructions that follow describe building Imath with CMake.
Linux/macOS¶
To build via CMake, you need to first identify three directories:
The source directory, i.e. the top-level directory of the downloaded source archive or cloned repo, referred to below as
$srcdir
A temporary directory to hold the build artifacts, referred to below as
$builddir
A destination directory into which to install the libraries and headers, referred to below as
$installdir
.
To build: .. code-block:
$ 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-tree
build process, since there may be multiple build configurations
(i.e. debug and release), one per folder, all pointing at once source
tree, hence the $builddir
noted above, referred to in CMake
parlance as the build directory. You can place this directory
wherever you like.
See the CMake Configuration Options section below for the most common
configuration options especially the install directory. Note that with
no arguments, as above, make install
installs the header files in
/usr/local/include
, the object libraries in /usr/local/lib
, and the
executable programs in /usr/local/bin
.
Windows¶
Under Windows, if you are using a command line-based setup, such as
cygwin, you can of course follow the above. For Visual Studio, cmake
generators are “multiple configuration”, so you don’t even have to set
the build type, although you will most likely need to specify the
install location. Install Directory By default, make install
installs the headers, libraries, and programs into /usr/local
, but you
can specify a local install directory to cmake via the
CMAKE_INSTALL_PREFIX
variable:
$ cmake .. -DCMAKE_INSTALL_PREFIX=$Imath_install_directory
Library Names¶
By default the installed libraries follow a pattern for how they are named. This is done to enable multiple versions of the library to be installed and targeted by different builds depending on the needs of the project. A simple example of this would be to have different versions of the library installed to allow for applications targeting different VFX Platform years to co-exist.
If you are building dynamic libraries, once you have configured, built, and installed the libraries, you should see the following pattern of symlinks and files in the install lib folder:
libImath.so -> libImath-3_1.so
libImath-3_1.so -> libImath-3_1.so.30
libImath-3_1.so.30 -> libImath-3_1.so.30.3.0
libImath-3_1.so.30.3.0 (the shared object file)
The -3_1
suffix encodes the major and minor version, which can be
configured via the IMATH_LIB_SUFFIX
CMake setting. The 30
corresponds to the so version, or in libtool
terminology the
current
shared object version; the 3 denotes the libtool
revision
, and the 0
denotes the libtool
age
. See the
libtool
documentation for more details.
Porting Applications from OpenEXR v2 to v3¶
See the OpenEXR/Imath 2.x to 3.x Porting Guide for details about differences from previous releases and how to address them. Also refer to the porting guide for details about changes to Imath.
Building the Documentation¶
The Imath technical documentation at https://imath.readthedocs.io is generated via Sphinx with the Breathe extension using information extracted from header comments by Doxygen.
To build the documentation locally from the source headers and
.rst
files, set the CMake option BUILD_DOCS=ON
. This adds
Doxygen
and Sphinx
CMake targets and enables building the docs
by default. generation is off by default.
Building the documentation requires that sphinx
, breathe
, and
doxygen
are installed. It further requires the sphinx-press-theme, as indicated in the
requirements.txt
file.
CMake Build-time Configuration Options¶
The default CMake configuration options are stored in
cmake/ImathSetup.cmake
. To see a complete set of option
variables, run:
$ cmake -LAH $imath_source_directory
You can customize these options three ways:
Modify the
.cmake
files in place.Use the UI
cmake-gui
orccmake
.Specify them as command-line arguments when you invoke cmake.
Library Naming Options¶
IMATH_LIB_SUFFIX
Append the given string to the end of all the Imath libraries. Default is
-<major>_<minor>
version string. Please see the section on library names
Imath Dependency¶
CMAKE_PREFIX_PATH
The standard CMake path in which to search for dependencies, Imath in particular. A comma-separated path. Add the root directory where Imath is installed.
Namespace Options¶
IMATH_NAMESPACE
Public namespace alias for Imath. Default is
Imath
.IMATH_INTERNAL_NAMESPACE
Real namespace for Imath that will end up in compiled symbols. Default is
Imath_<major>_<minor>
.IMATH_NAMESPACE_CUSTOM
Whether the namespace has been customized (so external users know)
Component Options¶
BUILD_TESTING
Build the testing tree. Default is
ON
. Note that this causes the test suite to be compiled, but it is not executed. To execute the suite, run “make test”.
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. Available values:
Debug
,Release
,RelWithDebInfo
,MinSizeRel
BUILD_SHARED_LIBS
This is the primary control whether to build static libraries or shared libraries / dlls (side note: technically a convention, hence not an official
CMAKE_
variable, it is defined within cmake and used everywhere to control this static / shared behavior)IMATH_CXX_STANDARD
C++ standard to compile against. This obeys the global
CMAKE_CXX_STANDARD
but doesn’t force the global setting to enable sub-project inclusion. Default is14
.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 to set
LD_LIBRARY_PATH
to use themCMAKE_EXPORT_COMPILE_COMMANDS
Enable/Disable output of compile commands during generation. Default is
OFF
.CMAKE_VERBOSE_MAKEFILE
Echo all compile commands during make. Default is
OFF
.
Cross Compiling / Specifying Specific Compilers¶
When trying to either cross-compile for a different platform, or for tasks such as specifying a compiler set to match the VFX reference platform, cmake provides the idea of a toolchain which may be useful instead of having to remember a chain of configuration options. It also means that platform-specific compiler names and options are out of the main cmake file, providing better isolation.
A toolchain file is simply just a cmake script that sets all the
compiler and related flags and is run very early in the configuration
step to be able to set all the compiler options and such for the
discovery that cmake performs automatically. These options can be set
on the command line still if that is clearer, but a theoretical
toolchain file for compiling for VFX Platform 2015 is provided in the
source tree at cmake/Toolchain-Linux-VFX_Platform15.cmake
which
will hopefully provide a guide how this might work.
For cross-compiling for additional platforms, there is also an
included sample script in cmake/Toolchain-mingw.cmake
which shows
how cross compiling from Linux for Windows may work. The compiler
names and paths may need to be changed for your environment.
More documentation:
Ninja¶
If you have Ninja installed, it is faster than make. You can generate ninja files using cmake when doing the initial generation:
$ cmake -G “Ninja” ..