MATIO - MATLAB MAT file I/O library

Table of Contents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.0 Introduction
  1.1 Contact
  1.2 Acknowledgements
  1.3 Contributing
  1.4 Questions and Reporting Bugs
2.0 Dependencies
  2.1 zlib
  2.1 HDF-5
3.0 Platforms
4.0 Building with autoconf
  4.1 Quick Build Guide
  4.2 Configure Options
  4.3 Testsuite
5.0 Visual Studio
6.0 Building with cmake
  6.1 Quick Build Guide
  6.2 Configure Options
7.0 License

1.0 Introduction
    matio is an open-source library for reading/writing MATLAB MAT files.
    This library is designed for use by programs/libraries that do not have
    access or do not want to rely on MATLAB's shared library.
    Section 2 documents the dependencies and section 3 the platforms on which
    matio has been tested.
    Build can be made using either autoconf (recommended) or cmake (experimental),
    see sections 4 and 5 respectively.

    1.1 Contact
        You can contact me (Christopher Hulbert) through email at
        chulbe2lsu@users.sourceforge.net.

    1.2 Acknowledgements
        The following people/organizations have helped in the development of
        matio through patches, bug reports, and/or testing:
          * Jacco van Beek
          * SGI in support of Interactive Supercomputing, Inc.
          * Scilab (http://www.scilab.org/)
          * Steven Leibman <sleibman@alum.mit.edu>
          * OpenMEEG (http://www-sop.inria.fr/athena/software/OpenMEEG/)

    1.3 Contributing
        Part of my reason for releasing this software is I have many other
        projects to work on and have many features I would still like to
        implement. If you make changes, I would appreciate your contributions
        and more than likely will include them in future releases. If you are
        interested in collaborations, contact me via email (see Section 1.1).

    1.4 Questions and Reporting Bugs
        Questions can be askes using the forums on the sourceforge site hosting
        matio (http://sourceforge.net/projects/matio/forums).

        Bugs, enhancements, etc. should be submitted using one of the trackers
        on the sourceforge page
        (http://sourceforge.net/tracker/?group_id=176643).

2.0 Matio dependencies

    MATIO has two optional dependencies. These are not required for the
    software to work, but without them some files may be unreadable. Zlib
    is required to read/write level 5 MAT files that use compression. HDF5
    is required to work with newer MAT files that use the HDF5-format
    files

    2.1.1 zlib
          To support compressed MAT files, zlib 1.2.3 or greater is
          required. The zlib software can be downloaded from
          http://zlib.net.

    2.1.2 HDF5
          Support for MAT file version 7.3 requires the HDF5 library. This
          library can be downloaded from The HDF Group website
          (http://www.hdfgroup.org/). MATIO requires HDF5 version 1.8.x,
          and must be built with default API version 1.8 (i.e.
          '--with-default-api-version=v18').

        For windows, the pre-compiled binaries can be used which also
        include a DLL of zlib to satisfy the zlib dependency.

3.0 Platforms
    The library has been tested/used on Linux, Windows, OS X, and AIX
    including both little-endian and big-endian architecture.

4.0 Building with autoconf

    This is currently the recommended way to build matio as it is the one that
    got tested the most.

    This section describes how to build matio with autoconf. Section 4.1
    describes how to build/test matio, and Section 4.2 the options that
    can be used to modify the build.

    4.1 Quick Build Guide
        The primary method for building the software is using 'configure'
        followed by 'make'. After building, the testsuite can be executed to
        test the software using 'make check'. The software can be installed
        using 'make install'. For example,
            $ tar zxf matio-X.Y.Z.tar.gz
            $ cd matio-X.Y.Z
            $ ./configure
            $ make
            $ make check
            $ make install

        If any of the tests in the testsuite fail, you should report the failure
        using the tracker (see Section 1.4). You should attach the generated
        testsuite.log file to the bug report.

    4.2 Configure Options
        The configure script used to build the software takes a number of
        options. This section describes the key options.

            * --enable-mat73=yes
                This flag en/disables the support for version 7.3 MAT files.
                The option only makes sense if built with HDF5 as support
                for version 7.3 files will be disabled if HDF5 is not
                available.
            * --enable-extended-sparse=yes
                Enable extended sparse matrix data types not supported in
                MATLAB. MATLAB only supports double-precision sparse data.
                With this flag, matio will read sparse data with other
                types (i.e. single-precision and integer types).
            * --with-matlab=DIR
                This option specifies the directory (DIR) with the 'matlab'
                program. With this option, the testsuite will check that the
                MAT files written by matio can be read into MATLAB. Without
                this, the test will only check that matio can read the file
                written and if successful the test will be skipped. If matio
                can not read the file, the test will fail.
            * --with-zlib=DIR
                This option specifies the prefix where zlib is installed
                (see Section 2.1.1 for information about zlib).
            * --with-hdf5=DIR
                This option specifies the prefix where the HDF5 software is
                installed (see Section 2.1.2 for information about HDF5).
            * --with-default-file-ver=version
                This option sets the default MAT file version (4,5,7.3) that
                will be used when writing. The default file version is used
                by the Mat_Create macro and the Mat_CreateVer function when
                MAT_FT_DEFAULT is used for the version argument.
            * --with-libdir-suffix=suffix
                This option specifies a suffix to apply to library
                directories when installing and looking for dependent
                libraries (i.e. HDF5 and zlib). For example, some multi-arch
                Linux distributions install 64-bit libraries into lib64 and
                32-bit libraries into lib.

    4.3 Testsuite
        A testsuite is available when building with the GNU autotools. To
        run the testsuite, First configure and build matio. After building
        run 'make check' to run the testsuite. If matio was built without
        zlib, the compressed variable tests will be skipped. If built
        without HDF5, the tests for version 7.3 MAT files will be skipped.
        If the path to the MATLAB application was not specified
        (--with-matlab), the write tests will fail if matio cannot read the
        file and skip if matio can read the file. The write tests will pass
        if MATLAB is available and can also read the file.

        To report matio testsuite failures, compress the testsuite.log file
        in the test sub-directory of the build directory. Upload the
        compressed log file along with a bug report (see Section 1.4 for
        information on reporting bugs).

5.0 Building with Visual Studio

    A visual studio solution is provided as visual_studio/matio.sln.
    The solution is set up to build a DLL of the matio library
    (libmatio.dll) and matdump tool in release mode and assumes HDF5 is
    available in the directory specified by the HDF5_DIR environment
    variable. The build was tested with the HDF5 visual studio pre-built
    Windows binaries including zlib.

6.0 Building with cmake

    This section describes how to build matio using the cmake build system.
    This is rather new and should be considered experimental, but has the 
    nice property that the same instructions can be used on all supported
    platforms. Section 5.1 describes how to build/test matio, and Section 5.2
    the options that can be used to modify the build. This build type can be
    used on all platforms.

    6.1 Quick Build Guide
        The primary method for building the software is using 'ccmake'
        followed by 'make'. After building, the testsuite can be executed to
        test the software using 'make check'. The software can be installed
        using 'make install'. For example,
            $ tar zxf matio-X.Y.Z.tar.gz
            $ mkdir matio-X.Y.Z-build
            $ cmake ../matio-X.Y.Z
            $ make
            $ make test
            $ make install

        If any of the tests in the testsuite fail, you should report the failure
        using the tracker (see Section 1.4). You should attach the generated
        testsuite.log file to the bug report.

    6.2 Configure Options
        cmake also allows you to change the way matio is built ny tweaking several
        options. Those options can be passed to the cmake command line with the
        syntax -D OPTION=VALUE, or you can use a graphic interface.

        To use the graphic interface, use the same instructions as in 5.1 but
        replacing the line "cmake ../matio-X.Y.Z" by "ccmake ../matio-X.Y.Z".
        This will give you a graphic interface where you can change several
        options. See the cmake manual for the interface documentation.
        The remaining of this section details the main options that can be
        tweaked.

7.0 License
    This software is provided under a Simplified BSD license. See the COPYING
    file for details on the license.