C++ Core

cpp-core is the header-only API and ABI contract shared by the Serial-IO platform bindings. It defines the exported serial interface, the status-code model, and build-time version information consumed by the platform implementations.

This repository does not provide a ready-to-load shared library by itself. It provides the contract consumed by the platform implementations:

• cpp-bindings-linux
• cpp-bindings-windows

Status

cpp-core is the canonical definition of the current API line.

• Current baseline compiler: GCC 16.1+
• Reflection model: GCC std::meta with -freflection
• Supported Linux toolchain: GCC 16.1+ in C++26 mode
• Supported Windows toolchain: MinGW 16.1+ in C++26 mode
• macOS support: not ready yet
• Required language mode: C++26
• Required build system: CMake 3.30+

What It Provides

• Header-only C++ API definitions with unmangled C linkage under include/cpp_core
• Modern C++26 helper surface for std::expected-based error propagation, strong typed config values, and compile-time reflection helpers
• A generated version surface used consistently across all platform bindings
• An installable CMake package target: cpp_core::cpp_core

Repository Layout

• include/cpp_core/serial.h: aggregated C ABI for serial operations
• include/cpp_core/status_code.h: shared status-code model
• include/cpp_core/interface/meta.h: metadata struct and exported meta function

Quick Start

Consume cpp-core as a CMake dependency from another project:

CPMAddPackage(
  NAME cpp_core
  GITHUB_REPOSITORY Serial-IO/cpp-core
  GIT_TAG vX.Y.Z
)

target_link_libraries(my_binding PRIVATE cpp_core::cpp_core)

Use the exported headers in your implementation:

#include <cpp_core/serial.h>
#include <cpp_core/interface/meta.h>

auto serialOpen(
    const char *port,
    const cpp_core::SerialConfig *config,
    ErrorCallbackT error_callback
) -> intptr_t;

Read the version data baked into the checkout:

#include <cpp_core/interface/meta.h>

cpp_core::Meta metadata{};
meta(&metadata);

Building This Repository

Native build:

cmake -S . -B build -G Ninja
cmake --build build
ctest --test-dir build

The CMake project exports the package target and also builds these relevant targets:

• cpp_core::cpp_core: header-only interface target
• cpp_core_compile_tests: compile-time validation target when testing is enabled

ABI Surface

The main aggregated interface lives in:

#include <cpp_core/serial.h>

The API requires a C++ compiler, while exported functions use unmangled C linkage through MODULE_API. Functions either return a status code, return a value-or-negative-status, or return an opaque handle-or-negative-status.

Example:

MODULE_API auto serialOpen(
    const char *port,
    const cpp_core::SerialConfig *config,
    ErrorCallbackT error_callback = nullptr
) -> intptr_t;

Line settings and per-operation timeout settings use explicit configuration structures. flow_mode is applied as part of serialOpen together with the other line settings:

constexpr auto serial_config = cpp_core::SerialConfig::make<
    115'200,
    cpp_core::DataBits::kEight,
    cpp_core::Parity::kNone,
    cpp_core::StopBits::kOne,
    cpp_core::FlowControl::kRtsCts>();
constexpr auto timeout_config = cpp_core::SerialTimeoutConfig::make<50, 1>();

const auto handle = serialOpen(port, &serial_config);
const auto bytes_read = serialRead(handle, buffer, buffer_size, &timeout_config);

This model keeps the ABI easy to consume from TypeScript hosts, Rust, Python, or other FFI hosts without requiring C++ runtime coupling.

For C++ callers, the helper surface includes:

• include/cpp_core/result.hpp: Result<T>, Status, forwardUnexpected(...), plus the native std::expected monadic operations
• include/cpp_core/scope_guard.hpp: onScopeExit(...), onScopeFail(...), onScopeSuccess(...), defer(...)
• include/cpp_core/strong_types.hpp: arithmetic-preserving strong integral wrappers and enum conversion helpers
• include/cpp_core/serial_config.hpp: typed line and timeout config construction with validation helpers
• include/cpp_core/reflection.hpp: GCC 16 / C++26 reflection helpers such as enum/member counts and names, plus public field counts and names

Versioning

Version information is generated from Git during CMake configure and written into include/cpp_core/version.hpp.

• Tagged checkout: uses the tag as the base version
• Additional commits after a tag: appends the commit distance and short hash
• Dirty working tree: appends -dirty
• No usable tag: falls back to 0.0.0

The version data is exposed through:

• the version namespace in include/cpp_core/version.hpp
• the cpp_core::Meta struct
• the exported meta(cpp_core::Meta *out) ABI function

Relationship to Platform Repositories

cpp-core defines the contract. The platform repositories implement it.

• cpp-bindings-linux provides the Linux shared library implementation
• cpp-bindings-windows provides the Windows DLL implementation
• macOS bindings are not part of the supported line yet

Keeping the contract and version surface here avoids ABI drift between platforms and keeps the shared API aligned with the actual exported implementation.

License

Licensed under Apache-2.0. See LICENSE.