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
  'oracle' - The Oracle database system
  'mssql'  - The Microsoft SQL Server 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-tests
package directory (referred to as odb-tests/ 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 profile tests, 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
profile tests, 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 tests. 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

If you would like to build the tests in the C++11 mode, then you will need
to pass the necessary options to turn the C++ compiler into this mode. For
example:

./configure CXXFLAGS=-std=c++0x

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

make

Once the build is completed successfully you can run the tests 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-tests 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 profile tests, 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 profile tests, 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.

There are two ways to build the tests with Visual Studio. After unpacking
the source code archive, you can manually open solution files located in
the libcommon\, common\, <database>\, boost\common\, boost\<database>\,
qt\common\, and qt\<database>\ directories in the odb-tests package
directory (referred to as odb-tests\ from now on). In the libcommon\,
common\, boost\common\, and qt\common\ directories the solutions are
named in the form name-<database>-vc<N>.sln. And in the <database>\,
boost\<database>\, and qt\<database>\ directories they are named in
the form <database>-vc<N>.sln. Here <N> is the version of Visual Studio
that you are using. Once each solution is open, select the desired build
configuration (Debug or Release) and platform (Win32 or x64) and build the
solution. Note that with Visual Studio 10 (2010) and later the tests are
built in the C++11 mode.

Alternatively, you can use the build.bat batch files located in the
odb-tests\, odb-tests\boost\, and odb-tests\qt\ directories to build all
the solutions, for all the configurations and for all the platforms
automatically. The build.bat file has the following command line interface:

build.bat <database> <N> <conf> <plat> [/Build|/Clean|/Rebuild]

Where <N> is the version of Visual Studio that you are using, <conf> is the
desired configuration (e.g., Debug or Release), and <plat> is the desired
platform (e.g., Win32 or x64). For <conf> and <plat> arguments you can
specify several configurations or platforms. You can also use the 'all'
value to build all configurations and/or all platforms. If no action is
specified, the default is /Build.

Once the build is completed successfully, you can run all the tests using
the test.bat batch file located in the odb-tests\ 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 tests. To do this, edit the
<database>.options and <database>-driver.bat files located in the
odb-tests\ directory. Once this is done, you can run the tests by
executing the following command from the command prompt:

test.bat <database>


Test Suite Configuration
========================

The test suite supports additional configuration via the following
preprocessor macros:

HOST_WIN32            Specifies that the tests will run on Windows. This
                      macro is only needed when cross-compiling for Windows
                      using, for example, a cross-compiler to MinGW.

MSSQL_SERVER_VERSION  Specifies the SQL Server version that will be used to
                      run the tests. The version is specified as XXYY where
                      XX is the major and YY is the minor SQL Server versions,
                      for example, 900 (SQL Server 2005/9.0), 1000 (2008/10.0),
                      1050 (2008R2/10.5), 1100 (2012/11.0). If this macro is
                      not defined, then the test suite assumes SQL Server 2008.

To define any of these macros when building on UNIX operating systems you
can use the CPPFLAGS configure variable, for example:

./configure CPPFLAGS=-DMSSQL_SERVER_VERSION=900

When building on Windows with Visual Studio the extra macros have to be
specified in two places: in the default.options ODB configuration file
(located in the odb-X.Y.Z-i686-windows\etc\odb\ directory) as well as
in the CL environment variable. For example, to specify the SQL Server
version add the following line to the default.options file:

-DMSSQL_SERVER_VERSION=900

As well as set the CL environment variable before running the build.bat
batch file:

SET CL=-DMSSQL_SERVER_VERSION=900

If you are using the Visual Studio IDE to build the tests, then you will
need to start the IDE from a command prompt after setting the CL variable,
for example:

SET CL=-DMSSQL_SERVER_VERSION=900
C:\Program Files (x86)\Microsoft Visual Studio <N>\Common7\IDE\devenv.com
