jstore: initial commit

JSON configuration and state serialization and introspection library.

.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        os: [ubuntu-latest]
+        build_type: [Release, Debug]
+        compiler: [g++] # 'clang' temporarily disabled as github actions uses clang 14, which has an out-of-date interpretation of C++20 standard and errors out.
+        dbus_support: [OFF, ON]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set reusable strings
+      # Turn repeated input strings (such as the build output directory) into step outputs. These step outputs can be used throughout the workflow file.
+      id: strings
+      shell: bash
+      run: echo "build-output-dir=${{ github.workspace }}/build" >> "$GITHUB_OUTPUT"
+
+    - name: Install libsystemd dependencies
+      if: matrix.dbus_support == 'ON'
+      run: |
+        sudo apt update -y
+        sudo apt install -y meson ninja-build libcap-dev libmount-dev m4 gperf
+
+    - name: Configure CMake
+      # Configure CMake in a 'build' subdirectory.
+      run: >
+        cmake
+        -B ${{ steps.strings.outputs.build-output-dir }}
+        -S ${{ github.workspace }}
+        -DCMAKE_CXX_COMPILER=${{ matrix.compiler }}
+        -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+        -DCMAKE_CXX_STANDARD=20
+        -DJSTORE_BUILD_JSON=ON
+        -DJSTORE_BUILD_DBUS=ON
+        -DJSTORE_BUILD_TESTS=ON
+        -DJSTORE_BUILD_EXAMPLES=ON
+        -DJSTORE_BUILD_EXAMPLES=ON
+        -DJSTORE_ENABLE_DBUS=${{ matrix.dbus_support }}
+
+    - name: Build
+      # Note that --config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
+      run: cmake --build ${{ steps.strings.outputs.build-output-dir }} --config ${{ matrix.build_type }}
+
+    - name: Test
+      working-directory: ${{ steps.strings.outputs.build-output-dir }}
+      # Note that --build-config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
+      run: dbus-run-session ctest --output-on-failure --build-config ${{ matrix.build_type }}

.gitignore

@@ -0,0 +1,32 @@
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app

CMakeLists.txt

@@ -0,0 +1,71 @@
+# -------------------------------
+# JSON Configuration Storage library
+# -------------------------------
+
+cmake_minimum_required(VERSION 3.16)
+project(
+    jstore
+    VERSION 1.0.0
+    LANGUAGES CXX
+)
+
+# -------------------------------
+# Project Options
+# -------------------------------
+
+option(JSTORE_BUILD_JSON "Fetch the nlohmann_json library, instead of searching for it in the system" OFF)
+option(JSTORE_BUILD_DBUS "Fetch the sdbus-c++ library, instead of searching for it in the system" OFF)
+option(JSTORE_BUILD_TESTS "Build tests" OFF)
+option(JSTORE_BUILD_EXAMPLES "Build examples" OFF)
+option(JSTORE_ENABLE_DBUS "Enable remote access to the data model via D-Bus (sdbus-c++ library)" OFF)
+
+# -------------------------------
+# Setup Compiler
+# -------------------------------
+
+# Set compiler options
+if(NOT DEFINED CMAKE_CXX_STANDARD)
+    set(CMAKE_CXX_STANDARD 20)
+endif()
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# -------------------------------
+# Resolve library dependencies
+# -------------------------------
+
+add_subdirectory(thirdparty)
+
+# -------------------------------
+# Build Library
+# -------------------------------
+
+add_library(jstore INTERFACE)
+target_compile_features(jstore INTERFACE cxx_std_20)
+target_include_directories(jstore INTERFACE include)
+target_link_libraries(jstore INTERFACE nlohmann_json::nlohmann_json fmt::fmt visit_struct::visit_struct)
+
+# Optional D-Bus integration using sdbus-c++ library
+if(JSTORE_ENABLE_DBUS)
+    target_compile_definitions(jstore INTERFACE JSTORE_SDBUSCPP=1)
+    target_link_libraries(jstore INTERFACE SDBusCpp::sdbus-c++)
+else()
+    target_compile_definitions(jstore INTERFACE JSTORE_SDBUSCPP=0)
+endif()
+
+# -------------------------------
+# Build Unit Tests
+# -------------------------------
+
+if(JSTORE_BUILD_TESTS)
+    message(STATUS "jstore: building with tests")
+    enable_testing()
+    add_subdirectory(tests)
+endif()
+
+# -------------------------------
+# Build Examples
+# -------------------------------
+
+if(JSTORE_BUILD_EXAMPLES)
+    # add_subdirectory(examples)
+endif()

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 David Leeds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,11 @@
+# jstore
+
+[![CI](https://github.com/DavidLeeds/jstore/actions/workflows/ci.yml/badge.svg)](https://github.com/DavidLeeds/jstore/actions/workflows/ci.yml)
+
+`jstore` is a header-only library written in modern C++ that allows application configuration and state in C++ classes and structures to be persisted to flash and exported via RPC. In addition to the `jstore::tree<T>` class that wraps application-defined state, the library exposes a tool-kit of library functions for serialization and path-based traversal of the tree.
+
+## Design Philosophy
+
+* **Minimize impact to the application.** While the `jstore::tree<T>` class wraps application state, state is represented using native C++ data types and may be directly accessed by the application. This contrasts with traditional databases or configuration stores where glue code must be written to load and store every piece of state. In most cases, applications pass references to their state structures with no knowledge that persistence and export is being managed by `jstore`.
+* **Infinite potential for extension.** For simplicity and broad compatibility with existing code-bases, `jstore` uses the wildly popular [nlohmann/json](https://github.com/nlohmann/json) library for serialization and deserialization. This library has built-in support for most common STL data types, and allows applications to define their own `from_json()` and `to_json()` ADL serializers for any data type. While JSON is not the most compact serialization format, it maps well to most data models, is human-readable, and is approachable by a broad audience. Compression of on-disk data is on the to-do list.
+* **Leverage data type reflection.** While proposals have been circulated for built-in static reflection in the C++ '26 language standard, we can be assured that it will a number of years until it is available to the average application. Until then, we can take our pick from several open-source libraries that utilize preprocessor macros to provide compile-time reflection of classes and structs. While the macro solution is admittedly ugly, the benefits appear to outweigh the aesthetic shortcomings. I selected the feature-rich and stable [cbeck88/visit_struct](https://github.com/cbeck88/visit_struct) library for this purpose. `visit_struct` allows us to iterate over members of arbitrary classes, which is a core piece of `jstore`'s serialization and path-based-traversal strategy.

dbus/JStore.xml

@@ -0,0 +1,27 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+
+<node>
+
+    <interface name="io.davidleeds.JStore">
+        <method name="Get">
+            <arg type="s" name="Path" direction="in" />
+            <arg type="s" name="ValueJson" direction="out" />
+        </method>
+
+        <method name="GetAll">
+            <!-- dict{path, JSON encoded value} -->
+            <arg type="a{ss}" name="ValuesJson" direction="out" />
+        </method>
+
+        <method name="Set">
+            <arg type="s" name="Path" direction="in" />
+            <arg type="s" name="ValueJson" direction="in" />
+        </method>
+
+        <signal name="ValuesChanged">
+            <arg type="a{ss}" name="Values" />
+        </signal>
+    </interface>
+
+</node>