persistency/examples: Provide a integration example

examples/.bazelrc

@@ -0,0 +1,32 @@
+# *******************************************************************************
+# Copyright (c) 2025 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+
+# Links to S-CORE Bazel registry and Bazel Central Registry
+common --registry=https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/
+common --registry=https://bcr.bazel.build
+
+#common --credential_helper=*.qnx.com=/<full>/bazel_cpp_toolchains/tools/qnx_credential_helper.py
+
+build:x86_64-gcc --host_platform=@score_bazel_platforms//:x86_64-linux-gcc_12.2.0-posix
+build:x86_64-gcc --extra_toolchains=@score_gcc_x86_64//:x86_64-linux-gcc_12.2.0
+build:x86_64-gcc --host_features=use_pthread
+
+build:x86_64-qcc --platforms=@score_bazel_platforms//:x86_64-qnx-sdp_8.0.0-posix
+build:x86_64-qcc --extra_toolchains=@score_qcc_x86_64//:x86_64-qnx-sdp_8.0.0
+
+build:aarch64-qcc --platforms=@score_bazel_platforms//:aarch64-qnx-sdp_8.0.0-posix
+build:aarch64-qcc --extra_toolchains=@score_qcc_aarch64//:aarch64-qnx-sdp_8.0.0
+
+build --@score_baselibs//score/json:base_library=nlohmann
+
+try-import %workspace%/user.bazelrc

examples/.bazelversion

@@ -0,0 +1 @@
+8.4.2

examples/MODULE.bazel

@@ -0,0 +1,63 @@
+# *******************************************************************************
+# Copyright (c) 2025 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+module(
+    name = "score_per_example",
+    version = "0.0.1",
+    compatibility_level = 0,
+)
+
+bazel_dep(name = "rules_cc", version = "0.2.17")
+bazel_dep(name = "score_bazel_platforms", version = "0.1.1")
+bazel_dep(name = "score_bazel_cpp_toolchains", version = "0.3.0")
+
+gcc = use_extension("@score_bazel_cpp_toolchains//extensions:gcc.bzl", "gcc", dev_dependency = True)
+gcc.toolchain(
+    name = "score_gcc_x86_64",
+    target_cpu = "x86_64",
+    target_os = "linux",
+    use_default_package = True,
+    version = "12.2.0",
+)
+gcc.toolchain(
+    name = "score_qcc_x86_64",
+    sdp_version = "8.0.0",
+    target_cpu = "x86_64",
+    target_os = "qnx",
+    use_default_package = True,
+    version = "12.2.0",
+)
+gcc.toolchain(
+    name = "score_qcc_aarch64",
+    sdp_version = "8.0.0",
+    target_cpu = "aarch64",
+    target_os = "qnx",
+    use_default_package = True,
+    version = "12.2.0",
+)
+use_repo(
+    gcc,
+    "score_gcc_x86_64",
+    "score_qcc_aarch64",
+    "score_qcc_x86_64",
+)
+
+bazel_dep(name = "score_persistency", version = "0.3.0")
+
+# only in the intern examle to test the latest local version instead of the latest released one
+local_path_override(
+    module_name = "score_persistency",
+    path = "../",
+)
+
+# inherited deps
+bazel_dep(name = "score_baselibs", version = "0.2.4")

examples/README.md

@@ -1,122 +1,94 @@
 
 # Getting Started with Key-Value-Storage (persistency)
 
-This guide will help you get started with the C++ and Rust implementations of the Key-Value-Storage (KVS) library, including how to use it and link it with Bazel.
+This guide demonstrates how to use the Key-Value-Storage (KVS) library in a standalone Bazel workspace. The example module shows how to integrate `score_persistency` with modern C++ toolchains and build a simple KVS application.
 
-## 1. Integrating with Bazel
+## 1. About this Example Module
 
-### 1.1 Add this to your MODULE.bazel:
-<details>
-  <summary>MODULE.bazel</summary>
+This example workspace demonstrates a minimal setup for using the `score_persistency` library. It's configured as a standalone Bazel module with the following features:
 
-    module(name = "your_project_name")
+### Module Structure
+- **MODULE.bazel**: Defines dependencies and toolchain configuration
+- **.bazelrc**: Contains build configurations for different target platforms
+- **src/main.cpp**: Simple example application using the KVS C++ API
+- **src/BUILD**: Bazel build target for the example
 
