To build the latest release of Imath, download the source (.zip or .tar.gz) from the releases page https://github.com/AcademySoftwareFoundation/Imath/releases.
To build from the latest development version, clone the GitHub repo directly via:
% git clone https://github.com/AcademySoftwareFoundation/Imath.git
The main branch is the most recent development version, which
may be unstable, but the release branch always points to the most
recent and most modern, stable, released version.
Note: The GitHub repository identifies a "latest" release, which
GitHub defines as the release containing the most recent commit, which
may correspond to a patch for an earlier minor release. Therefore, the
release labled "latest" is not always the most modern or preferable
version. If you want the most modern release, use the releases
branch.
In the instructions that follow, we will refer to the top-level
directory of the source code tree as $source_directory.
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
To build via CMake, first choose a location for the build directory,
which we will refer to as $build_directory.
% mkdir $build_directory
% cd $build_directory
% cmake $source_directory
% make
% make install
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 $build_directory 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.
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=$install_directory
The Imath documentation at imath.readthedocs.io is generated via Sphinx with the Breathe extension using information extracted from header comments by Doxgen.
To build the documentation locally from the source headers and
.rst files, set the CMake option DOCS=ON. This adds
Doxygen and Sphinx CMake targets. Local documentation
generation is off by default.
Building the documentation requires that sphinx, breathe, and doxygen are installed.
To build and install the optional Python bindings for Imath, set the
CMake option PYTHON=ON.
The Python bindings require that boost_python is installed. By
default, the bindings build for Python 3. To build with python 2, set
the CMake option USE_PYTHON2=ON.
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 something like 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.29
libImath-3_1.so.29 -> libImath-3_1.29.0.1
The actual shared object file is appended with the library interface
version name, formed according to the libtool versioning
scheme:
current.revision.age.
Note that the libImath.so symlink is ommitted if the
IMATH_INSTALL_SYM_LINK option is disabled.
You can configure the IMATH_LIB_SUFFIX, although it defaults to
the library major and minor version, so in the case of a 3.1 release,
it would default to -3_1. You would then link your programs against
this versioned library to have maximum safety (i.e. -lImath-3_1),
and the pkg-config and CMake configuration files included with
find_package should set this up.
The versioned libraries will have the -d suffix when the
CMAKE_BUILD_TYPE is Debug.
Normally, all Imath symbols are in the Imath namespace, but you
can control this at CMake time via the IMATH_NAMESPACE and
IMATH_INTERNAL_NAMESPACE CMake settings.
These settings specify an IMATH_INTERNAL_NAMESPACE preprocessor
definition that places all of the Imath symbols within the given
namespace rather than the standard Imath namespace. Those symbols
are made available to client code through the IMATH_NAMESPACE in
addition to the IMATH_INTERNAL_NAMESPACE. See
Imath/ImathConfig.h for details.
To ensure source code compatibility, the IMATH_NAMESPACE defaults
to Imath and then using namespace IMATH_INTERNAL_NAMESPACE;
brings all of the declarations from the IMATH_INTERNAL_NAMESPACE
into the IMATH_NAMESPACE. This means that client code can
continue to use syntax like Imath::V3f, but at link time it will
resolve to a mangled symbol based on the IMATH_INTERNAL_NAMESPACE.
As an example, if one needed to build against a newer version of Imath and have it run alongside an older version in the same application, it is possible to use an internal namespace to prevent collisions between the older versions of Imath symbols and the newer ones. To do this, the following could be defined at build time:
% cmake -DIMATH_INTERNAL_NAMESPACE=Imath_v2 $source_directory
This means that declarations inside Imath headers look like this (after the preprocessor has done its work):
namespace Imath_v2 {
...
class declarations
...
}
namespace Imath {
using namespace Imath_v2;
}
When either cross-compiling for a different platform, or when
specifying a compiler set to match the VFX reference platform
(https://vfxplatform.com/), CMake provides the idea of a toolchain,
which may be useful instead of having to remember a chain of
configuration options. This also means that platform-specific compiler
names and options are kept out of the main CMakeList.txt file,
which provides better isolation.
A toolchain file is simply a CMake script that sets compiler and
related flags and is run early in the configuration step, prior to
CMake's automatic discovery step. These options can still be set on
the command line if that is clearer, but a theoretical toolchain file
for compiling for VFX Platform 2021 is provided in the source tree at
cmake/Toolchain-Linux-VFX_Platform21.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:
- Toolchains: https://cmake.org/cmake/help/v3.12/manual/cmake-toolchains.7.html
- Cross compiling: https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/
The default CMake configuration options are stored in
Imath/config/ImathSetup.cmake. To see a complete set of option
variables, run:
% cmake -LAH $source_directory
Via standard cmake operation, you can customize these options three ways:
- Modify the
.cmakefiles in place. - Use the UI
cmake-guiorccmake. - Specify them as command-line arguments via -D when you invoke cmake.
IMATH_CXX_STANDARD
C++ standard to compile against. Default is 14.
IMATH_HALF_USE_LOOKUP_TABLE
Use the half-to-float conversion lookup table. Default is ON for
backwards compatibility. With the value of OFF, use a bit-shift
conversion algorithm. Note that this setting is overriden when
compiler flags enable the F16C SSE instruction set.
IMATH_USE_DEFAULT_VISIBILITY
Use default visibility, which makes all symbols visible in compiled
objects. Default is OFF, in which case only designated
necessary symbols are marked for export.
IMATH_USE_NOEXCEPT
Use the noexcept specifier of appropriate methods. Default is
ON. With the value of OFF, the noexcept specifier is
omitted, for situations in which it is not desireable.
IMATH_ENABLE_LARGE_STACK
Enables the halfFunction object to place the lookup tables on
the stack rather than allocating heap memory. Default is OFF.
IMATH_VERSION_RELEASE_TYPE
A string to append to the version
number in the internal package name macro
IMATH_PACKAGE_STRING. Default is the empty string, but can be set
to, for example, "-dev" during development (e.g. "3.1.0-dev").
IMATH_INSTALL_SYM_LINK
Install an unversioned symbolic link (i.e. libImath.so) to the
versioned library.
IMATH_INSTALL_PKG_CONFIG
Install Imath.pc file. Default is ON.
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). Default is NO.
IMATH_LIB_SUFFIX
String added to the end of all the versioned libraries. Default is
-<major>_<minor>
IMATH_OUTPUT_SUBDIR
Destination sub-folder of the include path for install. Default is Imath.
DOCS
Build the html documentation. Default is OFF.
PYTHON
Build the optional Imath python bindings. Default is OFF.
The Python bindings require that boost_python is installed.
USE_PYTHON2 If ON and PYTHON is also ON, build the
bindings for Python 2. Default is OFF, implying that the default
bindings are built for Python 3.
PYIMATH_OVERRIDE_PYTHON_INSTALL_DIR
Custom destination for installatation of imath.so and
imathnumpy.so modules. By default, they go into either
site-packages or ``dist-packages`.
To enable half-to-float conversion using the F16C SSE instruction set
for g++ and clang when installing Imath, add the -mf16c compiler
option:
% cmake <Imath source directory> -DCMAKE_CXX_FLAGS="-mf16c"
See the Imath Technical Documentation for more information about the half-float conversion process.
-
BUILD_SHARED_LIBS- CMake standard variable to select a static or shared build. Default isON. -
BUILD_TESTING- Build the runtime test suite. Default isON.
If you have ninja (https://ninja-build.org/) installed, it is faster than make. You can generate ninja files using CMake when doing the initial generation:
% cmake -G “Ninja” ..
If you would like to confirm compile flags, you don’t have to specify the verbose configuration up front, you can instead run
% make VERBOSE=1