84 lines
3.5 KiB
Plaintext
84 lines
3.5 KiB
Plaintext
------------------------------------------------
|
|
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 <ImfForward.h>,
|
|
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.
|