Installation

Requirements

Below is an overall list of SOCI core:

and backend-specific dependencies:

Downloads

Download package with latest release of the SOCI source code: soci-X.Y.Z, where X.Y.Z is the version number. Unpack the archive.

You can always clone SOCI from the Git repository:

git clone git://github.com/SOCI/soci.git

Building with CMake

SOCI is configured to build using CMake system in version 2.8+.

The build configuration allows to control various aspects of compilation and installation by setting common CMake variables that change behaviour, describe system or control build (see CMake help) as well as SOCI-specific variables described below. All these variables are available regardless of platform or compilation toolset used.

Running CMake from the command line allows to set variables in the CMake cache with the following syntax: -DVARIABLE:TYPE=VALUE. If you are new to CMake, you may find the tutorial Running CMake helpful.

Running CMake on Unix

Steps outline using GNU Make Makefile-s:

mkdir build
cd build
cmake -G "Unix Makefiles" -DWITH_BOOST=OFF -DWITH_ORACLE=OFF (...) /path/to/soci-X.Y.Z
make
make install

Running CMake on Windows

Steps outline using Visual Studio 2010 and MSBuild:

mkdir build
cd build
cmake -G "Visual Studio 10" -DWITH_BOOST=OFF -DWITH_ORACLE=OFF (...) C:\path\to\soci-X.Y.Z
msbuild.exe SOCI.sln

CMake configuration

By default, CMake will try to determine availability of all dependencies automatically. If you are lucky, you will not need to specify any of the CMake variables explained below. However, if CMake reports some of the core or backend-specific dependencies as missing, you will need specify relevant variables to tell CMake where to look for the required components.

CMake configures SOCI build performing sequence of steps. Each subsequent step is dependant on result of previous steps corresponding with particular feature. First, CMake checks system platform and compilation toolset. Next, CMake tries to find all external dependencies. Then, depending on the results of the dependency check, CMake determines SOCI backends which are possible to build. The SOCI-specific variables described below provide users with basic control of this behaviour.

The following sections provide summary of variables accepted by CMake scripts configuring SOCI build. The lists consist of common variables for SOCI core and all backends as well as variables specific to SOCI backends and their direct dependencies.

List of a few essential CMake variables:

List of variables to control common SOCI features and dependencies:

Some other build options:

Empty (sample backend)

IBM DB2

Firebird

MySQL

ODBC

Oracle

PostgreSQL

SQLite 3

Building with Makefiles on Unix

NOTE: These (classic) Makefiles have not been maintained for long time. The officially maintained build configuration is CMake. If you still want to use these Makefiles, you've been warned that you may need to patch them.

The classic set of Makefiles for Unix/Linux systems is provided for those users who need complete control over the whole processand 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/<i>name</i> directory contains the backend part for each supported backend with the appropriate Makefile.basic and the backends/<i>name</i>/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

For each backend and its test program, the Makefile.basics 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 Makefile.basics. 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.

Building with Conan

SOCI is available as a Conan package since February 2021 for the version 4.0.1 for the following backends: sqlite3, odbc, mysql, and postgresql.

This section lists the steps required to use SOCI in a CMake project with Conan:

Install Conan

Install Conan if it is not installed yet:

pip3 install conan

Create conanfile.txt

Create a conanfile.txt in the same directory of the CMakeLists.txt, with a reference to a recipe (which is a string with the library name and the version to use), the build options, and the CMake generator:

# conanfile.txt
[requires]
soci/4.0.1

[options]
soci:shared       = True
soci:with_sqlite3 = True

[generators]
cmake

The option soci:with_sqlite3 = True indicates that the sqlite3 backend will be downloaded and used.

Update CMakeLists.txt

Add the following Conan-specific lines to the CMakeLists.txt of your project:

include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
conan_basic_setup(TARGETS)
conan_target_link_libraries(${PROJECT_NAME} ${CONAN_LIBS})

The command conan_target_link_libraries replaces target_link_libraries.

Run Conan

Run conan install to install SOCI, and then build your project as usual:

mkdir build
cd build
conan install .. --build=soci
cmake ..
cmake . --build

Running tests

The process of running regression tests highly depends on user's environment and build configuration, so it may be quite involving process. The CMake configuration provides variables to allow users willing to run the tests to configure build and specify database connection parameters (see the lists above for variable names).

In order to run regression tests, configure and build desired SOCI backends and prepare working database instances for them.

While configuring build with CMake, specify SOCI_TESTS=ON to enable building regression tests. Also, specify SOCI_{backend name}_TEST_CONNSTR variables to tell the tests runner how to connect with your test databases.

Dedicated make test target can be used to execute regression tests on build completion:

mkdir build
cd build
cmake -G "Unix Makefiles" \
        -DWITH_BOOST=OFF \
        -DSOCI_TESTS=ON \
        -DSOCI_EMPTY_TEST_CONNSTR="dummy connection" \
        -DSOCI_SQLITE3_TEST_CONNSTR="test.db" \
        (...)
        ../soci-X.Y.Z
make
make test
make install

In the example above, regression tests for the sample Empty backend and SQLite 3 backend are configured for execution by make test target.

Using library

CMake build produces set of shared and static libraries for SOCI core and backends separately. On Unix, for example, build/lib directory will consist of the static libraries named like libsoci_core.a, libsoci_sqlite3.a and shared libraries with names like libsoci_core.so.4.0.0, libsoci_sqlite3.so.4.0.0, and so on.

If your project also uses CMake, you can simply use find_package(Soci) to check for SOCI availability and target_link_libraries() to link with the SOCI libraries available under the names Soci::core and Soci::<backend> (or Soci::<backend>_static if you prefer linking statically) and ensure that SOCI headers can be included (i.e. there is no need to use target_include_directories() explicitly). An example of a very simple CMake-based project using SOCI is provided in the examples/connect directory.

Alternatively, you can add SOCI as a subdirectory to your project and include it via add_subdirectory(). As before, target_link_libraries() is used to link with the SOCI libraries available under the same names Soci::core and Soci::<backend> as above. An example of this can be found in the directory examples/subdir-include.

If you don't use CMake but want to use SOCI in your program, you need to specify the paths to the SOCI headers and libraries in your build configuration and to tell the linker to link against the libraries you want to use in your program.