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.
While version 2.5.0
is still in beta, at this stage in the
development cycle it is as stable as 2.4.0
, we are using it
ourselves in multiple projects (including build2
), we have
migrated a number of users with very good results, and it is fully supported
(that is, we provide the same level of support as for 2.4.0
,
both commercial and best-effort).
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
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.
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.
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.cc.coptions=/Od /MDd /Zi"^ config.cc.loptions=/DEBUG^ config.install.root=C:\odb\debug
If you prefer to include the debug information into the libraries instead
of having it in separate .pdb
files, 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
There is an issue with newer versions of GCC (11.3, 12.1) on Intel (but not M1) Mac OS. Older versions of GCC (10.x, 11.2) seem to work. You can install the specific version of GCC with the following command:
$ brew install gcc@10
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.