Installation
The ObjectBox C / C ++ database is setup within minutes. Get the library and the generator and start developing high performance data applications.
ObjectBox library
There are a couple of ways to get the ObjectBox library (we recommend CMake 3.14 or newer):
Use CMake's FetchContent to get ObjectBox headers and library ready to use in your project:
If you want to use an ObjectBox Sync variant of the library, change the list line to:
Supported Platforms: Linux (x86_64, aarch64, armv7hf, armv6hf), macOS (x64,arm64), Windows (x64,x86) On Windows you might have to install the latest Microsoft Visual C++ Redistributable package (X64) to use the ObjectBox DLL. Support for other platforms and architectures on request (i.e. QNX, armv6)
Once you setup the headers and library like this, you can already start using the ObjectBox API! Here's a minimal example to verify your setup:
#define OBX_CPP_FILE
is not strictly required in this minimal example. However, when starting with the real C++ API, it is required to have exactly one .cpp file that defines OBX_CPP_FILE right before the inclusion of the "objectbox.hpp" header.
If you used CMake to setup your project you can already build and execute this program. Otherwise ensure your includes and the runtime shared library (libobjectbox.so, .dylib, .dll depending on the platform) are setup correctly for your compiler and linker environment.
ObjectBox Generator
Install the objectbox-generator
executable by downloading the version for your OS from releases. If you want, add it to $PATH
for convenience. Alternatively, instead of downloading, you can build the generator yourself by cloning this repo and running make
. To build yourself, you need a recent Go version, CMake and a C++11 toolchain.
ObjectBox Generator is a tool that will help you with during development of your application (and as opposed to the objectbox shared library, it's not supposed to be distributed with your app).
Try running objectbox-generator -help
to verify the installation and see the options.
FlatBuffers
If you are using the recommended CMake's FetchContent ObjectBox setup, there's no FlatBuffers setup required. You can skip this section.
ObjectBox uses FlatBuffers to represent objects at lower levels. It is a highly efficient binary representation that works across platforms.
To set up ObjectBox for C++ projects, you need to provide the FlatBuffers headers additionally. The objectbox.hpp header file requires it; e.g. you will find the line #include "flatbuffers/flatbuffers.h"
there. Thus, you also need it when using ObjectBox Generator (see above).
We recommend using ObjectBox Generator, which generates C++ data (entity) classes. It's a higher level abstraction which takes care of FlatBuffers internals so you don't have to.
Nevertheless, advanced users may also use FlatBuffers directly, e.g. for zero-copy data access, which can be even faster.
How to get the FlatBuffer headers:
The ObjectBox shared library already includes FlatBuffers symbols so no additional linking should be necessary. For headers, there are the following options (chose one):
If you're using the recommended CMake setup with the
FetchContent
command like described above, you are already set up to work with FlatBuffers APIs. (The FlatBuffers headers are already part of theobjectbox
library interface include directories.)Get the latest FlatBuffers headers and e.g. copy them into your source/include path.
Add the "external" directory from our C/C++ GitHub repository as an include path to your project. This is likely not the latest version of FlatBuffers. On the upside it is tested to work with ObjectBox.
The OBX_DISABLE_FLATBUFFERS
define
For special setups, the objectbox.hpp header also allows a configuration, which does not depend on including FlatBuffers. This is a limited setup, as it does not allow putting entities created by ObjectBox Generator. It can be helpful though, e.g. if you want to verify your ObjectBox basic setup without generated entities yet as a first step. To enable this, simply add the OBX_DISABLE_FLATBUFFERS
define to your C++ compiler configuration.
Last updated