-    # Add the persistency dependency (replace version as needed)
-    bazel_dep(name = "persistency", version = "0.2.0")
+### Supported Toolchains
+The example is configured to build with three different toolchains:
+- **x86_64-gcc**: GCC for Linux x86_64 (POSIX)
+- **x86_64-qcc**: QNX compiler for x86_64
+- **aarch64-qcc**: QNX compiler for ARM64/AArch64
 
-    # Add required toolchains and dependencies for C++ and Rust
-    bazel_dep(name = "score_toolchains_gcc", version = "0.4", dev_dependency=True)
-    gcc = use_extension("@score_toolchains_gcc//extentions:gcc.bzl", "gcc", dev_dependency=True)
-    gcc.toolchain(
-        url = "https://github.com/eclipse-score/toolchains_gcc_packages/releases/download/0.0.1/x86_64-unknown-linux-gnu_gcc12.tar.gz",
-        sha256 = "457f5f20f57528033cb840d708b507050d711ae93e009388847e113b11bf3600",
-        strip_prefix = "x86_64-unknown-linux-gnu",
-    )
-    use_repo(gcc, "gcc_toolchain", "gcc_toolchain_gcc")
+## 2. Bazel Configuration Explained
 
-    bazel_dep(name = "rules_rust", version = "0.61.0")
-    crate = use_extension("@rules_rust//crate_universe:extensions.bzl", "crate")
-    crate.from_specs(name = "crate_index")
-    use_repo(crate, "crate_index")
+### 2.1 Module Dependencies (MODULE.bazel)
 
-    # Add any other dependencies required by persistency (see persistency's own MODULE.bazel for details)
+The [MODULE.bazel](MODULE.bazel) file defines the workspace and its dependencies:
 
-</details>
+**Core Dependencies:**
+- `rules_cc`: C++ build rules
+- `score_bazel_platforms`: Platform definitions for different OS/CPU combinations
+- `score_bazel_cpp_toolchains`: GCC and QCC toolchain support
+- `score_persistency`: The KVS library itself
+- `score_baselibs`: Common utilities and result types
 
-### 1.2 Insert this into your .bazelrc:
-<details>
-  <summary>.bazelrc</summary>
+*See [MODULE.bazel](MODULE.bazel) for specific versions currently in use.*
 
-  ```
-  build --@score_baselibs//score/json:base_library=nlohmann
-  build --@score_baselibs//score/mw/log/flags:KRemote_Logging=False
+**Toolchain Configuration:**
+The module uses the `gcc` extension from `score_bazel_cpp_toolchains` to configure three toolchains with automatic package downloading enabled (`use_default_package = True`). This means the toolchain packages are downloaded automatically during the build.
 
-  ```
-</details>
+**Local Override:**
+The example uses `local_path_override` to reference the parent persistency directory, allowing testing against the latest local version instead of a published release.
 
-### 1.3 Run Bazel
-If you start with a plain project add an empty file called `BUILD` into your project folder.
+### 2.2 Build Configuration (.bazelrc)
 
-Now you can build the project with the command:
-```sh
-bazel build //...
-```
-(So far nothing happens, because no targets were defined.)
-
-You can now continue in this guide to create a simple consumer-producer program or start on your own.
+The [.bazelrc](.bazelrc) file configures how Bazel builds for different platforms:
 
+**Registry Configuration:**
+Specifies the S-CORE Bazel registry and Bazel Central Registry for downloading dependencies.
 
+**Build Configurations:**
+- **x86_64-gcc**: Linux x86_64 target with GCC, includes pthread support
+- **x86_64-qcc**: QNX x86_64 target with QCC
+- **aarch64-qcc**: QNX ARM64 target with QCC
 
-## 2. Using the C++ Implementation
+**Common Build Flags:**
+- Uses nlohmann JSON library via `score_baselibs`
+- Disables remote logging for the KVS logger
 
-### 2.1 Basic Usage
+### 2.3 Build Target (src/BUILD)
 
-The C++ API is centered around `KvsBuilder` and `Kvs` classes. Here is a minimal example based on the test scenarios:
+The [src/BUILD](src/BUILD) file defines a simple binary target:
+- **Name**: `hello_kvs_world`
+- **Source**: `main.cpp`
+- **Dependencies**: `@score_persistency//:kvs_cpp`
 
