Installing ODB with build2
The latest ODB
compiler and runtime libraries (libodb*) as well as their
dependencies 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 (or, alternatively, from pre-downloaded package archives if installing offline). See the current CI build status for
the ODB compiler and ODB runtime libraries.
Instead of building ODB from source you could use binary distribution packages provided for a number of mainstream platforms.
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.
If the application in which you will be using ODB is cross-compiled, use your host development platform to select the instructions to follow. Then build the ODB compiler for the host and the ODB runtime libraries for the target. For example, if you would like to cross-compile from Linux to Windows using the MinGW GCC cross-compiler, then you would follow the Linux instructions, use your host's native GCC to build the ODB compiler, and use MinGW GCC to build the ODB runtime libraries.
Note also that in build2 no special steps are required to
cross-compile. Simply specifying the correct compiler to use should be
sufficient in most cases. Continuing with the above example, if the MinGW
GCC cross-compiler binary is called x86_64-w64-mingw32-g++,
then all you have to do is to pass
config.cxx=x86_64-w64-mingw32-g++ when creating the build
configuration for the ODB runtime libraries.
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
On RHEL the gcc-plugin-devel package is available form the
optional "CodeReady Linux Builder" repository.
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/stable
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 README.md files
for additional requirements):
$ bpkg add https://pkg.cppget.org/1/stable $ 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, libpq, libmysqlclient)
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.c=clang \ config.cxx="clang++ -stdlib=libc++" \ 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.
2 Windows
The overall plan is as follows: first install the build2
toolchain (which includes GCC built 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 by default). 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/stable
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.
If you have multiple builds (for example, 32 and 64-bit), then repeat the
steps in this section for each of them. In this case you will also want to
include the build type into the configuration names (for example,
libodb-msvc-release-64) and installation directories (for
example, C:\odb\release-64\) to avoid clashes.
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.bin.lib=shared^ "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
It is possible to install release and debug builds into the same directory by adding a suffix to the debug libraries:
config.bin.lib.suffix=D
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/stable > 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 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
Sometimes there are issues with newer versions of GCC on Mac OS and in such cases you may want to try an older version. You can install a specific version of GCC like this:
$ brew install gcc@14
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++-N \ config.cc.coptions=-O3 \ config.bin.rpath=/usr/local/lib \ config.install.root=/usr/local \ config.install.sudo=sudo $ cd odb-gcc-N
If building on an Apple Silicon machine (M1, etc), 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++-N \ 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/stable
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:
$ bpkg add https://pkg.cppget.org/1/stable $ 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, libpq, libmysqlclient)
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/stable
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 ODB compiler build 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/stable $ 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
As in the normal instructions, you can instead use system-installed versions of dependencies. For example:
$ bpkg build libodb-X.Y.Z.tar.gz $ bpkg build libodb-sqlite-X.Y.Z.tar.gz ?sys:libsqlite3
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.