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.

It has been developped and tested on most mainstream linux
distributions as well as on FreeBSD 6.2 and MacOS X 10.3
Check the bug tracker for porting issues.

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 try to have as less dependencies as possible. You need:
* A good C++98 library
* 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 controller pingers and carob
object locking (thread safety)
* 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
\-- make-includes => compile-time options for ports and to tune the build

Compiling
---------
We develop with GCC version 3.3-4.0 but other compilers should work.

To build carob on linux, just type:
> make
And optionally:
> make test && cd test && ./carobTestLauncher

For other platforms type something like:
> make OS=freebsd
Check make-includes/README for details

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
