SOCI - The C++ Database Access Library

Library structure, files and compilation

The SOCI library structure

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:

• More backends can be added to target various database servers.
• More interfaces can be defined on top of common backend interface.
• Other languages can use the simple interface, which was designed specifically for the "C" calling convention to ensure easy binding.

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), although with dynamic backend loading this can be avoided. It is possible for the same program to use many backends at the same time.

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 if necessary

using namespace soci;

// ...

Compilation

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.

With build script on Unix/Linux

Short version:

$ ./configure
$ make
$ make install

Long version:

The 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.

When the 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 and /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/include and /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 make. The core library and backends will be placed in build/unix/include and build/unix/lib directories.

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

With classic Makefiles on Unix/Linux

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.

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, respectively. 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

The Makefiles for test programs can be a good starting point to find out correct compiler and linker options.

With Microsoft Visual C++ 2005 on Windows

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 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.

Configure:

1. Open soci_dll.sln or soci_lib.sln solution in Visual C++ IDE
2. Open View -> Property Manager
3. Expand one of the projects (it doesn't matter which one), expand selected configuration ie. Debug, go through soci_lib sheet and double-click on soci to open its properties
4. According to your environment, customize paths and list of libraries by editing the following macros (double-click on macro update Value box):
   • 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 libpq headers
   • POSTGRESQL_LIB_DIR - path to libpq library
   • POSTGRESQL_LIB - libpq library, 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
5. Leave the remaining macros untouched

After 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-2009 Maciej Sobczak, Stephen Hutton