Installation

    Installation
    ============

    The process required to install JasPer is described below.

    Installation on Systems Running Unix
    ------------------------------------

    In what follows, let $SOURCE_DIR denote the top-level directory of the
    JasPer software source tree and let $INSTALL_DIR denote the target
    directory for installation.

    1) Select an empty directory to use for building the software.
    Let $BUILD_DIR denote this directory.

    2) Generate the makefiles used for building the software.  To do this,
    invoke the command:

        cmake -G "Unix Makefiles" -H$SOURCE_DIR -B$BUILD_DIR \
          -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR $OPTIONS

    where $OPTIONS corresponds to zero or more -D options as described below
    under the heading "Cmake Options".

    3) Change the working directory to the build directory.  To do this,
    use the command:

        cd $BUILD_DIR

    4) Build the code using the make utility.  To do this, invoke the command:

        make clean all

    5) Run the test suite to ensure that the software seems to be working
    correctly.  To do this, invoke the command:

        make test

    If more verbose output from the testing process is desired (e.g., to
    assist in diagnosing a problem), instead use the command:

        make test ARGS="-V"

    6) Install the software.  To do this, invoke the command:

        make install

    Additional Remarks:

    When building the JasPer software under Mac OSX, only the use of the
    native framework for OpenGL is officially supported.  If the Freeglut
    library is installed on your system, you will need to ensure that the
    native GLUT library (as opposed to the Freeglut library) is used by the
    build process.  This can be accomplished by adding an extra option to
    the cmake command line that resembles the following:

        -DGLUT_glut_LIBRARY=/System/Library/Frameworks/GLUT.framework

    Installation on Systems Running Microsoft Windows
    -------------------------------------------------

    In what follows, let %SOURCE_DIR% denote the top-level directory of the
    JasPer software source tree and let %INSTALL_DIR% denote the target
    directory for installation.

    1) Select an empty directory to use for building the software.
    Let %BUILD_DIR% denote this directory.

    2) Generate the project file needed to build the software with Microsoft
    Visual Studio.  To do this, invoke the command:

        cmake -G "Visual Studio 12 2013 Win64" -H%SOURCE_DIR% -B%BUILD_DIR% ^
          -DCMAKE_INSTALL_PREFIX=%INSTALL_DIR% %OPTIONS%

    where %OPTIONS% corresponds to zero or more -D options as described
    below under the heading "Cmake Options".  (Note the caret symbol "^"
    above denotes line continuation.)

    3) Build and install the software.  To do this, invoke the command:

        msbuild %build_dir%\INSTALL.vcxproj

    Cmake Options
    -------------

    The option OPTION can be set to the value VALUE with a command-line option
    of the form -DOPTION=VALUE
    The following options are supported:

    CMAKE_INSTALL_PREFIX
        Specify the installation directory.
        Value: A directory name.

    CMAKE_BUILD_TYPE
        Specify the build type (i.e., release or debug).
        Valid values: Debug or Release

    JAS_ENABLE_DOC
        Enable the building of the documentation (which requires LaTeX).
        Valid values: true and false

    JAS_ENABLE_LIBJPEG
        Enable the use of the JPEG library
        Valid values: true and false

    JAS_ENABLE_OPENGL
        Enable the use of the OpenGL and GLUT libraries.
        Valid values: true and false

    JAS_ENABLE_STRICT
        Enable pedantic errors for building the code.
        Valid values: true or false

    JAS_ENABLE_SHARED
        Enable the building of shared libraries.
        Valid values: true or false

    JAS_ENABLE_ASAN
        Enable the Address Sanitizer.
        Valid values: true or false

    JAS_ENABLE_USAN
        Enable the Undefined-Behavior Sanitizer.
        Valid values: true or false

    JAS_ENABLE_LSAN
        Enable the Leak Sanitizer.
        Valid values: true or false

    JAS_ENABLE_MSAN
        Enable the Memory Sanitizer.
        Valid values: true or false

    JAS_MEMORY_LIMIT
        DO NOT RELY ON THIS OPTION, AS IT IS LIKELY TO BE REMOVED IN THE FUTURE.
        Set the maximum amount of memory that can be allocated with jas_malloc
        and friends.
        Value: a value of unsigned integral type (e.g., 10000000 or SIZE_MAX).