-```cpp
-#include "kvsbuilder.hpp"
-#include <iostream>
+The target is minimal and focused on demonstrating basic KVS usage.
 
-int main() {
-  // Use fully qualified names instead of 'using namespace'
-  auto open_res = score::mw::per::kvs::KvsBuilder(score::mw::per::kvs::InstanceId(0))
-            .need_defaults_flag(true)
-            .need_kvs_flag(false)
-            .dir(".")
-            .build();
-  if (!open_res) {
-    std::cerr << "Failed to open KVS: " << static_cast<int>(open_res.error()) << std::endl;
-    return 1;
-  }
-  score::mw::per::kvs::Kvs kvs = std::move(open_res.value());
+## 3. Using the C++ Implementation
 
-  // Set a key-value pair
-  kvs.set_value("username", score::mw::per::kvs::KvsValue("alice"));
+### 3.1 Example Application
 
-  // Read a value (will fall back to default if not set)
-  score::mw::per::kvs::Result<score::mw::per::kvs::KvsValue> get_res = kvs.get_value("username");
-  if (get_res) {
-    std::cout << "username: " << get_res.value().as_string() << std::endl;
-  }
+The [src/main.cpp](src/main.cpp) demonstrates basic KVS operations:
 
-  // Read a default value (not set, but present in defaults)
-  auto get_default = kvs.get_value("language");
-  if (get_default) {
-    std::cout << "language (default): " << get_default.value().as_string() << std::endl;
-  }
+- Building the KVS instance
+- Show some key operations
+- Error handling
 
-  // Check if a key exists (only if written)
-  if (kvs.key_exists("username").value_or(false)) {
-    std::cout << "username exists!" << std::endl;
-  }
+### 3.2 Building the Example
 
-  // Remove a key
-  kvs.remove_key("username");
+To build for different platforms:
 
-  // List all keys (only written keys, not defaults)
-  auto keys_res = kvs.get_all_keys();
-  if (keys_res) {
-    std::cout << "All keys in KVS:" << std::endl;
-    for (const auto& key : keys_res.value()) {
-      std::cout << "  " << key << std::endl;
-    }
-  }
+```sh
+# within the examples folder (not the top level persistency folder)
+# Linux x86_64 with GCC
+bazel build --config=x86_64-gcc //src:hello_kvs_world
 
-  // Flush changes to disk
-  kvs.flush();
+# QNX x86_64
+bazel build --config=x86_64-qcc //src:hello_kvs_world
 
-  return 0;
-}
+# QNX ARM64
+bazel build --config=aarch64-qcc //src:hello_kvs_world
 ```
 
 ## 3. Using the Rust Implementation

examples/src/BUILD

@@ -0,0 +1,22 @@
+# *******************************************************************************
+# Copyright (c) 2026 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+load("@rules_cc//cc:defs.bzl", "cc_binary")
+
+cc_binary(
+    name = "hello_kvs_world",
+    srcs = ["main.cpp"],
+    deps = [
+        "@score_baselibs//score/mw/log:console_only_backend",
+        "@score_persistency//:kvs_cpp",
+    ],
+)

examples/src/main.cpp

@@ -0,0 +1,40 @@
+/********************************************************************************
+ * Copyright (c) 2026 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ********************************************************************************/
+#include <iostream>
+#include <kvsbuilder.hpp>
+
+int main() {
+    std::cout << "Hello, score_persistency world!" << std::endl;
+
+    auto open_res = score::mw::per::kvs::KvsBuilder(score::mw::per::kvs::InstanceId(0))
+        .need_defaults_flag(false)
+        .need_kvs_flag(false)
+        .dir(".")
+        .build();
+
+    if (!open_res) {
+        std::cerr << "Failed to open KVS: " << open_res.error() << std::endl;
+        return 1;
+    }
+    score::mw::per::kvs::Kvs kvs = std::move(open_res.value());
+
+    // Set a key-value pair
+    kvs.set_value("username", score::mw::per::kvs::KvsValue("alice"));
+
+    // Read a value
+    score::Result<score::mw::per::kvs::KvsValue> get_res = kvs.get_value("username");
+    if (get_res) {
+        std::cout << "username: " << std::get<std::string>(get_res.value().getValue()) << std::endl;
+    }
+    return 0;
+}