ABOUT THE ILMBASE LIBRARIES
----------------------------

Half is a class that encapsulates our 16-bit floating-point format.

IlmThread is a thread abstraction library for use with OpenEXR
and other software packages.  It currently supports pthreads and
Windows threads.

Imath implements 2D and 3D vectors, 3x3 and 4x4 matrices, quaternions
and other useful 2D and 3D math functions.

Iex is an exception-handling library.

If you have questions about using the IlmBase libraries, you may want
to join our developer mailing list.  See http://www.openexr.com for
details.


LICENSE
-------

The IlmBase source code distribution is free software.  See the file
named COPYING (included in this distribution) for details.


BUILDING ILMBASE
----------------

To build IlmBase on GNU/Linux or other UNIX-like systems, do this:

./configure
make
make install

unless you obtained IlmBase directly from git, in which case you
should first read README.git


Please type :

./configure --help

for a list of options in relation to building IlmBase libraries. In
particular, peruse README.namespaces for information regarding the
use of namespaces in IlmBase and OpenEXR.


See README.OSX for details on building IlmBase in MacOS X.

Do `make check` to run the IlmBase confidence tests.  They should all
pass; if you find a test that does not pass on your system, please let
us know.

Other UNIX variants haven't been tested, but should be easy to build.
Let us know if you're having problems porting IlmBase to a particular
platform.

All include files needed to use the IlmBase libraries are installed in the
OpenEXR subdirectory of the install prefix, e.g. /usr/local/include/OpenEXR.


USING ILMBASE IN YOUR APPLICATIONS
----------------------------------

On systems with support for pkg-config, use `pkg-config --cflags
IlmBase` for the C++ flags required to compile against IlmBase
headers; and `pkg-config --libs IlmBase` for the linker flags required
to link against IlmBase libraries.

If you're using IlmBase from CVS, you should run the bootstrap script
to create the auto* files.  It's a good idea to run this whenever you
update IlmBase from CVS.

Then run './configure' and make.

Note that the configure.ac file requires a fairly new version of
automake.  If you get this error message:

running aclocal ...
aclocal: configure.ac: 142: macro `AM_CFLAGS' not found in library
aclocal: configure.ac: 143: macro `AM_CXXFLAGS' not found in library
failed!

you should upgrade your automake to version 1.6 or better.

IlmBase on MacOS X
------------------

Building IlmBase on MacOS X is just like building it on GNU/Linux.
Follow the instructions in the README file under BUILDLING ILMBASE,
but see below re: shared libraries.


Missing gnu automake tools on  Mac OS X 10.8+
------------------
Later versions of OS X ,10.8+, do not, by default have all the necessary
tools for building. In particular,  Autoconf and Automake may be missing.

The following commands will download and install the necessary components:

cd ~/myDevLoc
curl -OL http://ftpmirror.gnu.org/autoconf/autoconf-2.64.tar.gz
tar xzf autoconf-2.64.tar.gz
cd autoconf-2.64
./configure --prefix=~/myDevLoc/autotools-bin
make; make install

cd ~/myDevLoc
curl -OL http://ftpmirror.gnu.org/automake/automake-1.12.tar.gz
tar xzf automake-1.12.tar.gz
cd automake-1.12
./configure --prefix=~/myDevLoc/autotools-bin
make; make install

cd ~/myDevLoc
curl -OL http://ftpmirror.gnu.org/libtool/libtool-2.4.tar.gz
tar xzf libtool-2.4.tar.gz
cd libtool-2.4
./configure --prefix=~/myDevLoc/autotools-bin
make; make install


You may want to export the installation path for your convenience.
Finally, make sure that you have installed the command line tools for XCode.


Universal Builds on Mac OS X
------------------
OS X supports multiple architectures. By default, IlmBase will be built
for the system doing the building. For example, if you build IlmBase on
an Intel system, the libraries will be built for Intel.

You can specify building for a different architecture, or multiple architectures,
by passing the "--enable-osx-arch" flag to configure. Building for multiple
architectures requires that "--disable-dependency-tracking" be passed as well.

For example, to build for Intel and PowerPC:

./configure --enable-osx-arch="i386 ppc" --disable-dependency-tracking.

To build "4-way universal" for 32-bit and 64-bit Intel and PowerPC:

./configure --enable-osx-arch="i386 ppc x86_64 ppc64" --disable-dependency-tracking.

For more information on universal builds, see:

http://developer.apple.com/documentation/Porting/Conceptual/PortingUNIX/compiling/chapter_4_section_3.html

Earlier releases of IlmBase included an "--enable-osx-universal-binaries"
switch, which specifies a two-way universal build: Intel and PowerPC, 32-bit only.
This is still available, but deprecated in favor of the more flexible
"--enable-osx-arch" and "--enable-osx-sdk" switches.


Choosing an SDK on Mac OS X
------------------
OS X allows you to specify one of several SDKs, or sysroots. This allows you to
target systems other than the system that your build machine runs.

For example, if you are building on Mac OS X 10.4, but you need access to features
that were introduced in Mac OS X 10.5, you can build against the Mac OS X 10.5
versions of system libraries and headers.

You can choose to build IlmBase with a specific SDK using the "--enable-osx-sdk"
switch. For example:

./configure --enable-osx-sdk=MacOSX10.5.sdk

If you are building on Mac OS X 10.4 and want to build universal, you will need to
specify the universal version of the 10.4 SDK: MacOSX10.4u.sdk. Otherwise, you probably
don't need to specify an SDK.

For more information on sysroots, see:

http://developer.apple.com/documentation/DeveloperTools/gcc-4.2.1/gcc/Directory-Options.html


Shared libraries
----------------

IlmBase requires the "flat namespace" option when built as a shared
library.  You may have problems trying to use IlmBase shared libraries
with applications that expect OS X's two-level namespace.  We have not
tested the shared libs extensively, though they appear to work with
exrdisplay and exrheader, but use them at your own risk.  We will
support two-level namespace shared libs in a future release.

If you're using IlmBase from github, you should run the bootstrap script
to create the auto* files.  It's a good idea to run this whenever you
update IlmBase from github.

Then run './configure' and make.

Note that the configure.ac file requires a fairly new version of
automake.  If you get this error message:

running aclocal ...
aclocal: configure.ac: 142: macro `AM_CFLAGS' not found in library
aclocal: configure.ac: 143: macro `AM_CXXFLAGS' not found in library
failed!

you should upgrade your automake to version 1.6 or better.

------------------------------------------------
 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.

IlmBase is one of five software packages that were designed to work
together: IlmBase, OpenEXR, OpenEXR_Viewers, CTL and OpenEXR_CTL.
You may want to build Imath by itself, or together with one or more
of the other packages.

What follows are instructions for building all five packages.
If you want to build only IlmBase, stop after step 1.

A couple of notes before getting started:

- This is not the only way to do this. This document describes a path
that doesn't involve installing libraries into default system paths,
but rather, creates a standalone universe.
- Some of these steps may be a bit redundant, and will be optimized in
the future.
- The Debug versions of the libraries and tools are not required if
you are not going to be doing any debugging, and can be optionally
built.

The source will build under both Visual Studio versions 7 and 8, and
there are separate directories for the corresponding build files.  The
tag <vc7|8> is used in this document to describe the appropriate folder
in the path that corresponds to your the version of Visual Studio.

The Visual Studio project files assume, and help build out, a directory
called "Deploy".   In the end, this directory will contain the objects
that might then be moved away from the source for general running of the
compiled programs.  The directory structure at the end of compiling all
the related tools looks like this:

Deploy
  include
  lib
    Debug
    Release
  bin
    Debug
    Release
openexr-cvs (name as desired)
  IlmBase
  OpenEXR
  OpenEXR_Viewers
ctl-cvs (name as desired)
  CTL
  OpenEXR_CTL
fltk
  FL
  GL
  lib
nvidia
  include
    GL
    glh
  lib

If OpenEXR_Viewers is not being compiled, then fltk and nvidia will
not be needed, but that will be covered later.

Step 1. Compile IlmBase

  a. Point Visual Studio at the .sln file in vc\<vc7|8>\IlmBase in the
  IlmBase subdirectory

  b. Select the Release configuration and hit Build Solution.  This
  will create the Deploy directory, and copy the relevant parts to it.

  c. If the debug versions are desired, select the Debug configuration
  and hit Build Solution.  This will add the Debug directories to Deploy.

