This ObjectBox beginner tutorial is for people who have limited knowledge of C++ development (no prior experience with external libraries is required). It will walk you through the installation process of all the development tools needed to get started with ObjectBox on Windows. By the way, ObjectBox is a database with intuitive native APIs, so it won’t take you long to start using it.
Firstly, we will need to set up a Linux subsystem (WSL2) and install such tools as:
- CMake, which will generate build files from the ObjectBox source code to work on Linux;
- Git, which will download the source code from the ObjectBox repository.
Then, we will install ObjectBox and run a simple example in Visual Studio Code.
Windows Subsystem for Linux (WSL2)
In this section, you will set up a simple Linux subsystem that you can use to build Objectbox in C++.
- Install WSL (Note: this requires a reboot; it also configures a limited HyperV that may cause issues with e.g. VirtualBox).
Warning: to paste e.g. a password to the Ubuntu setup console window, right-click the title bar and select Edit → Paste. CTRL + V may not work. - (optional, but recommended) install Windows Terminal from Microsoft Store and use Ubuntu from there (does not have the copy/paste issue, also supports terminal apps better).
3. Within Windows Terminal, open Ubuntu by choosing it from the dropdown menu.
4. Get the latest packages and upgrade:
| 1 2 | sudo apt update sudo apt upgrade |
5. Install build tools
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | sudo apt install build-essential git cmake ccache gdb # install LLVM / clang LLVM_VERSION=12 sudo apt install clang-$LLVM_VERSION clang-tools-$LLVM_VERSION clang-format-$LLVM_VERSION lldb-$LLVM_VERSION lld-$LLVM_VERSION clangd-$LLVM_VERSION # Make clang-LLVM_VERSION the default clang, and clang the default C/C++ compiler sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-$LLVM_VERSION 1000 sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 1000 sudo update-alternatives --config c++ sudo update-alternatives --config clang++ sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-$LLVM_VERSION 1000 sudo update-alternatives --install /usr/bin/cc cc /usr/bin/clang 1000 sudo update-alternatives --config cc sudo update-alternatives --config clang cc --version c++ --version # clang tools sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-$LLVM_VERSION 1000 sudo update-alternatives --install /usr/bin/scan-build scan-build /usr/bin/scan-build-$LLVM_VERSION 1000 # lld is faster than the standard ld linker sudo update-alternatives --install /usr/bin/ld ld /usr/bin/ld.lld-$LLVM_VERSION 50 sudo update-alternatives --install /usr/bin/ld ld /usr/bin/ld.bfd 10 sudo update-alternatives --config ld ld --version |
Install ObjectBox using CMake
Now that you have WSL2 and all the packages, we can switch to VS Code and install ObjectBox with the help of CMake.
- In Ubuntu, create a new directory and then open it in Visual Studio Code:
| 1 2 3 | mkdir objectbox-ex cd objectbox-ex code . |
2. Install the following extensions:
3. Create a text file called CMakeLists.txt with the following code. It will tell CMake to get the ObjectBox source code from its Git repository and link the library to your project.
| 1 2 3 4 5 6 7 8 9 10 11 12 | include(FetchContent) FetchContent_Declare( objectbox GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git GIT_TAG v0.14.0 ) FetchContent_MakeAvailable(objectbox) add_executable(myapp main.cpp) target_link_libraries(myapp objectbox) |
4. Create a simple main.cpp file that will help us verify the setup:
| 1 2 3 4 5 6 | #include "objectbox.hpp" int main() { printf("Using ObjectBox version %s\n", obx_version_string()); } |
5. Follow this official guide for VS code and CMake to select Clang as the compiler, configure and build ObjectBox. As a result, .vscode and build folders will be generated. So your directory should now look like this:
Running the tasks-list app example
Finally, we can check that everything works and run a simple example.
1. Click the “Select target to launch” button on the status bar and select “myapp” from the dropdown menu. Then launch it. You should see it output the correct version as in the screenshot.
2. Before proceeding with the example, you need to download the most recent ObjectBox generator for Linux from releases. Then come back to the Windows Terminal and type
| 1 | explorer.exe . |
to open the current directory in Windows Explorer. Copy the objectbox-generator file in there.
3. Back in VS Code, you should now run the generator for the example code:
| 1 | ./objectbox-generator -cpp build/_deps/objectbox-src/examples/cpp-gen/tasklist.fbs |
If you get a “permission denied” error, try this to make the generator file executable for your user:
| 1 | chmod +x objectbox-generator |
4. Now choose objectbox-c-examples-tasks-cpp-gen as the target and run it. You should see the menu of a simple to-do list app as shown on the screenshot. It stores your tasks, together with their creation time and status. Try playing around with it and exploring the code of this example app to get a feel of how ObjectBox can be used.
Note: if you see a sync error (e.g. Can not modify object of sync-enabled type “Task” because sync has not been activated for this store), please delete the first line from the tasklist.fbs file and run the objectbox generator once again. Or, if you want to try sync, apply for our Early Access Data Sync. There is a separate example (called objectbox-c-examples-tasks-cpp-gen-sync) that you can run after installing the Sync Server.