Blob Blame History Raw
------------------------------------------------
 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.