What is Carob?
--------------
Carob's purpose is to offer Sequoia access to ODBC, C and C++ client applications.
The base library, libCarob, is a C++ port of the JDBC driver code. It offers to
developpers the same access as in Java. Connections, Statements, Requests,
ResultSets and all necessary C++ classes can be used transparently and directly
in any C++ enabled application.

Carob and Friends
-----------------
"Carob" is the historical name grouping the C++ API, the ODBC driver and the
native mySQL - C API projects.
While those 3 projects were growing, it has been decided to give 3 different
names:
- "ODBSequoia" for the ODBC driver
   http://carob.continuent.org/doc/odbsequoia/
- "libMySequoia" for the native mySQL API
   http://carob.continuent.org/LibMySequoia
- "carob" or "libCarob" for the C++
   http://carob.continuent.org/HomePage

Dependencies
------------
We tried to have as less dependencies as possible. And it is even possible to
tweak carob so you will have NO dependency at all (except libstdc++!)...
But for the general case, you will need:
* The GNU MP Bignum Library (GMP) available at http://www.swox.com/gmp/ AND its
C++ interface for BigDecimals support
* a POSIX thread (pthread) library for thread safety (there is no real thread in
carob, just critical sections)
* optionally Apache's logging library for C++ (log4cxx) available at
http://logging.apache.org/log4cxx/ for better logging (it is still possible to
use internal cerr<<-style logging)
* to run tests, you will need CppUnit available at
http://cppunit.sourceforge.net/cppunit-wiki/FrontPage

Directory Structure
-------------------
.
|-- contrib     => Basic examples and contributions to carob
|   |-- CPP
|   `-- PHP
|-- debian      => Everything needed to build a debian package
|-- doc         => Notes for users and developpers
|-- doxygen     => API documentation
|-- include     => Headers
|-- src         => Source files
`-- test        => Test files

Compiling
---------
Gnu C++ compiler is required. We develop with version 4.0 but it should work with
3.3.5 or 3.4 with few effort
To build carob, just type:
> make
And optionally:
> make test && cd test && ./carobTestLauncher

Quick start
-----------
"a good example is better than a long speech"
To start developping with carob, please look at the contrib/CPP/read_example.cpp
file.
For deeper documentation, just "make doc" (requires doxygen, available at
http://www.stack.nl/~dimitri/doxygen/index.html) and open
doxygen/html/index.html.
If you still have questions please post to carob@lists.forge.continuent.org,
we will be happy to give you a hand !

Contributing
------------
Please do not hesitate to send feedback, bugs, questions, whishes, smilleys... to 
carob@lists.forge.continuent.org
