The core part of the library and the backend interface definition are
placed in the core
directory of the library distribution.
The soci-backend.h
file is an internal abstract
interface to the actual backends, which are needed to perform
operations on the given database server. Normally, the C++ client
program needs to interface with the soci.h
header and the
header(s) relevant to the given backend(s) (for example, soci-oracle.h
).
It is possible for the same program to use many backends at the same
time.
The gray boxes above indicate that the SOCI library is extensible and that there are two aspects of this extensibility: more backends can be added, and more interfaces (possibly for other languages) can be defined to reuse the already existing backends.
Everything in SOCI is
declared in the namespace SOCI
.
All code examples presented in this documentation assume that your code
begins with something
like:
#include "soci.h" // other includes using namespace SOCI; // ...
Note:
In simple programs, #include
for the relevant
backend is needed only in the file where the Session
object is created, because it is where the name of the backend factory
is referenced. The example program on the previous
page shows the appropriate #include
directive for the
Oracle backend.
Download the SOCI distribution file: soci-X.Y.Z.tar.gz|tar.bz2|zip, where X.Y.Z is the version number. Unpack this file.
Configure:
$ ./configure
You may want to pass custom options to ./configure
script.
Backends can be enabled using options named as --enable-backend-<name>
and
disabled using --disable-backend-<name>
.
For example, to compile with support for MySQL that is already installed in some standard location, do this:
$ ./configure --enable-backend-mysql=yes
There are also --with-<package>
options which can be used to tell the script where the required headers and libraries can be found.
For example, to compile the library with the Oracle backend that is itself installed on a separate filesystem the following might be needed (example broken into three lines for clarity):
$ ./configure --enable-backend-oracle=yes \ --with-oracle-include=/u01/oracle/product/10.1.0/rdbms/public \ --with-oracle-lib=/u01/oracle/product/10.1.0/lib
Run ./configure --help
to learn what configuration options are available.
Build (after successful configuration):
$ make
Installation:
$ make install
After the last step, SOCI components will be placed under default installation prefix /usr/local
or custom location, if specified using --prefix
option.
The classic set of Makefiles for Unix/Linux systems is provided just in case if the autotools method fails to recognize the local system configuration. In this sense, the Makefiles are supposed to only provide a minimal starting point for custom experimentation and are not intended to be a complete build/installation solution.
On the other hand, they are complete in the sense that they can compile the library with all test programs and for some users this level of support will be just fine.
The core
directory of the library distribution contains
the Makefile.basic
that can be used to compile the core part of
the library. Run make -f Makefile.basic
or make -f Makefile.basic shared
to get
the static and shared versions. Similarly, the backends/name
directory contains the
backend part for each supported backend with the appropriate Makefile.basic
and the backends/name/test
directory contains the test program for the given backend.
For example, the simplest way to compile the static version of the library and the test program for PostgreSQL is:
$ cd src/core $ make -f Makefile.basic $ cd ../backends/postgresql $ make -f Makefile.basic $ cd test $ make -f Makefile.basic
Note:
For each backend and its test program, the Makefile.basic
s
contain the variables that can have values specific to the given
environment. These variables are placed at the beginning of the Makefile.basic
s.
Please review their values in case of any compilation problems.
The Makefiles for test programs can be a good starting point to find out correct compiler and linker options.
The SOCI distribution package includes solution files for Visual C++ 2005 - they can be found inside the build\msvc80
directory:
dll\soci_dll.sln
- to build SOCI as DLL librarieslib\soci_lib.sln
- to build SOCI as static librariesBoth solutions inherit common
settings and macros from Visual Studio Property Sheet in file build\msvc80\soci.vsprops
. The main concept behind the soci.vsprops
is to provide common place where paths and
names of SOCI libraries and external dependencies are defined.
NOTE: Currently, MySQL backend compilation is not supported due to some problems with linking to MySQL client library. If you know how to use it from Visual C++ 2005 and without rebuilding MySQL libraries on your own, please let us know.
Configure:
soci_dll.sln
or soci_lib.sln
solution in Visual C++ IDEsoci_lib
sheet and double-click on soci
to open its propertiesValue
box):
FIREBIRD_INCLUDE_DIR
- path to FireBird client library headersFIREBIRD_LIB_DIR
- path to FireBird client libraryFIREBIRD_LIB
- FireBird library, can be left unchangedMYSQL_INCLUDE_DIR
- NOT USEDMYSQL_LIB_DIR
- NOT USEDMYSQL_LIB
- NOT USEDODBC_INCLUDE_DIR
- ODBC include path, can be left unchangedODBC_LIB_DIR
- ODBC libraries path, can be left unchangedODBC_LIB
- ODBC library file, can be left unchangedORACLE_INCLUDE_DIR
- path to OCI headersORACLE_LIB_DIR
- path to OCI librariesORACLE_LIB
- list of OCI librariesPOSTGRESQL_INCLUDE_DIR
- path to libpq
headersPOSTGRESQL_LIB_DIR
- path to libpq
libraryPOSTGRESQL_LIB
- libpq
library, can be left unchangedSQLITE3_INCLUDE_DIR
- path to SQLite 3 headersSQLITE3_LIB_DIR
- path to SQLite 3 librarySQLITE3_LIB
- SQLite 3 library, can be left unchangedAfter the configuration is ready, you can build SOCI libraries from the Visual C++ 2005 IDE.
Build:
Build -> Build Solution
If no errors occured, SOCI libraries and test programs can be found in subdirectory debug
or release
, depending on selected build configuration.
Running tests:
You need to edit maketest.mak
file and change relevant connection strings in the CONFIGURATION
block, according to your environment.
Run all tests:
nmake /f maketest.mak
Run test for selected backend:
nmake /f maketest.mak <backendname>
It is also possible to run test programs directly from command prompt, without using maketest.mak
controller.
Previous (Contents) | Next (Errors) |
Copyright © 2004-2006 Maciej Sobczak, Stephen Hutton