Installing ODB on Windows

This README describes installing the ODB compiler (odb), runtime libraries (libodb, libodb-<database>), and profile libraries (libodb-boost, libodb-qt) from binary packages on Windows.

The libodb-sqlite, libodb-pgsql, and libodb-mysql packages depend on the underlying database client libraries. These are bundled with the respective packages and you don't need to install them separately. For convenience, the underlying database client programs (sqlite3, psql and mysql, respectively) are also bundled.

Note also that the libodb-boost and libodb-qt packages do not bundle Boost/Qt. Instead, if you wish to use the corresponding profile, you are expected to install the desired Boost/Qt versions yourself.

The following ODB binary packages are provided for Windows:

odb-<...>.zip                 -- ODB compiler

libodb-<...>.zip              -- Common runtime library
libodb-<...>-debug.zip        -- Common runtime debug library

libodb-sqlite-<...>.zip       -- SQLite runtime library
libodb-sqlite-<...>-debug.zip -- SQLite runtime debug library

libodb-pgsql-<...>.zip        -- PostgreSQL runtime library
libodb-pgsql-<...>-debug.zip  -- PostgreSQL runtime debug library

libodb-mysql-<...>.zip        -- MySQL runtime library
libodb-mysql-<...>-debug.zip  -- MySQL runtime debug library

libodb-boost-<...>.zip        -- Boost profile library
libodb-boost-<...>-debug.zip  -- Boost profile debug library

libodb-qt-<...>.zip           -- Qt profile library
libodb-qt-<...>-debug.zip     -- Qt profile debug library

Above <...> denotes the version, architecture, OS, and runtime information, for example 2.5.0-x86_64-windowsX-msvcA.B, where X is the Windows version, for example, 10, and A.B is the MSVC version, for example, 17.10.

Note that the ODB compiler package does not have the -msvcA.B component (since it's not built with MSVC) and can be used on Windows version X or later. The library packages are built with MSVC version A.B and should be usable with that or later versions (they also normally work with earlier A.* versions). The libraries come in the release and debug variants.

Typically, when installing ODB, you would install the ODB compiler (odb), the common runtime library (libodb), plus one or more database-specific runtime libraries (libodb-<database>), depending on which database(s) you wish to target. To be able to persist types from either Boost or Qt you would also install the corresponding profile library.

All the packages are relocatable and can be installed into any location. To install them you can use your favorite zip archive extractor. Alternatively, on recent Windows 10 builds you can use the included BSD tar command line utility. For example, if you wish to use SQLite and to install to C:\odb:

> md C:\odb
> tar -xf odb-<...>.zip           -C C:\odb --strip-components=1
> tar -xf libodb-<...>.zip        -C C:\odb --strip-components=1
> tar -xf libodb-sqlite-<...>.zip -C C:\odb --strip-components=1

The resulting directory structure in C:\odb will look as follows:

C:\odb\
├── bin\
│   ├── odb.exe              -- ODB compiler
│   ├── odb-2.5.dll          -- Common runtime DLL
│   ├── odb-sqlite-2.5.dll   -- SQLite runtime DLL
│   ├── sqlite3-1.dll        -- SQLite client DLL
│   └── sqlite3.exe          -- SQLite client program
├── include\
│   ├── odb\                 -- ODB runtime headers
│   └── sqlite3.h            -- SQLite client header
└── lib\
    ├── odb.dll.lib          -- Common runtime import library
    ├── odb.lib              -- Common runtime static library
    ├── odb-sqlite.dll.lib   -- SQLite runtime import library
    ├── odb-sqlite.lib       -- SQLite runtime static library
    ├── sqlite3.dll.lib      -- SQLite import library
    └── sqlite3.lib          -- SQLite static library

You can install both debug and release libraries side-by-side into the same location. By convention, the debug .dll and .lib files contain the D suffix to distinguish them from release, for example, odbD-2.5.dll and odbD.dll.lib (there is no debug static library).

Or, as another example, if you wish to use PostgreSQL as well as the Boost profile:

> md C:\odb
> tar -xf odb-<...>.zip          -C C:\odb --strip-components=1
> tar -xf libodb-<...>.zip       -C C:\odb --strip-components=1
> tar -xf libodb-pgsql-<...>.zip -C C:\odb --strip-components=1
> tar -xf libodb-boost-<...>.zip -C C:\odb --strip-components=1

The resulting directory structure in C:\odb will look as follows:

C:\odb\
├── bin\
│   ├── odb.exe              -- ODB compiler
│   ├── odb-2.5.dll          -- Common runtime DLL
│   ├── odb-pgsql-2.5.dll    -- PostgreSQL runtime DLL
│   ├── odb-boost-2.5.dll    -- Boost profile DLL
│   ├── pq-5.dll             -- PostgreSQL client DLL
│   └── psql.exe             -- PostgreSQL client program
├── include\
│   ├── odb\                 -- ODB runtime/profile headers
│   └── libpq-fe.h           -- PostgreSQL client header
└── lib\
    ├── odb.dll.lib          -- Common runtime import library
    ├── odb.lib              -- Common runtime static library
    ├── odb-pgsql.dll.lib    -- PostgreSQL runtime import library
    ├── odb-pgsql.lib        -- PostgreSQL runtime static library
    ├── odb-boost.dll.lib    -- Boost profile import library
    ├── odb-boost.lib        -- Boost profile static library
    ├── pq.dll.lib           -- PostgreSQL import library
    └── pq.lib               -- PostgreSQL static library

The database client libraries may in turn depend on other libraries so you may see other DLLs in bin\.

To test the installation you can try to build and run an example, for example hello from the odb-examples source package (see examples README for details).

To build and run the example with SQLite, start an appropriate (normally x64) Visual Studio Command Prompt and then execute:

> C:\odb\bin\odb -IC:\odb\include --std c++11 -d sqlite ^
  --generate-query --generate-schema person.hxx

> cl /IC:\odb\include /DLIBODB_SHARED /EHsc /c person-odb.cxx
> cl /IC:\odb\include /DLIBODB_SHARED /DDATABASE_SQLITE /EHsc /c ^
  driver.cxx

> link /LIBPATH:C:\odb\lib driver.obj person-odb.obj ^
  odb-sqlite.dll.lib odb.dll.lib sqlite3.dll.lib

> set "PATH=C:\odb\bin;%PATH%"
> .\driver.exe --help
> .\driver --database .\test.sqlite3

To build and run the example with PostgreSQL, execute:

> C:\odb\bin\odb -IC:\odb\include --std c++11 -d pgsql ^
  --generate-query --generate-schema person.hxx

> cl /IC:\odb\include /DLIBODB_SHARED /EHsc /c person-odb.cxx
> cl /IC:\odb\include /DLIBODB_SHARED /DDATABASE_PGSQL /EHsc /c ^
  driver.cxx

> link /LIBPATH:C:\odb\lib driver.obj person-odb.obj ^
  odb-pgsql.dll.lib odb.dll.lib

> set "PATH=C:\odb\bin;%PATH%"
> psql --username=odb_test --dbname=odb_test -f person.sql
> .\driver.exe --help
> .\driver --user odb_test --database odb_test

To integrate the installation into your build system of IDE, add C:\odb\bin to the executable search paths (or to the PATH environment variable), C:\odb\include to the header search paths, and C:\odb\lib to the library search paths. Then link your application with the desired runtime/profile libraries. If using shared libraries, also define the LIBODB_SHARED preprocessor macro when compiling your application source files.