"\title=Installing ODB with build2"

"\H|Installing ODB with \c{build2}|

The latest ODB compiler and runtime libraries (\c{libodb*}) can now be built
and installed on all the major platforms (Linux, Windows, and Mac OS) from
source packages available in the \c{build2} \l{https://cppget.org/?q=odb
cppget.org} repository. See the current build status for the
\l{https://cppget.org/?builds=odb ODB compiler} and
\l{https://cppget.org/?builds=libodb* ODB runtime libraries}.

\N|While \c{2.5.0} is still in beta, at this stage in the development cycle it
is as stable as \c{2.4.0}, we are using it ourselves in multiple projects
(including \c{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 \c{2.4.0}, both \l{../../../support/ commercial and
best-effort}).|

This installation method uses the \c{build2} package manager (\c{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 the your own projects don't have to use
\c{build2} to benefit from this installation method. But if you would like
to learn more, see
\l{https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml The
\c{build2} Toolchain Introduction}.

\n\n"

"\$TOC$"

"
\h1#linux|Linux|

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

Note also that while most things are by default installed into \c{/usr/local},
with \c{build2} everything can be cleanly uninstalled at any moment as long as
you keep the build configuration that was used for the installation.

\h2#linux-build2|Installing \c{build2}|

Build the latest \c{build2} toolchain by following the
\l{https://build2.org/install.xhtml#unix UNIX (Linux, Mac OS, FreeBSD)}
installation instructions.


\h2#unix-odb|Building ODB Compiler|

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

\
$ gcc --version
gcc X.Y.Z

$ sudo apt-get install gcc-X-plugin-dev
\

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

\
$ sudo dnf install gcc-plugin-devel
\

Next create the build configuration (replace \i{X} with the GCC major
version):

\
$ mkdir odb-build
$ cd odb-build

$ bpkg create -d odb-gcc-X 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-X
\

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 upgrade:

\
$ bpkg fetch
$ bpkg status odb

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

See
\l{https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-consume-pkg
Package Consumption} for more information on these \c{bpkg} commands.


\h2#unix-libodb|Building ODB Runtime Libraries|

While you can build the ODB runtime libraries (\c{libodb*}) in the same build
configuration as the ODB compiler above, it will be easier to manage
(install/uninstall, upgrade, etc) if they are in a separate build
configuration.

Create the build configuration (replace \i{X} with the GCC major version):

\
$ cd odb-build

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

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

\
$ cd gcc-X
$ 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 install --all --recursive
\

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 (\c{libsqlite3},
\c{libmysqlclient}, and \c{libpq}) will be built from source packages.
If you would prefer to use the system-installed versions, adjust the
corresponding \c{build} commands as follows:

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

To upgrade:

\
$ cd gcc-X
$ bpkg fetch
$ bpkg status libodb libodb-...
$ 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 \c{libc++} runtime and install
it into \c{~/install/odb} (replace \i{X} with the Clang major version):

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

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


\h1#windows|Windows|

The overall plan is as follows: first install the \c{build2} toolchain (which
includes GCC build with plugins enabled) then use it to build and install the
ODB compiler (with GCC) and runtime libraries (with MSVC).

Note that the ODB compiler is installed into the \c{build2} installation
directory (\c{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{C:\\build2\\bin} in
your \c{PATH} as well as move/rename \c{C:\\build2} or zip and copy it to
another machine (in other words, \c{C:\\build2} is a self-sufficient ODB
compiler distribution).


\h2#windows-build2|Installing \c{build2}|

Build the latest \c{build2} toolchain by following the
\l{https://build2.org/install.xhtml#windows-mingw Windows with MinGW}
installation instructions.


\h2#windows-odb|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 upgrade:

\
> bpkg fetch
> bpkg status odb

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

See
\l{https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-consume-pkg
Package Consumption} for more information on these \c{bpkg} commands.


\h2#windows-libodb|Building ODB Runtime Libraries|

Start a suitable Visual Studio command prompt (for example, \c{x86} or
\c{x64}), then run:

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

> C:
> cd \odb-build
\

Create the Release and Debug build configurations:

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

> bpkg create -d 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 \c{.pdb} files, use this Debug configuration instead:

\
> bpkg create -d 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 \c{libodb-oracle} see
below). Here replace \i{XXX} either with \c{debug} or \c{release}:

\
> cd 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
> bpkg install --all --recursive
\

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
\

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

If you need both 32 and 64-bit builds, then repeat the above steps for the
other set of configurations (and from the corresponding Visual Studio command
prompt). In this case you may also want to include the width into your
build/install directory names (for example, \c{msvc-32-debug} and
\c{C:\\odb\\32\\debug}, etc).

If you also want to build \c{libodb-oracle}, then you will need to first
install the OCI library (see \c{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 \c{/I} and
\c{/LIBPATH} values to an existing configuration by editing its
\c{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 upgrade:

\
> cd msvc-XXX
> bpkg fetch
> bpkg status libodb libodb-...
> bpkg uninstall --all --recursive
> bpkg build --upgrade --recursive
> bpkg install --all --recursive
\


\h1#macos|Mac OS|

The overall plan is as follows: first install the \c{build2} toolchain then
use it to build and install the ODB compiler with Homebrew GCC. Finally, build
and install the ODB runtime libraries with Clang (and/or 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
\

Note also that while most things are by default installed into \c{/usr/local},
with \c{build2} everything can be cleanly uninstalled at any moment as long as
you keep the build configuration that was used for the installation.

\h2#macos-build2|Installing \c{build2}|

Build the latest \c{build2} toolchain by following the
\l{https://build2.org/install.xhtml#unix UNIX (Linux, Mac OS, FreeBSD)}
installation instructions.


\h2#macos-odb|Building ODB Compiler|

First install GCC from \l{https://brew.sh Homebrew} (here \i{X} is the GCC
major version):

\
$ brew update
$ brew info gcc
$ brew install gcc

$ which g++-X
\

Next create the build configuration (replace \i{X} with the GCC major
version):

\
$ mkdir odb-build
$ cd odb-build

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

$ cd odb-gcc-X
\

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 upgrade:

\
$ bpkg fetch
$ bpkg status odb

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

See
\l{https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-consume-pkg
Package Consumption} for more information on these \c{bpkg} commands.


\h2#macos-libodb|Building ODB Runtime Libraries|

The following steps show how to build the ODB runtime libraries (\c{libodb*})
with Apple Clang. However, you can instead (or in addition, see below) build
them with Homebrew GCC.

Create the build configuration (replace \i{X} with the Clang major version):

\
$ cd odb-build

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

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

\
$ cd clang
$ 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 install --all --recursive
\

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 (\c{libsqlite3},
\c{libmysqlclient}, and \c{libpq}) will be built from source packages.
If you would prefer to use the system-installed versions, adjust the
corresponding \c{build} commands as follows:

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

To upgrade:

\
$ cd clang-X
$ bpkg fetch
$ bpkg status libodb libodb-...
$ 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 \c{~/install/odb}:

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

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

"