------------------------------------------------

 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.