The picture above presents the structure of the library, together with its clients and servers. The boxes filled with cyan represent components that are part of the library distribution.
The SOCI library is extensible in the following ways:
The core part of the library and the backend interface definition are
placed in the
core directory of the library distribution.
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,
although with dynamic backend loading this can be avoided.
It is possible for the same program to use many backends at the same
Everything in SOCI is
declared in the namespace
All code examples presented in this documentation assume that your code
begins with something
#include "soci.h" // other includes if necessary using namespace soci; // ...
In simple programs,
#include for the relevant
backend is needed only in the file where the
object is created with explicit name of the backend factory.
The example program on the previous
page shows the appropriate
#include directive for the
Oracle backend. It is also possible to name backends at run-time
as part of the connection string, in which case no backend-specific
#include directive is necessary.
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 $ make $ make install
configure script verifies that the Tcl interpreter is installed on the system,
as a dependency for all the build and install scripts, and allows to provide various
settings if the local environment differs from standard installations.
configure script is run without parameters, the remaining
part of the process will use
/usr/local/include/soci as a default destination for SOCI header files
/usr/local/lib as a default destination for library files and the build script
will try to find all supported database installations in the "usual" set of directories.
To build the Oracle backend, the
ORACLE_HOME environment variable has to be set
properly as well.
The configuration parameters allow to change the target directory for installing SOCI and to name specific directories for chosen database header and library files if they are not installed on any of the "usual" paths. To learn about all configuration options run:
$ ./configure --help
For example, if the MySQL header and library files were installed locally in
/opt/mysql/lib, then the following
command will configure the build step accordingly:
$ ./configure --mysql-include=/opt/mysql/include --mysql-lib=/opt/mysql/lib
After configuring the build and installation steps you can build the SOCI library by simply running
The core library and backends will be placed in
Note that in addition to the options describe above, the
CXXFLAGS environment variable is recognized and if defined, its value is taken instead of default set of compilation flags.
The library can be installed by:
$ make install
The installation script recognizes also the
DESTDIR environment variable, which value (if set) is prepended to the default or configured installation paths.
Note: depending on the target directory it might be necessary to acquire root permissions before installing the library.
The "undo" script that removes all files and directories that were created during installation is created automatically and can be run by:
$ make uninstall
In addition to the library itself, the test programs for each backend can be compiled as well:
$ make tests
The compiled test programs are located in
build/unix/tests and require, as their single parameter,
a connection string understood by the relevant backend. Run them without arguments to see the usage description.
All build artefacts (not counting the installed files) can be removed with the following:
$ make clean
The classic set of Makefiles for Unix/Linux systems is provided for those users who need complete control over the whole process
and who can benefit from the basic scaffolding that they can extend on their own.
In this sense, the basic Makefiles are supposed to provide a minimal starting point for custom experimentation and are not intended to be a complete build/installation solution.
At the same time, 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.
core directory of the library distribution contains
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, respectively.
backends/name directory contains the
backend part for each supported backend with the appropriate
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
For each backend and its test program, the
contain the variables that can have values specific to the given
environment - they usually name the include and library paths.
These variables are placed at the beginning of the
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
dll\soci_dll.sln- to build SOCI as DLL libraries
lib\soci_lib.sln- to build SOCI as static libraries
Both 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.
soci_lib.slnsolution in Visual C++ IDE
soci_libsheet and double-click on
socito open its properties
FIREBIRD_INCLUDE_DIR- path to FireBird client library headers
FIREBIRD_LIB_DIR- path to FireBird client library
FIREBIRD_LIB- FireBird library, can be left unchanged
MYSQL_INCLUDE_DIR- NOT USED
MYSQL_LIB_DIR- NOT USED
MYSQL_LIB- NOT USED
ODBC_INCLUDE_DIR- ODBC include path, can be left unchanged
ODBC_LIB_DIR- ODBC libraries path, can be left unchanged
ODBC_LIB- ODBC library file, can be left unchanged
ORACLE_INCLUDE_DIR- path to OCI headers
ORACLE_LIB_DIR- path to OCI libraries
ORACLE_LIB- list of OCI libraries
POSTGRESQL_INCLUDE_DIR- path to
POSTGRESQL_LIB_DIR- path to
libpqlibrary, can be left unchanged
SQLITE3_INCLUDE_DIR- path to SQLite 3 headers
SQLITE3_LIB_DIR- path to SQLite 3 library
SQLITE3_LIB- SQLite 3 library, can be left unchanged
After the configuration is ready, you can build SOCI libraries from the Visual C++ 2005 IDE.
Build -> Build Solution
If no errors occured, SOCI libraries and test programs can be found in subdirectory
release, depending on selected build configuration.
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
|Previous (Contents)||Next (Errors)|
Copyright © 2004-2009 Maciej Sobczak, Stephen Hutton