Version 5.0.0-rc

Author: greenrobot

.gitlab-ci.yml

@@ -2,6 +2,6 @@ image: objectboxio/cbuild-ubuntu18.04:2023-08-23
 
 build:
   stage: build
-  tags: [x64, docker, linux]
+  tags: [x64, docker ]
   script:
     - ./test.sh

CHANGELOG.md

@@ -1,6 +1,29 @@
 ObjectBox C and C++ API Changelog
 =================================
 
+5.0.0-rc (2025-09-30)
+------------------
+
+### User-Specific Data Sync
+
+* Sync filters: define server-side filter expression to sync individual data for each sync user.
+  This is also known as "user-specific data sync" and requires Sync clients version 5.0.
+* Client variables: clients may define key/value pairs that can be used in sync filters
+
+### Fixes
+
+* Fixed clearing 1:N backlinks for IDs larger than 32-bit (setting backlink ID to 0 on the "1" side)
+* In-memory with WAL file: improved error handling
+* Safeguard against undefined behavior by panicking in rare illegal usage patterns that are not recoverable.
+  I.e. deleting a (write) transaction in a non-owner thread cannot be safely handled in any other way.
+
+### Examples
+
+* Make each example self-contained, you can e.g. copy an example's directory as a starting point for your own app
+* Add a convenient `build.sh` script to each example that works the same way across examples,
+  e.g. `./build.sh run` to build and run the example in one step
+* Make sources more readable (refactorings, added additional comments)
+
 4.3.1 (2025-07-28)
 ------------------
 * Cursor/Query: deleting a cursor (e.g. in a non-creator thread) waits for any query to finish 

CMakeLists.txt

@@ -1,5 +1,5 @@
-cmake_minimum_required(VERSION 3.5)
-# 3.5: Since CMake 3.27 VERSION < 3.5 produce a deprecation warning.
+cmake_minimum_required(VERSION 3.5...4.0)
+# ^ We likely require a new minimum version soon, as we do not test those ancient CMake versions anymore.
 
 # This CMake file has the following purposes:
 # * Define the ObjectBox library target (target name "objectbox"; or, if the sync variant is used, "objectbox-sync")
@@ -28,19 +28,25 @@ if (${CMAKE_VERSION} VERSION_LESS "3.11.0")
     link_directories("${CMAKE_CURRENT_SOURCE_DIR}/lib")
 else ()
     function(defineObjectBoxLibForURL VARIANT DL_URL)
+        # Fetch (download and un-archive) the ObjectBox library
         include(FetchContent)
