libtabula

Installing libtabula
====

The installation procedure depends on the compiler you use to build
libtabula and on the OS you build it on.  There are platform-specific
instructions for all popular platforms:

* [Cygwin](README-Cygwin.md)
* [Linux](README-Linux.md)
* [Mac OS X](README-Mac-OS-X.md)
* [MinGW](README-MinGW.md)
* [Solaris](README-Solaris.md)
* [Visual C++](README-Visual-C%2b%2b.md)

If you're on some Unix variant (Linux, OS X, \*BSD, Solaris,
Cygwin...)  there are additional general instructions in [the Unix
README](README-Unix.md).

See [the main README file](README.md) for high-level instructions
that apply to all platforms libtabula works on.

Building libtabula on Unix
====

Platform Variations
----

This file only covers details common to all Unix variants supported by
libtabula  For platform-specific details, see the file appropriate to
your OS:

*   [Cygwin](README-Cygwin.md)
*   [Linux](README-Linux.md)
*   [Mac OS X](README-Mac-OS-X.md)
*   [Solaris](README-Solaris.md)

There are no special instructions for any other Unix flavors.


Building the Library and Example Programs
----

----

Each major platform we support has a dedicated `README-*.md` file for
it containing information specific to that platform.  Please read it:

*   [Cygwin](README-Cygwin.md)
*   [Linux](README-Linux.md)
*   [Mac OS X](README-Mac-OS-X.md)
*   [MinGW](README-MinGW.md)
*   [Solaris](README-Solaris.md)
*   [Unix (generic)](README-Unix.md)
*   [Visual C++](README-Visual-C%2b%2b.md)

For authorship information, see [the CREDITS file](CREDITS.md).

Building the Library
----

libtabula uses [CMake][4] to generate platform-specific build files
from a platform-independent set of build rules.  We have successfully
used it to build libtabula under these native build system types:

*   **Makefiles**: For Unixy platforms, including Linux, Mac OS X,
    Cygwin, and MinGW, in addition to the "real" Unices.
    
    See [the Unix README](README-Unix.md) for general instructions.

    There are supplementary platform-specific `README` files for most
    popular Unixy platforms:

    -   [Cygwin](README-Cygwin.md)
    -   [Linux](README-Linux.md)
    -   [Mac OS X](README-Mac-OS-X.md)
    -   [MinGW](README-MinGW.md)
    -   [Solaris](README-Solaris.md)

    TODO: Write README-Free/Net/OpenBSD.md, if only to mention the
    location for C API files.

    If your platform of choice doesn't have a `README` dedicated

    
    See [the Visual C++ README](README-Visual-C%2b%2b.md) for more
    details.

*   **Xcode**: CMake will generate an Xcode project file instead of
    Makefiles on OS X if you ask nicely.

    See [the Mac OS X README](README-Mac-OS-X.md) for more the proper
    incantation.

CMake can generate many other kinds of IDE project files, but we have
either not tried it, or have not succeeded with it.  Success reports
and patches are welcome on the mailing list.[3]

    <computeroutput>--with-mysql-lib</computeroutput> flags. See
    <filename>README-Unix.md</filename> for details.</para>

    <para>If you need to modify the build system files, per-platform
    instructions are in
    <filename>README-Visual-Studio.md</filename>,
    <filename>README-MinGW.md</filename>, and
    <filename>README-Mac-OS-X.md</filename>.</para>
  </sect2>


  <sect2 id="max-fields">
    <title>The Maximum Number of Fields Allowed</title>

    <para>libtabula offers two ways to automatically build

      OS X.</para>

      <para>One thing that may trip you up on OS X is that it uses an
      uncommon dynamic linkage system. The easiest way to cope with
      this is to link your executables with the compiler, rather than
      call <filename>ld</filename> directly.</para>

      <para>Another tricky bit on OS X is the concept of Universal
      binaries. See <filename>README-Mac-OS-X.md</filename> for
      details on building a Universal version of the libtabula library,
      if you need one. By default, you only get a version tuned for
      the system type you build it on.</para>
    </sect3>

    <sect3 id="inc-osx-xcode">
      <title>Xcode</title>