Installing OpenVDB
==================

Requirements
------------
- GNU GCC (gcc.gnu.org), version 4.1 or later
  or Intel ICC (software.intel.com), version 11.1 or later

- GNU gmake (www.gnu.org/software/make/), version 3.81 or later

- Boost (www.boost.org), version 1.42.0 or later
  (Linux: yum install boost-devel; OS X: port install boost +python26)

- libz (zlib.net)
  (Linux: yum install zlib-devel)

- OpenEXR (www.openexr.com), for the 16-bit float Half class in half.h

- Intel Threading Building Blocks (threadingbuildingblocks.org),
  version 3.0 or later

Other compilers or versions might work but have not been tested.


Optional:

- Doxygen 1.8 (www.stack.nl/~dimitri/doxygen/)

- CppUnit (www.freedesktop.org/wiki/Software/cppunit), version 1.10 or later
  (Linux: yum install cppunit-devel)

- Ghostscript (www.ghostscript.com), version 8.70 or later, for documentation
  in PDF format

- pdfLaTeX (www.pdftex.org), version 1.21 or later, for documentation
  in PDF format

- GLFW 2.7 (www.glfw.org), for the OpenVDB viewer

- OpenGL 3.2 or later, for the OpenVDB viewer

- Python 2.5, 2.6 or 2.7, for the Python module

- NumPy (www.numpy.org), for the Python module

