Installing ODB with build2

The latest ODB compiler and runtime libraries (libodb*) can now be built and installed on all the major platforms (Linux, Windows, and Mac OS) from source packages available in the build2 cppget.org repository. See the current build status for the ODB compiler and ODB runtime libraries.

This installation method uses the build2 package manager (bpkg) which has a uniform interface across all the platforms and compilers. It significantly simplifies the initial build as well as the ongoing maintenance (upgrades/downgrades, etc). Note also that your own projects don't have to use build2 to benefit from this installation method. But if you would like to learn more, see The build2 Toolchain Introduction.

1 Linux

The overall plan is as follows: first install the build2 toolchain then use it to build and install the ODB compiler (with system GCC) and runtime libraries (with GCC or Clang).

In this section we use /usr/local as the installation directory but this can be changed by adjusting the relevant configuration variables. Note also that with build2 everything can be cleanly uninstalled at any moment as long as you keep the build configurations that were used for the installation.

1.1 Installing build2

Build the latest build2 toolchain by following the UNIX (Linux, Mac OS, FreeBSD) installation instructions.

1.2 Building ODB Compiler

First make sure the GCC plugin headers are installed. For Debian/Ubuntu, this package is called gcc-N-plugin-dev (where N is the GCC major version), for example:

$ gcc --version
gcc X.Y.Z

$ sudo apt-get install gcc-N-plugin-dev

For RedHat/Fedora, this package is called gcc-plugin-devel, for example (replace dnf with yum for older distributions):

$ sudo dnf install gcc-plugin-devel

Next create the build configuration (replace N with the GCC major version):

$ mkdir odb-build
$ cd odb-build

$ bpkg create -d odb-gcc-N cc     \
  config.cxx=g++                  \
  config.cc.coptions=-O3          \
  config.bin.rpath=/usr/local/lib \
  config.install.root=/usr/local  \
  config.install.sudo=sudo

$ cd odb-gcc-N

To build:

$ bpkg build odb@https://pkg.cppget.org/1/beta

To test:

$ bpkg test odb

To install:

$ bpkg install odb

$ which odb
$ odb --version

To uninstall:

$ bpkg uninstall odb

To upgrade:

$ bpkg fetch
$ bpkg status odb

$ bpkg uninstall odb
$ bpkg build --upgrade --recursive odb
$ bpkg install odb

See Package Consumption for more information on these bpkg commands.

1.3 Building ODB Runtime Libraries

When it comes to the ODB runtime libraries (libodb*), it's a good idea to use the same C++ compiler and settings as for the application in which you will be using ODB. In this section we will use GCC as an example.

First create the build configuration (replace N with the GCC major version):

$ cd odb-build

$ bpkg create -d libodb-gcc-N cc  \
  config.cxx=g++                  \
  config.cc.coptions=-O3          \
  config.install.root=/usr/local  \
  config.install.sudo=sudo

$ cd libodb-gcc-N

Next decide which database runtime libraries you need and perform the following steps (for libodb-oracle and libodb-mssql see their respective INSTALL files for additional requirements):

$ bpkg add https://pkg.cppget.org/1/beta
$ bpkg fetch
$ bpkg build libodb
$ bpkg build libodb-sqlite
$ bpkg build libodb-pgsql
$ bpkg build libodb-mysql

If you are using Boost and/or Qt profile libraries, then build them (before installing) together with the runtime libraries:

$ bpkg build libodb-qt
$ bpkg build libodb-boost

Note that by default the underlying database libraries (libsqlite3, libmysqlclient, and libpq) will be built from source packages. If you would prefer to use the system-installed versions, adjust the corresponding build commands as follows:

$ bpkg build libodb-sqlite ?sys:libsqlite3
$ bpkg build libodb-pgsql  ?sys:libpq
$ bpkg build libodb-mysql  ?sys:libmysqlclient

To install:

$ bpkg install --all --recursive

To uninstall:

$ bpkg uninstall --all --recursive

To upgrade:

$ bpkg fetch
$ bpkg status
$ bpkg uninstall --all --recursive
$ bpkg build --upgrade --recursive
$ bpkg install --all --recursive

Note also that you can create as many builds of the runtime libraries as you need: different compilers, debug/release, 32/64-bit, etc. Simply create another build configuration with the desired settings and repeat the above steps. For such development builds you will also probably want to adjust the installation location to somewhere private. For, example, this is how we can create a debug build that uses Clang with the libc++ runtime and install it into ~/install/odb (replace N with the Clang major version):

