Skip to main content

How to get started

ObjectBox Generator produces binding code for ObjectBox C & C++ APIs. This greatly simplifies the model declaration and FlatBuffers serialization, allowing you to concentrate on the application logic.

Generating binding code​

info

ObjectBox Generator is a tool, which must be downloaded separately. For details, please check the installation page.

ObjectBox Generator uses FlatBuffer schema file (.fbs) as its primary input. The Generator also maintains some metadata around the data model in a JSON file (objectbox-model.json). Based on these two files, it generates code for the selected language (C or C++).

Let’s have a look at a sample schema and how Generator helps us.

tasklist.fbs
table Task {
id: ulong;
text: string;
date_created: ulong;
date_finished: ulong;
}

Use CMake or launch the following command to generate the binding code from the FlatBuffers schema file:

find_package(ObjectBoxGenerator 5.0.0 REQUIRED)
add_obx_schema(TARGET myapp SCHEMA_FILES tasklist.fbs INSOURCE)

The following files will be generated:

  • objectbox-model.h
  • objectbox-model.json
  • tasklist.obx.hpp
  • tasklist.obx.cpp
info

See #cmake-supportfor details on CMake integration.

warning

You should add all these generated files to your source control (e.g. git), most importantly objectbox-model.json which ensures compatibility with previous versions of your database after you make changes to the schema.

Working with Object Boxes​

Bet you wondered where our name comes from :)

From an ObjectBox Store, you get Box instances to manage your entities. While you can have multiple Box instances of the same type (for the same Entity) "open" at once, it's usually preferable to just use one instance and pass it around your code.

Now, you can include the generated headers in your application and start working with your database. Consider the following main file:

main.cpp
#define OBX_CPP_FILE
#include "objectbox.hpp"
#include "objectbox-model.h"
#include "tasklist.obx.hpp"

int main(int argc, char* args[]) {
// create_obx_model() provided by objectbox-model.h
// obx interface contents provided by objectbox.hpp
obx::Store store(create_obx_model());
obx::Box<Task> box(store);

obx_id id = box.put({.text = "Buy milk"}); // Create
std::unique_ptr<Task> task = box.get(id); // Read
if (task) {
task->text += " & some bread";
box.put(*task); // Update
box.remove(id); // Delete
}
return 0;
}
info

It's required to have exactly one .cpp file in your project that defines OBX_CPP_FILE right before the inclusion of the "objectbox.hpp" header.

This #define instructs the "objectbox.hpp" header to emit implementation definitions. If you accidentally have it in multiple files, the linker will complain about multiple symbols (having the same name).