-        project(objectbox${VARIANT}-download)
-        FetchContent_Declare(${PROJECT_NAME} URL ${DL_URL})
-
-        FetchContent_Populate(${PROJECT_NAME})
-        set(DL_DIR "${${PROJECT_NAME}_SOURCE_DIR}")
-        message(STATUS "Pre-compiled ObjectBox library is saved in ${DL_DIR}")
-
-        project(objectbox${VARIANT})
-        add_library(${PROJECT_NAME} SHARED IMPORTED GLOBAL)
+        set(_obx_download_name objectbox${VARIANT}-download)
+        # Note: FetchContent_Populate(URL ${DL_URL}) on Windows CMake 3.31 downloaded to "wrong" dir (leaving out "_deps")
+        FetchContent_Declare(${_obx_download_name} URL ${DL_URL})
+        if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.14") # FetchContent_Populate with single param is deprecated
+            FetchContent_MakeAvailable(${_obx_download_name})
+        else()
+            FetchContent_Populate(${_obx_download_name})
+        endif()
+        set(DL_DIR "${${_obx_download_name}_SOURCE_DIR}")
+        message(STATUS "ObjectBox library saved to ${DL_DIR}")
+
+        # Create the public imported target with the expected name: objectbox or objectbox-sync
+        set(_obx_public_target objectbox${VARIANT})
+        add_library(${_obx_public_target} SHARED IMPORTED GLOBAL)
         set(objectbox_include_dirs ${DL_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/external/)
         set_target_properties(
-                ${PROJECT_NAME} PROPERTIES
+                ${_obx_public_target} PROPERTIES
                 IMPORTED_LOCATION ${DL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}objectbox${CMAKE_SHARED_LIBRARY_SUFFIX}
                 IMPORTED_IMPLIB ${DL_DIR}/lib/${CMAKE_IMPORT_LIBRARY_PREFIX}objectbox${CMAKE_IMPORT_LIBRARY_SUFFIX}
                 INTERFACE_INCLUDE_DIRECTORIES "${objectbox_include_dirs}"
@@ -49,7 +55,7 @@ else ()
 
     function(defineObjectBoxLib VARIANT)
         # Configuration updated for each release
-        set(DL_VERSION 4.3.1)
+        set(DL_VERSION 5.0.0-rc)
 
         # Platform detection and other setup
         set(DL_URL https://github.com/objectbox/objectbox-c/releases/download)
@@ -108,7 +114,7 @@ else ()
     endif ()
     set(OBX_GEN_DL_URL https://raw.githubusercontent.com/objectbox/objectbox-generator/${ObjectBoxGenerator_CMAKE_VERSION}/cmake/FindObjectBoxGenerator.cmake)
 
-    if (${CMAKE_VERSION} VERSION_GREATER_EQUAL 3.18)
+    if (${CMAKE_VERSION} VERSION_GREATER_EQUAL 3.18) # 3.18 because DOWNLOAD_NO_EXTRACT
         message(STATUS "ObjectBox Generator: fetching version \"${ObjectBoxGenerator_CMAKE_VERSION}\"")
         include(FetchContent)
         FetchContent_Declare(FindObjectBoxGenerator URL ${OBX_GEN_DL_URL} DOWNLOAD_NO_EXTRACT TRUE)
@@ -140,10 +146,10 @@ else ()
 endif ()
 
 
-# If this project is top-level, include public tests and examples.
+# If this project is top-level, include public tests.
 # Otherwise, this CMake file is used from a user project, so we do not want to expose these.
 if (CMAKE_SOURCE_DIR STREQUAL PROJECT_SOURCE_DIR)
     add_subdirectory(src-test)     # target:  objectbox-c-test
     add_subdirectory(src-test-gen) # target:  objectbox-c-gen-test
-    add_subdirectory(examples)     # targets: objectbox-c-examples-tasks-{c,cpp-{auto}gen,cpp-gen-sync}
+    # Note: examples are standalone CMake projects, so we do not include them here.
 endif ()

README.md

@@ -18,7 +18,7 @@ box.put({.text = "Buy milk"});
 
 See [ObjectBox C and C++ docs](https://cpp.objectbox.io/) for API details.
 
-**Latest version: 4.3.1** (2025-07-28).
+**Latest version: 5.0.0-rc** (2025-09-30).
 See [changelog](CHANGELOG.md) for more details.
 
 ## Table of Contents:
@@ -77,20 +77,14 @@ Head over to [ObjectBox C and C++ installation docs](https://cpp.objectbox.io/in
 
 C++ API
 -------
-The C++ API is built on top of the C API exposed by the library (e.g. you still need objectbox.h).
-You can also use both APIs from your code if necessary.
-For example, you use the C++ `obx::Box` class for most database operations, but "break out" into the C API for a special function you need.  
+The C++ API provides a higher level `class`-based interface built on top of the C API.
+A central class is `obx::Box`, which provides most database operations. 
 Note that to use the `obx::Box` class, you also need the [ObjectBox Generator](https://github.com/objectbox/objectbox-generator) to generate binding code.
 Find more details how to use it the [Getting started](https://cpp.objectbox.io/getting-started) section of the docs.
 
 Examples
 --------
-Have a look at the following TaskList example apps, depending on your programming language and preference:
-
-* [C, cursor, no generated code](examples/c-cursor-no-gen) - plain C; using flatcc directly; without any generated code
-* [C, with generated code](examples/c-gen) - plain C, using code generated by `objectbox-generator`
-* [C++, with generated code](examples/cpp-gen) - C++, using code generated by `objectbox-generator`
-  * also includes sync client application example
+Check the [examples](examples) directory for self-contained examples that show how to use the C and C++ APIs.
 
 Documentation
 -------------

download.sh

@@ -44,7 +44,7 @@ tty -s || quiet=true
 
 # Note: optional arguments like "--quiet" shifts argument positions in the case block above
 
-version=${1:-4.3.1}
+version=${1:-5.0.0-rc}
 os=${2:-$(uname)}
 arch=${3:-$(uname -m)}
 echo "Base config: OS ${os} and architecture ${arch}"

doxygen/Changelog.md

@@ -3,6 +3,29 @@
 ObjectBox C and C++ API Changelog
 =================================
 
+5.0.0-rc (2025-09-30)
+------------------
+
+### User-Specific Data Sync
+
+* Sync filters: define server-side filter expression to sync individual data for each sync user.
+  This is also known as "user-specific data sync" and requires Sync clients version 5.0.
+* Client variables: clients may define key/value pairs that can be used in sync filters
+
+### Fixes
+
+* Fixed clearing 1:N backlinks for IDs larger than 32-bit (setting backlink ID to 0 on the "1" side)
+* In-memory with WAL file: improved error handling
+* Safeguard against undefined behavior by panicking in rare illegal usage patterns that are not recoverable.
+  I.e. deleting a (write) transaction in a non-owner thread cannot be safely handled in any other way.
+
+### Examples
+
+* Make each example self-contained, you can e.g. copy an example's directory as a starting point for your own app
+* Add a convenient `build.sh` script to each example that works the same way across examples,
+  e.g. `./build.sh run` to build and run the example in one step
+* Make sources more readable (refactorings, added additional comments)
+
 4.3.1 (2025-07-28)
 ------------------
 * Cursor/Query: deleting a cursor (e.g. in a non-creator thread) waits for any query to finish 

doxygen/Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "ObjectBox C and C++ API"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "4.3.1"
+PROJECT_NUMBER         = "5.0.0-rc"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

examples/README.md

@@ -0,0 +1,75 @@
+ObjectBox C and C++ examples
+============================
+
+These are examples for ObjectBox C and C++.
+
+Each example is self-contained in its own subdirectory and can be built using CMake.
+For convenience, a `build.sh` script is provided in each example directory,
+which puts all build files into a separate directory ("build/").
+See the [build and run](#build-and-run) section below for details.
+
+## Tasks Examples
+
+There are four examples console applications that implement a simple task list.
+Tasks can be added, viewed, and marked as finished to demonstrate typical ObjectBox database operations.
+
+The examples for C++ are:
+
+- `tasks`: C++ application
+- `tasks-sync`: C++ application with sync enabled (requires a ObjectBox Sync server)
+
+The examples for C are:
+
+- `c-tasks`: C application
+- `c-tasks-lowlevel`: C application, but with lesser used lower-level APIs; not the best to start with
+
+## Vector Search Example
+
+There's a C++ example for vector search in the [vectorsearch-cities](vectorsearch-cities/README.md) directory.
+
+## Build and run
+
+Prerequisites are CMake 3.14+ and a C/C++ compiler.
+All examples follow the same setup, and thus we document it only once here.
+
+### Build with the provided shell script
+
+This is the simplest way on Linux and macOS from the command line.
+
+* Typically, you `cd` into an example directory and run `./build.sh` (each example has its own `build.sh`).
+* Once the build is done, you can run the example: the executable is in the `build/` directory and its path is printed to the console during the build.
+* Run `./build.sh run` to build and run the example in one step.
+* The `./build.sh` also accepts `--clear` as the first argument to clear the build directory before building.
+
+### Build within IDEs (CMake)
+
+If you work with a IDE, you can typically just open each example as a CMake project.
+The IDE will setup everything for you.
+
+### Build with CMake
+
+If you prefer to use CMake directly (e.g. on a Windows terminal), you can do so as follows:
+
+```
+cmake -S . -B build
+cmake --build build
+```
+
+And then run the built executable:
+
+```
+build/objectbox-examples-... # replace ... with the example name
+```
+
+## Next steps
+
+If you want, you can copy an example as a starting point for your own project.
+Pick the directory of the example that fits best for your needs.
+
+Links and documentation:
+
+* [ObjectBox homepage](https://objectbox.io/)
+* [ObjectBox C and C++ docs](https://cpp.objectbox.io/)
+* [ObjectBox Sync docs](https://sync.objectbox.io/)
+* [ObjectBox vector search docs](https://docs.objectbox.io/on-device-vector-search)
+