------------------------------------------------ On the use of namespace in IlmBase and OpenEXR ------------------------------------------------ v2.0 of the code base introduces user configurable namespaces for component libraries. This addition introduces the ability to deal with multiple versions of these libraries loaded at runtime. An example case: Application is built with OpenEXR v1.7, but the required plugin requires functionality from OpenEXR v2.0. By injecting the version number into the (mangled) symbols, via the namespacing mechanism, and changing the soname, via the build system, the developer can link his plugin against the v2.0 library At run time the dynamic linker can load both the 1.7 and 2.0 versions of the library since the library soname are different and the symbols are different. When building IlmBase or OpenEXR the following configure script options are available: --enable-namespaceversioning and --enable-customusernamespace -- Internal Library Namespace The option, --enable-namespaceversioning, controls the namespace that is used in the library. Without an argument (see below) the library will be built with a suffix made up of the major and minor versions. For example, for version 2.0.0, the internal library namespaces will be Imath_2_0, Iex_2_0, IlmThread_2_0 etc For additional flexibility and control, this option can take an additional argument in which case the internal library namespace will be suffixed accordingly. For example: ./configure --enable-namespaceversioning=ILM will result in the namespaces of the type Imath_ILM, Iex_ILM etc. This can be useful for completely isolating your local build. Code using the library should continue to use the namespace Imath, or for greater portability IMATH_NAMESPACE, to refer to objects in libImath. In particular, the explicit use of the internal namespace is discouraged. This ensures that code will continue to compile with customised or future versions of the library, which may have a different internal namespace. Similarily, for other namespaces in the libraries: Iex, IlmThread and IlmImf. Note that this scheme allows existing code to compile without modifications, since the 'old' namespaces Imath, Iex, IlmThread and IlmImf continue to be available, albeit in a slightly different form. This is achieved via the following, in the Imath case: namespace IMATH_INTERNAL_NAMESPACE {} namespace IMATH_NAMESPACE { using namespace IMATH_INTERNAL_NAMESPACE; } This is included in all header files in the Imath library and similar ones are present for the libraries Iex, IlmThread and IlmImf. The only exception to this is where user code has forward declarations of objects in the Imf namespace, as these will forward declare symbols in an incorrect namespace These forward declarations should be removed, and replaced with #include , which forward-declares all types correctly. -- Public/User Library Namespace The option, --enable-customusernamespace, can override the namespace into which we will 'export' the internal namespace. This takes an argument that sets the name of the custom user namespace. In the example above, IMATH_NAMESPACE could be resolved into something other than Imath, say Imath_MySpecialNamespace. In nearly all cases, this will not be used as per the above discussion regarding code compatibility. Its presence is to provide a mechanism for not prohibiting the case when the application must pass objects from two different versions of the library.