$ bpkg create -d libodb-clang-N-libc++-debug cc \
  config.cxx=clang++                            \
  config.cc.coptions=-g                         \
  config.cxx.coptions=-stdlib=libc++            \
  config.install.root=$HOME/install/odb

After the installation the ODB runtime headers will be in ~/install/odb/include and libraries in ~/install/odb/lib. To use this build simply add the corresponding -I and -L options to your project's build configuration.

2 Windows

The overall plan is as follows: first install the build2 toolchain (which includes GCC build with plugins enabled) then use it to build and install the ODB compiler and runtime libraries. While in this section we will use MSVC as the C++ compiler for the runtime libraries, Clang and MinGW GCC can be used as well.

Note that the ODB compiler is installed into the build2 installation directory (C:\build2). Currently this is the only supported arrangement due to the complexity of finding plugins, compilers, etc. Note also that you should be able to run the ODB compiler without having C:\build2\bin in your PATH as well as move/rename C:\build2 or zip and copy it to another machine (in other words, C:\build2 is a self-sufficient ODB compiler distribution).

2.1 Installing build2

Build the latest build2 toolchain by following the Windows with MinGW installation instructions.

Note: if your organization's network security breaks the installation process (often the case on Windows when trying to use curl), then consider Installing Offline.

2.2 Building ODB Compiler

Open the command prompt, then run:

> set "PATH=C:\build2\bin;%PATH%"

> C:
> md \odb-build
> cd \odb-build

Create the build configuration:

> bpkg create -d odb-mingw cc^
  config.cxx=g++^
  config.cc.coptions=-O2^
  config.install.root=C:\build2

> cd odb-mingw

To build:

> bpkg build odb@https://pkg.cppget.org/1/beta

To test:

> bpkg test odb

To install:

> bpkg install odb

> where odb
> odb --version

To uninstall:

> bpkg uninstall odb

To upgrade:

> bpkg fetch
> bpkg status odb

> bpkg uninstall odb
> bpkg build --upgrade --recursive odb
> bpkg install odb

See Package Consumption for more information on these bpkg commands.

2.3 Building ODB Runtime Libraries

When it comes to the ODB runtime libraries (libodb*), it's a good idea to use the same C++ compiler and settings as for the application in which you will be using ODB. The easiest way to accomplish this is by starting a Visual Studio command prompt (for example, x86 or x64) that corresponds to your application's build.

In the Visual Studio command prompt run:

> set "PATH=C:\build2\bin;%PATH%"

> C:
> cd \odb-build

Create the Release and Debug build configurations:

> bpkg create -d libodb-msvc-release cc^
  config.cxx=cl^
  "config.cc.coptions=/O2 /MD"^
  config.install.root=C:\odb\release

> bpkg create -d libodb-msvc-debug cc^
  config.cxx=cl^
  "config.cc.coptions=/Od /MDd /Zi"^
  config.cc.loptions=/DEBUG:FULL^
  config.install.root=C:\odb\debug

If you wish to build a static library with debug information, use this Debug configuration instead:

> bpkg create -d libodb-msvc-debug cc^
  config.cxx=cl^
  "config.cc.coptions=/Od /MDd /Z7"^
  config.install.root=C:\odb\debug

Next, for each build configuration perform the following set of steps (pick the database runtime libraries that you need; for libodb-oracle see below). Here replace XXX either with debug or release:

> cd libodb-msvc-XXX

> bpkg add https://pkg.cppget.org/1/beta
> bpkg fetch
> bpkg build libodb
> bpkg build libodb-sqlite
> bpkg build libodb-pgsql
> bpkg build libodb-mysql
> bpkg build libodb-mssql

If you are using Boost and/or Qt profile libraries, then build them (before installing) together with the runtime libraries:

> bpkg build libodb-qt
> bpkg build libodb-boost

If you also want to build libodb-oracle, then you will need to first install the OCI library (see libodb-oracle\INSTALL for various ways to obtain it) and then specify the location of its headers and libraries when creating the build configurations (you can also add the necessary /I and /LIBPATH values to an existing configuration by editing its libodb-msvc-XXX\build\config.build file). For example:

