In this document we use <database> to refer to the name of the database
system you would like to use. Valid values for <database> are:

  'mysql'  - The MySQL database system
  'sqlite' - The SQLite database system
  'pgsql'  - The PostgreSQL database system
  
Prerequisites
=============

Required:
  - odb                     http://www.codesynthesis.com/products/odb/
  - libodb                  http://www.codesynthesis.com/products/odb/
  - libodb-<database>       http://www.codesynthesis.com/products/odb/

Optional:
  - libodb-boost            http://www.codesynthesis.com/products/odb/
  - Boost                   http://www.boost.org
  - libodb-qt               http://www.codesynthesis.com/products/odb/
  - Qt                      http://qt.nokia.com

Building on UNIX
================

The following build instructions are for the Linux/UNIX/Mac OS X
operating systems as well as for Cygwin and MinGW on Windows.

The standard autotools-based build system is used on these platforms.
After unpacking the source code archive, change to the odb-examples
package directory (referred to as odb-examples/ from now on) and run
the configure script, for example:

./configure --with-database <database>

To see the available configuration options run configure with --help:

./configure --help

The required --database option specifies the database system you would
like to use.

The configure script expects the directory where the ODB compiler
binary is installed to be in the executable search path (the PATH
environment variable). If that's not the case, you can use the ODB
configure variable to specify the path to the ODB compiler, for
example:

./configure ODB=/opt/odb/bin/odb

If the ODB compiler is not installed and you would like to run it from
its build directory instead, you can use the --with-odb configure option
to specify the build directory, for example:

./configure --with-odb=/tmp/odb

The configure script also expects the libodb and libodb-<database>
headers and libraries to be installed in a directory where the C++
compiler and linker will search for them by default (normally /usr
and /usr/local). If these libraries are installed in other directories,
you can use the CPPFLAGS and LDFLAGS configure variables to specify
their locations, for example:

./configure CPPFLAGS=-I/opt/libodb/include LDFLAGS=-L/opt/libodb/lib

If these libraries are not installed and you would like to use their
build directories instead, you can use the --with-libodb and
--with-libodb-<database> configure options to specify their locations,
for example:

./configure --with-libodb=/tmp/libodb

If you would also like to build the boost example, then the configure
script should be able to find headers and libraries for libodb-boost
and Boost. Similarly, if you would like to build the qt example, then
the configure script should be able to find headers and libraries for
libodb-qt and Qt. The same mechanisms as described above can be used
to specify locations of these libraries if they cannot be discovered
automatically.

For each <database> value the configure script has a set of options in
the form --with-<database>-* that allow you to specify various database
system parameters, such as the login name, password, and database name,
that should be used when running the examples. Run configure with
--help to see the available options for your database.

As another example, the following configure command uses the specified
C++ compiler and compiles with optimization and without debug information:

./configure CXX=g++-4.5 CXXFLAGS=-O3

Once configuration is complete, run make to build the examples:

make

Once the build is completed successfully, you can run each example
manually from the command line. See the README file accompanying each
example for more information on how to do this. Alternatively, you can
run all the examples using the check target:

make check


Building on Windows
===================

The following build instructions are for Windows using Microsoft Visual
Studio. If you would like to build odb-examples with GCC either using
Cygwin or MinGW, refer to the "Building on UNIX" section above.

The standard Visual Studio project and solution files are used on this
platform. The provided project files expect the directory where the ODB
compiler binary is installed to be in the executable search path (the
PATH environment variable). They also expect the libodb and libodb-<database>
header and import library directories to be in the VC++ Directories Include
and Library search lists. See the INSTALL files in the ODB library packages
for more information on how to setup their VC++ Directories.

If you would also like to build the boost example, then the header and
import library directories for libodb-boost and Boost must be in the VC++
Directories Include and Library search lists. Similarly, if you would like
to build the qt example, then the header and import library directories
for libodb-qt and Qt must be in the VC++ Directories Include and Library
search lists. See the INSTALL files in the ODB library packages for more
information on how to setup their VC++ Directories. For Boost and Qt,
refer to their documentation.

To build the examples, unpack the source code archive and open the
examples-<database>-vc<N>.sln file located in the odb-examples package
directory (referred to as odb-examples\ from now on). Here <N> is the
version of Visual Studio that you are using. Once the solution is open,
select the desired build configuration (Debug or Release) and platform
(Win32 or x64) and build the solution.

If you would like to build the boost example (requires Boost and
libodb-boost), also open and build the solution in the boost/
subdirectory.

If you would like to build the qt example (requires Qt and libodb-qt),
also open and build the solution in the qt/ subdirectory.

Once the build is completed successfully, you can run each example
manually from the command line. See the README file accompanying each
example for more information on how to do this. Alternatively, you can
run all the examples using the test.bat batch file located in the
odb-examples\ directory.

Before you can run test.bat, you may need to adjust the database system
parameters, such as the login name, password, and database name, that
should be used when running the examples. To do this, edit the
<database>.options and <database>-driver.bat files located in the
odb-examples\ directory. Once this is done, you can run the examples by
executing the following command from the command prompt:

test.bat <database>