From ba7f5bc797c6cfe35bfb504cc9400215b87359d1 Mon Sep 17 00:00:00 2001 From: Uwe Maucher <205777204+umaucher@users.noreply.github.com> Date: Fri, 20 Feb 2026 14:54:13 +0100 Subject: [PATCH 1/2] persistency/examples: Provide a integration example Show how to integrate score_persistency in a own standalone bazel workspace and showing the usage of the C++ implementation. Remove the previous pseudo code from the README.md and document the new solution instead. --- examples/.bazelrc | 32 +++++++++ examples/.bazelversion | 1 + examples/MODULE.bazel | 63 ++++++++++++++++++ examples/README.md | 148 +++++++++++++++++------------------------ examples/src/BUILD | 10 +++ examples/src/main.cpp | 28 ++++++++ 6 files changed, 194 insertions(+), 88 deletions(-) create mode 100644 examples/.bazelrc create mode 100644 examples/.bazelversion create mode 100644 examples/MODULE.bazel create mode 100644 examples/src/BUILD create mode 100644 examples/src/main.cpp diff --git a/examples/.bazelrc b/examples/.bazelrc new file mode 100644 index 00000000..4639e1c2 --- /dev/null +++ b/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=//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 diff --git a/examples/.bazelversion b/examples/.bazelversion new file mode 100644 index 00000000..e7fdef7e --- /dev/null +++ b/examples/.bazelversion @@ -0,0 +1 @@ +8.4.2 diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel new file mode 100644 index 00000000..d9de8436 --- /dev/null +++ b/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", + version = "12.2.0", + use_default_package = True, +) + +gcc.toolchain( + name = "score_qcc_x86_64", + target_cpu = "x86_64", + target_os = "qnx", + sdp_version = "8.0.0", + version = "12.2.0", + use_default_package = True, +) + +gcc.toolchain( + name = "score_qcc_aarch64", + target_cpu = "aarch64", + target_os = "qnx", + sdp_version = "8.0.0", + version = "12.2.0", + use_default_package = True, +) + +use_repo( + gcc, + "score_gcc_x86_64", + "score_qcc_x86_64", + "score_qcc_aarch64", +) + +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") diff --git a/examples/README.md b/examples/README.md index 4c117959..f1c480e3 100644 --- a/examples/README.md +++ b/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: -
- MODULE.bazel +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: -
+**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: -
- .bazelrc +*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. - ``` -
+**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 +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(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 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 diff --git a/examples/src/BUILD b/examples/src/BUILD new file mode 100644 index 00000000..de37ce22 --- /dev/null +++ b/examples/src/BUILD @@ -0,0 +1,10 @@ +load("@rules_cc//cc:defs.bzl", "cc_binary") + +cc_binary( + name = "hello_kvs_world", + srcs = ["main.cpp"], + deps = [ + "@score_persistency//:kvs_cpp", + "@score_baselibs//score/mw/log:console_only_backend", + ], +) diff --git a/examples/src/main.cpp b/examples/src/main.cpp new file mode 100644 index 00000000..1947901c --- /dev/null +++ b/examples/src/main.cpp @@ -0,0 +1,28 @@ +#include +#include + +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 get_res = kvs.get_value("username"); + if (get_res) { + std::cout << "username: " << std::get(get_res.value().getValue()) << std::endl; + } + return 0; +} From 28a44633daf2aa01a038636c3156b4c236fa14ee Mon Sep 17 00:00:00 2001 From: Uwe Maucher <205777204+umaucher@users.noreply.github.com> Date: Fri, 20 Feb 2026 17:12:27 +0100 Subject: [PATCH 2/2] persistency/examples: Copyright and formatting fix --- examples/MODULE.bazel | 22 +++++++++++----------- examples/src/BUILD | 14 +++++++++++++- examples/src/main.cpp | 12 ++++++++++++ 3 files changed, 36 insertions(+), 12 deletions(-) diff --git a/examples/MODULE.bazel b/examples/MODULE.bazel index d9de8436..a5d7b019 100644 --- a/examples/MODULE.bazel +++ b/examples/MODULE.bazel @@ -21,43 +21,43 @@ 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", - version = "12.2.0", 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", - sdp_version = "8.0.0", - version = "12.2.0", 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", - sdp_version = "8.0.0", - version = "12.2.0", use_default_package = True, + version = "12.2.0", ) - use_repo( gcc, "score_gcc_x86_64", - "score_qcc_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 = "../") +local_path_override( + module_name = "score_persistency", + path = "../", +) # inherited deps bazel_dep(name = "score_baselibs", version = "0.2.4") diff --git a/examples/src/BUILD b/examples/src/BUILD index de37ce22..ca2f58cf 100644 --- a/examples/src/BUILD +++ b/examples/src/BUILD @@ -1,10 +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_persistency//:kvs_cpp", "@score_baselibs//score/mw/log:console_only_backend", + "@score_persistency//:kvs_cpp", ], ) diff --git a/examples/src/main.cpp b/examples/src/main.cpp index 1947901c..90eca3d0 100644 --- a/examples/src/main.cpp +++ b/examples/src/main.cpp @@ -1,3 +1,15 @@ +/******************************************************************************** + * 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 #include