> bpkg create ...^
  config.cc.poptions=/IC:\oracle\oci\include^
  config.cc.loptions=/LIBPATH:C:\oracle\oci\lib\msvc^

To install:

> bpkg install --all --recursive

The result (both shared and static libraries) will be in the C:\odb\XXX\ directories with headers in the include\ subdirectory, static libraries and DLL import stubs (.lib) in lib\ and DLLs in bin\.

To uninstall:

> bpkg uninstall --all --recursive

To upgrade:

> bpkg fetch
> bpkg status
> bpkg uninstall --all --recursive
> bpkg build --upgrade --recursive
> bpkg install --all --recursive

3 Mac OS

The overall plan is as follows: first install the build2 toolchain then use it to build and install the ODB compiler with Homebrew GCC. Finally, build and install the ODB runtime libraries with Apple Clang (and/or Homebrew GCC).

As a first step, make sure you have Apple Clang:

$ clang++ --version

If it's not present, install it as part of the Command Line Tools:

$ xcode-select --install

In this section we use /usr/local as the installation directory but this can be changed by adjusting the relevant configuration variables. Note also that with build2 everything can be cleanly uninstalled at any moment as long as you keep the build configurations that were used for the installation.

3.1 Installing build2

Build the latest build2 toolchain by following the UNIX (Linux, Mac OS, FreeBSD) installation instructions.

3.2 Building ODB Compiler

First install GCC from Homebrew (here N is the GCC major version):

$ brew update
$ brew info gcc
$ brew install gcc

$ which g++-N

$ brew install gcc@13

Next create the build configuration (replace N with the GCC major version):

$ mkdir odb-build
$ cd odb-build

$ bpkg create -d odb-gcc-N cc     \
  config.cxx=g++-X                \
  config.cc.coptions=-O3          \
  config.bin.rpath=/usr/local/lib \
  config.install.root=/usr/local  \
  config.install.sudo=sudo

$ cd odb-gcc-N

If on M1 Mac OS, then you will also need to add /opt/homebrew/include as the header search path while creating the build configuration:

$ bpkg create -d odb-gcc-N cc                \
  config.cxx=g++-X                           \
  config.cc.poptions=-I/opt/homebrew/include \
  config.cc.coptions=-O3                     \
  config.bin.rpath=/usr/local/lib            \
  config.install.root=/usr/local             \
  config.install.sudo=sudo

To build:

$ bpkg build odb@https://pkg.cppget.org/1/beta

To test:

$ bpkg test odb

To install:

$ bpkg install odb

$ which odb
$ odb --version

To uninstall:

$ bpkg uninstall odb

To upgrade:

$ bpkg fetch
$ bpkg status odb

$ bpkg uninstall odb
$ bpkg build --upgrade --recursive odb
$ bpkg install odb

See Package Consumption for more information on these bpkg commands.

3.3 Building ODB Runtime Libraries

When it comes to the ODB runtime libraries (libodb*), it's a good idea to use the same C++ compiler and settings as for the application in which you will be using ODB. In this section we will use Apple Clang as an example. However, you can instead (or in addition, see below) build them with Homebrew GCC.

First create the build configuration (replace N with the Clang major version):

$ cd odb-build

$ bpkg create -d libodb-clang-N cc \
  config.cxx=clang++               \
  config.cc.coptions=-O3           \
  config.install.root=/usr/local   \
  config.install.sudo=sudo

$ cd libodb-clang-N

Next decide which database runtime libraries you need and perform the following steps (for libodb-oracle and libodb-mssql see their respective INSTALL files for additional requirements):

$ bpkg add https://pkg.cppget.org/1/beta
$ bpkg fetch
$ bpkg build libodb
$ bpkg build libodb-sqlite
$ bpkg build libodb-pgsql
$ bpkg build libodb-mysql

If you are using Boost and/or Qt profile libraries, then build them (before installing) together with the runtime libraries:

$ bpkg build libodb-qt
$ bpkg build libodb-boost

Note that by default the underlying database libraries (libsqlite3, libmysqlclient, and libpq) will be built from source packages. If you would prefer to use the system-installed versions, adjust the corresponding build commands as follows:

$ bpkg build libodb-sqlite ?sys:libsqlite3
$ bpkg build libodb-pgsql  ?sys:libpq
$ bpkg build libodb-mysql  ?sys:libmysqlclient