Step 2. Compile OpenEXR support

  a. Retrieve the zlib binaries. The project files are set up to link
     against the dll version of zlib, but can easily be changed to link
     against a static version, or a self-built version if desired.

    1. Go to http://www.zlib.net and download the precompiled DLL
       version of zlib (as of writing, zlib123-dll.zip)

    2. If you don't wish to put the files into your MS visual studio
       directories and install the dll into windows\system32:

        a. Put a copy of zlib1.dll into Deploy\bin\Release and
           Deploy\bin\Debug

        b. Copy the header files into Deploy\include

        c. Copy zdll.lib and zdll.exp into Deploy\lib\Release and
           Deploy\lib\Debug

  b. Open the Visual Studio project in OpenEXR\vc\<vc7|8>\OpenEXR.

  c. Select the Release configuration and build. The IlmImfTest
     program runs a confidence test of your build to make sure
     it is able to work, and may take some time to complete.

  d. Optionally select the Debug configuration and build.

Step 3. Compile CTL support

  a. Open the Visual Studio project in CTL\vc\<vc7|8>\CTL.

  b. Select the Release configuration and build. The IlmCtlTest
     program runs a confidence test of your build to make sure it is
     able to work, and may take some time to complete.

  c. Optionally select the Debug configuration and build.

Step 4. Compile OpenEXR_CTL support

  a. Open the Visual Studio project in OpenEXR_CTL\vc\<vc7|8>\OpenEXR_CTL.

  b. Select the Release configuration and build.

  c. Optionally select the Debug configuration and build.

Step 5. Compile OpenEXR_Viewers

  a. Open the appropriate Visual Studio project in
     OpenEXR_Viewers\vc\<vc7|8>\OpenEXR_Viewers depending on whether or not
     you want CTL support.

  b. exrdisplay requires fltk to work.

    1. Go to http://www.fltk.org and download fltk 1.1.7

    2. Open its project files and compile using the instructions they
       provide.

    3. Create the fltk directory at the top level of your directory
       structure as presented above and copy the FL, GL, and lib folders
       into the fltk directory

    4. exrdisplay links fltk statically, so no dll is needed.

  c. playexr requires the nvidia cg library as well as glut and glew.

    1. Setup the cg toolkit

      a. Go to http://developer.nvidia.com, the developer section and
         download the cg toolkit, version 1.5, and install it.  The path
         where you choose to install Cg is referred to by the
         <Cg install location> tag in the steps below.

      b. During the installation, if the integrate with visual studio
         option is selected, the header files will be automatically found.
         Otherwise, copy the directory <Cg install location>\Cg\include\Cg
         to Deploy\include\Cg

      b. Copy the cg.dll and cgGL.dll from the <Cg install location>\Cg\bin
         into Deploy\bin\Release and Deploy\bin\Debug, or otherwise make
         them available (put them in system32, add to path, etc.)

      c. Copy the cg.lib and cgGL.lib from <Cg install location>\Cg\lib
         into Deploy\lib\Release and Deploy\lib\Debug

    2. Make glut available. This can be done via several mechanisms.
       See step 4 below.

    3. Make glew available. This can be done via several mechanisms.
       http://glew.sourceforge.net is the master site for this
       library. See step 4 below.

    4. nVidia makes both glut and glew available in their SDK package,
       which is a fairly large download, but provides a wealth of other
       information on programming for the GPU, and is generally a useful
       package, so that is the path chosen for this set up.

      a. Go to http://developer.nvidia.com and download version 10 of the
         SDK and install it.  It will prompt you to install the Cg toolkit,
         but this is not necessary as it was handled in step 1.  The path
         where you choose to install the SDK is referred to by the
         <SDK install location> tag in the steps below.

      b. Make an nvidia folder at the top level, with an include and
         lib folder inside it.  Inside the lib folder, make Debug and
         Release folders.

      c. Copy the <SDK install location>\external\include\GL directory into
         nvidia\include the GL and glh folders into nvidia\include.

      d. Copy the glew headers in <SDK install location>\common\GLEW\include\GL
         into nvidia\include\GL.

      e. Copy <SDK install location>\common\GLEW\lib\glew32.lib and
         <SDK install location>\external\lib\glut32.lib into Deploy\bin\Release.

      f. Copy bin\glut32.dll and bin\glew32.dll into Deploy\bin\Release.

  d. Build the Release configuration of the OpenEXR_Viewers.

  e. Build the Debug configuration if desired.

At this point, the Deploy folder should be fully built out and ready
to be used.  Both exrdisplay and playexr are meant to be launched from
the command line, as they originated as unix commands, so open a command
prompt, cd to the Deploy\bin\Release folder and enjoy.