Installation

ObjectBox C / C ++ database is designed to make it easy and fast for you to persist objects using C / C++. Ideal for high-performance, high-frequency data and fast data applications.

To start developing with ObjectBox you'll need to get the library and the generator executable.

ObjectBox library

The APIs come as a single header file for C and C++:

Compile your code against it and use the runtime shared library (.so, .dylib, .dll depending on the platform) to link against.

There are a couple of ways to get the library:

CMake (v3.11+)
download.sh
Bintray
CMake (v3.11+)

If you're using CMake v3.11+ you can use CMake's FetchContent to get ObjectBox headers and library.

CMakeLists.txt
include(FetchContent)
FetchContent_Declare(
objectbox
GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
GIT_TAG v0.11.0
)
FetchContent_GetProperties(objectbox)
if(NOT objectbox_POPULATED)
FetchContent_Populate(objectbox)
endif()
add_executable(myapp main.cpp)
target_link_libraries(myapp objectbox)

Additionally, if you're using C instead of C++ you also need to get the flatcc library (see below for details). You can use FetchContent to do that as well:

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)

If you have CMake v3.14+, you can simplify the code even further by replacing

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

with a single line:

FetchContent_MakeAvailable(objectbox)
download.sh

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

  • Either clone the repo and run ./download.sh

  • ... or get download.sh and run it in a terminal: bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-c/main/download.sh)

Details on the download.sh script:

  • Creates a "download" directory and a version dependent sub directory named like "libobjectbox-0.1-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).

Bintray

Get the latest binary by browsing its Bintray repository (Conan repository format): https://bintray.com/objectbox/conan/objectbox-c%3Aobjectbox

Distributing

Don't forget to include the library (so/dylib/dll) with your program when distributing/packaging for installer, otherwise your program users won't be able to run it.

Having the library in the same directory as your program binary should be enough for Windows. For other OSs you might need to ensure the installation library to the system directory (/usr/lib or /usr/local/lib) or one of the paths specified inLD_LIBRARY_PATH(linux) orDYLD_LIBRARY_PATH(macos).

FlatBuffers library

ObjectBox uses FlatBuffers high-performance binary representation to achieve cross-platform compatibility of the stored data. Google provides FlatBuffers implementation for various languages, including C++ and there's an independent implementation for C as well (third-party & semi-official - Google points to for C support). You can thus make your choice depending on the language you use.

  • For C: get flatcc library and headers. You can link your program to the to the static runtime library.

  • For C++: get flatbuffers headers. Objectbox shared library already includes flatbuffers symbols so no additional linking should be necessary. If you're using CMake's FetchContent, you don't need to get the flatbuffers headers separately - they're already part of the objectbox library interface include directories.

Even though you could use flatcc/plain C code in a C++ project, you'd be losing on the convenience and additional features provided by the code generated by ObjectBox Generator.

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

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.

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