To install:

$ bpkg install --all --recursive

To uninstall:

$ bpkg uninstall --all --recursive

To upgrade:

$ bpkg fetch
$ bpkg status
$ bpkg uninstall --all --recursive
$ bpkg build --upgrade --recursive
$ bpkg install --all --recursive

Note also that you can create as many builds of the runtime libraries as you need: different compilers, debug/release, 32/64-bit, etc. Simply create another build configuration with the desired settings and repeat the above steps. For such development builds you will also probably want to adjust the installation location to somewhere private. For, example, this is how we can create a debug build and install it into ~/install/odb:

$ bpkg create -d libodb-clang-N-debug cc \
  config.cxx=clang++                     \
  config.cc.coptions=-g                  \
  config.install.root=$HOME/install/odb

After the installation the ODB runtime headers will be in ~/install/odb/include and libraries in ~/install/odb/lib. To use this build simply add the corresponding -I and -L options to your project's build configuration.

4 Installing Offline

The installation process described in the previous sections requires network access. If you need to install offline or if your organization's network security breaks the installation process (often the case on Windows when trying to use curl), then it's possible to install ODB without the network access by pre-downloading and copying the required files from another computer (or using tools compatible with your organization's network security, such as the web browser). This section describes the changes to the above installation process that are required to accomplish this.

4.1 Installing build2

To install build2 without network access follow the instructions in the How to install offline FAQ entry. On Windows make sure to use the MinGW installation script.

4.2 Building ODB Compiler

To build and install the ODB compiler without network access, follow the normal instructions for your platform from one of the above sections until the bpkg build command:

$ bpkg build odb@https://pkg.cppget.org/1/beta

Instead of executing this command (which will attempt to download the odb package and all its dependencies over the network), on a machine with network access go with your web browser to the odb package page and navigate to the desired odb package version page (use the latest version if unsure).

On the odb package version page you will find the download link to the odb compiler package (odb-X.Y.Z.tar.gz) as well as the Depends section with links to the libstudxml and libcutl dependencies that it requires (you don't need the optional cli dependency). Click on the version number next to the dependency package name to go directly to its package version page. There download libstudxml-X.Y.Z.tar.gz and libcutl-X.Y.Z.tar.gz (the X.Y.Z versions for all three packages will most likely be different). At the end of this exercise you should have the following three files in your build configuration directory:

odb-X.Y.Z.tar.gz
libstudxml-X.Y.Z.tar.gz
libcutl-X.Y.Z.tar.gz

Now instead of the above bpkg build command execute:

$ bpkg build --configure-only libstudxml-X.Y.Z.tar.gz
$ bpkg build --configure-only libcutl-X.Y.Z.tar.gz
$ bpkg build odb-X.Y.Z.tar.gz

Once this is done, you can continue with the normal instructions for your platform. Note, however, that the upgrade step will not be possible with this setup and you will need to repeat the above manual download steps to upgrade to a newer version of ODB.

4.3 Building ODB Runtime Libraries

To build and install the ODB runtime libraries without network access, follow the normal instructions for your platform from one of the above sections until the bpkg add/fetch/build commands:

$ bpkg add https://pkg.cppget.org/1/beta
$ bpkg fetch
$ bpkg build libodb
...

Instead of executing these commands (which will attempt to download the odb runtime libraries and all their dependencies over the network), follow the same procedure as for the ODB compiler: download the archives of the runtime libraries you are interested in as well as their dependencies and then build those archives.

For example, if you need libodb and libodb-sqlite, go to the libodb package and libodb-sqlite package pages, pick the same versions as the ODB compiler package, and download their archives and dependencies. At the end of this exercise you should have the following three files in your build configuration directory:

libodb-X.Y.Z.tar.gz
libodb-sqlite-X.Y.Z.tar.gz
libsqlite3-X.Y.Z.tar.gz

Now instead of the above bpkg add/fetch/build commands execute:

$ bpkg build libodb-X.Y.Z.tar.gz
$ bpkg build libsqlite3-X.Y.Z.tar.gz
$ bpkg build libodb-sqlite-X.Y.Z.tar.gz

Once this is done, you can continue with the normal instructions for your platform. Note, however, that the upgrade step will not be possible with this setup and you will need to repeat the above manual download steps to upgrade to a newer version of ODB.