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 to get ObjectBox headers and library ready to use in your project:

CMakeLists.txt

cmake_minimum_required(VERSION 3.14)
project(myapp)
set(CMAKE_CXX_STANDARD 11) # C++11 or higher

include(FetchContent)
FetchContent_Declare(
    objectbox
    GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
    GIT_TAG        v4.1.0
)

FetchContent_MakeAvailable(objectbox)

add_executable(myapp main.cpp)
target_link_libraries(myapp objectbox)

If you want to use an ObjectBox Sync variant of the library, change the target_link_libraries to:

target_link_libraries(myapp objectbox-sync)

Use to get ObjectBox headers and library into your project like this:

CMakeLists.txt

cmake_minimum_required(VERSION 3.11)
project(myapp)
set(CMAKE_CXX_STANDARD 11) # C++11 or higher

include(FetchContent)
FetchContent_Declare(
    objectbox
    GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
    GIT_TAG        v4.1.0
)

FetchContent_GetProperties(objectbox)
if(NOT objectbox_POPULATED)
  FetchContent_Populate(objectbox)
endif()

add_executable(myapp main.cpp)
target_link_libraries(myapp objectbox)

If you want to integrate the ObjectBox-Generator via CMake (as an alternative to offline installation and pre-generation of C++ sources), use the following snippet:

# find objectbox-generator (auto-download if not found on system per default)
find_package(ObjectBoxGenerator 4.0.0 REQUIRED)

# generate C++ files from tasklist.fbs and compile/link with target
add_obx_schema(
  TARGET myapp 
  SCHEMA_FILES tasklist.fbs 
  INSOURCE # Opt-in: Generate in source directory
  CXX_STANDARD 11 # Defaults to C++14 otherwise
)

If you want to use an ObjectBox Sync variant of the library, change the list line to:

CMakeLists.txt

target_link_libraries(myapp objectbox-sync)

Using the download.sh script (on Windows, use something like Git Bash to run it)

To get the ObjectBox Sync variant of the library, pass --sync to the previous command.

Details on the download.sh script:

Creates a "download" directory and a version dependent sub directory named like "libobjectbox-4.1.0-some-hex-hash".
Inside the version dependent sub directory, you will find the directories "include" and "lib"/
The "lib" directory contains the binary library.
Gives you an option to install the library to /usr/lib (linux) or /usr/local/lib (macOS).

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:

main.cpp

#define OBX_CPP_FILE // Put this define in one file only before including
#include "objectbox.hpp"

int main() {
    printf("Using ObjectBox version %s\n", obx_version_string());
    return 0;
}

#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.

main.c

#include "objectbox.h"

int main() {
    printf("ObjectBox version %s\n", obx_version_string());
    return 0;
}

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

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).

Using the ObjectBox Generator with CMake is straightforward (after the installation via FetchContent above):

# Downloads automatically if not found on system per default)
find_package(ObjectBoxGenerator 4.0.0 REQUIRED)

# generate C++ files from tasklist.fbs and compile/link with target
add_obx_schema(
  TARGET myapp 
  SCHEMA_FILES tasklist.fbs 
  INSOURCE # Opt-in: Generate in source directory
  CXX_STANDARD 11 # Defaults to C++14 otherwise
)

Try running objectbox-generator -help to verify the installation and see the options.

FlatBuffers

ObjectBox uses FlatBuffers to represent objects at lower levels. It is a highly efficient binary representation that works across platforms. For advanced usage, you can opt to work with FlatBuffers directly.

If you are using the recommended CMake's FetchContent ObjectBox setup, there's no FlatBuffers setup required. You can skip this section.

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).

The default ObjectBox mode of operation involves the 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.

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 the objectbox library interface include directories.)

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.

CMake example (check the link above for the latest version):

FetchContent_Declare(
    flatcc
    GIT_REPOSITORY https://github.com/dvidelabs/flatcc.git
    GIT_TAG        v0.6.0
)

FetchContent_GetProperties(flatcc)
if(NOT flatcc_POPULATED)
  FetchContent_Populate(flatcc)
endif()

add_executable(c99app main.c)
target_link_libraries(c99app objectbox flatccrt)

PreviousObjectBox C / C++ Database NextHow to get started

Last updated 4 months ago

Was this helpful?