- Epydoc (http://epydoc.sourceforge.net/), version 3.0 or later,
  for Python module documentation

Other versions might work but have not been tested.


Installation
------------
1.  Set values appropriate to your environment for the following variables
    at the top of the Makefile:

    INSTALL_DIR         the directory into which to install libraries,
                        executables and header files (e.g., /usr/local)

    BOOST_INCL_DIR      the parent directory of the boost/ header directory
                        (e.g., /usr/include)

    EXR_INCL_DIR        the parent directory of the OpenEXR/ header directory
    EXR_LIB_DIR         the directory containing libIlmImf, etc.
    EXR_LIB             linker flags for libIlmImf, libIlmThread, libIex
                        and libImath

    HALF_INCL_DIR       the parent directory of the OpenEXR/ header directory
                        (which contains half.h)
    HALF_LIB_DIR        the directory containing libHalf.so and/or libHalf.a
    HALF_LIB            linker flag(s) for the Half library (e.g., -lHalf)

    TBB_INCL_DIR        the parent directory of the tbb/ header directory
    TBB_LIB_DIR         the directory containing libtbb
    TBB_LIB             linker flag(s) for the TBB library (e.g., -ltbb)

    CONCURRENT_MALLOC_LIB_DIR
                        a directory containing a scalable, concurrent malloc
                        replacement library such as jemalloc or TBB malloc
                        (leave blank if no such library is available, but
                        be aware that using standard malloc in concurrent
                        code incurs a significant performance penalty)
    CONCURRENT_MALLOC_LIB
                        linker flag(s) for the malloc replacement library
                        (e.g., -ltbbmalloc_proxy -ltbbmalloc)

    CPPUNIT_INCL_DIR    the parent directory of the cppunit/ header directory
                        (leave blank if CppUnit is not available)
    CPPUNIT_LIB_DIR     the directory containing libcppunit.so or libcppunit.a
    CPPUNIT_LIB         linker flag(s) for the cppunit library
                        (e.g., -lcppunit)

    GLFW_INCL_DIR       the directory containing glfw.h
                        (leave blank if GLFW is not available;
                        GLFW is needed only for the command-line viewer tool)
    GLFW_LIB_DIR        the directory containing libglfw
    GLFW_LIB            linker flags for the GLFW library (e.g., -lglfw)

    PYTHON_VERSION      the version of Python for which to build the OpenVDB
                        module (e.g., 2.6)
                        (leave blank if Python is unavailable)
    PYTHON_INCL_DIR     the directory containing the Python.h header file
                        (on OS X, this is usually /System/Library/Frameworks/
                        Python.framework/Versions/$(PYTHON_VERSION)/Headers)
    PYCONFIG_INCL_DIR   the directory containing the pyconfig.h header file
                        (usually but not always the same as PYTHON_INCL_DIR)
    PYTHON_LIB_DIR      the directory containing the Python library
                        (on OS X, this is usually /System/Library/Frameworks/
                        Python.framework/Versions/$(PYTHON_VERSION)/lib)
    PYTHON_LIB          linker flags for the Python library
                        (e.g., -lpython2.6)
    BOOST_PYTHON_LIB_DIR
                        the directory containing the Boost.Python library
    BOOST_PYTHON_LIB    linker flags for the Boost.Python library
                        (e.g., -lboost_python-mt)
    NUMPY_INCL_DIR      the directory containing the NumPy arrayobject.h
                        header file (leave blank if NumPy is unavailable)
                        (on OS X, this is usually /System/Library/Frameworks/
                        Python.framework/Versions/$(PYTHON_VERSION)/Extras/
                        lib/python/numpy/core/include/numpy)
    EPYDOC              the path to the Epydoc executable
                        (leave blank if Epydoc is unavailable)
    PYTHON_WRAP_ALL_GRID_TYPES
                        if set to "no", expose only FloatGrid, BoolGrid
                        and Vec3SGrid in Python, otherwise expose (most of)
                        the standard grid types defined in openvdb.h

    DOXYGEN             the path to the Doxygen executable
                        (leave blank if Doxygen is unavailable)

    Note that if you plan to build the Houdini OpenVDB tools (distributed
    separately), you must build the OpenVDB library and the Houdini tools
    against compatible versions of the Boost, OpenEXR and TBB libraries.
    Fortunately, all three are included in the Houdini HDK, so by default
    several of the variables above reference the Houdini environment variables
    $HDSO, $HFS and $HT.  Source the houdini_setup script provided with
    your Houdini installation to set those environment variables.

    To build the OpenVDB Python module, you will need local installations of
    Python, Boost.Python, and optionally NumPy.  As of Houdini 12.5, the HDK
    includes versions 2.5 and 2.6 of Python as well as Boost.Python headers.
    Unfortunately, it includes neither the libboost_python library nor NumPy,
    so both Boost.Python and NumPy have to be built separately.
    Point the variables $(BOOST_PYTHON_LIB_DIR), $(BOOST_PYTHON_LIB) and
    $(NUMPY_INCL_DIR) to your local installations of those libraries.

2.  From the top-level openvdb/ directory, type "make" (or "make -s" for
    less verbose output) to locally build the library and commands.
    The Makefile supports parallel builds (e.g. "make -j 8").

    A default local build generates the following libraries and executables
    (but see the Makefile for additional targets and build options):

    openvdb/libopenvdb.so.2.1.0         the OpenVDB library
    openvdb/libopenvdb.so               symlink to libopenvdb.so.2.1.0
    openvdb/pyopenvdb.so                the OpenVDB Python module (if Python
                                        and Boost.Python are available)
    openvdb/vdb_print                   command-line tool that prints info
                                        about OpenVDB .vdb files
    openvdb/vdb_render                  command-line tool that ray-traces
                                        OpenVDB volumes
    openvdb/vdb_test                    unit test runner for libopenvdb
                                        (if CppUnit is available)

    From the openvdb/ directory, type "make test" to run the unit tests
    and verify that the library is working correctly.  (Alternatively, once
    the library has been installed (Step 5), run the unit test executable
    directly with "./vdb_test", or "./vdb_test -v" for more verbose output.)
    Type "make pytest" to run the Python module unit tests.

3.  From the openvdb/ directory, type "make doc" (or "make -s doc")
    to generate HTML library documentation, then open the file
    openvdb/doc/html/index.html in a browser.  Type "make pydoc"
    (or "make -s pydoc") to generate HTML Python module documentation,
    then open openvdb/doc/html/python/index.html in a browser.

4.  Optionally (if OpenGL and GLFW are available), from the top-level openvdb/
    directory, type "make vdb_view" (or "make -s vdb_view") to locally build
    the OpenVDB viewer tool.  Then type "./vdb_view" for usage information.

5.  From the openvdb/ directory, type "make install" (or "make -s install")
    to copy generated files into the directory tree rooted at $(INSTALL_DIR).
    This creates the following distribution:

    $(INSTALL_DIR)/
        bin/
            vdb_print
            vdb_render
            vdb_view
        include/
            openvdb/
                Exceptions.h
                ...
                openvdb.h
                tools/
                tree/
                ...
                version.h
        lib/
            libopenvdb.so
            libopenvdb.so.2.1
            libopenvdb.so.2.1.0

        python/
            include/
                python$(PYTHON_VERSION)/
                    pyopenvdb.h
            lib/
                python$(PYTHON_VERSION)/
                    pyopenvdb.so
                    pyopenvdb.so.2.1

        share/
            doc/
                openvdb/
                    html/
                        index.html
                        ...
                        python/
                            index.html
                            ...

EOF
