The C++ Field Manual
write it clean, build it anywhere, ship it hard.

target_compile_features(mylib PUBLIC cxx_std_20)
set_target_properties(mylib PROPERTIES
    CXX_STANDARD_REQUIRED ON   # hard error if std unsupported
    CXX_EXTENSIONS        OFF) # -std=c++20, not gnu++20 (portable)

#pragma once
#include <cstdint>
#include <span>
#include <system_error>

namespace mbus {

class Transport;               // fwd-decl: no transport header pulled in

class ModbusClient {
public:
    explicit ModbusClient(Transport& t) noexcept;

    // std::expected in C++23; error code out-param or Result<T> pre-23
    std::error_code read_holding(std::uint16_t addr,
                                 std::span<std::uint16_t> out) noexcept;
private:
    Transport& transport_;
};

} // namespace mbus

#include <cstdint>
std::uint16_t reg;      // exactly 16 bits, unsigned   (a Modbus register)
std::int32_t  temp_mC;  // exactly 32 bits, signed     (milli-degrees C)
std::uint8_t  fc;       // exactly 8 bits              (a function code)

std::size_t    n;       // unsigned: sizeof, indexing, container .size()
std::ptrdiff_t d;       // signed:   result of pointer subtraction
std::uintptr_t a;       // an unsigned integer wide enough to hold a pointer

// literals
auto a    = 1'000'000;      // ' is a digit separator (C++14)
auto mask = 0b0000'1111;    // binary literal (C++14)
auto addr = 0x40'00u;       // hex, unsigned suffix
auto hz   = 3.3e6;          // double  (3.3e6f would be float)
using namespace std::chrono_literals;
auto t    = 500ms;          // typed literal -> std::chrono::milliseconds

// initialization — prefer braces
int    x{42};               // direct-list-init; NARROWING IS AN ERROR here
int    z{};                 // value-init -> 0  (never leaves garbage)
double d = 3.9;
// int bad{d};              // won't compile: narrowing double->int is caught
int    ok = d;              // compiles, silently truncates to 3

#include <string>
#include <string_view>

std::string s = "modbus/tcp";
s.size();  s.empty();                    // 10, false
s += ":502";                             // append  -> "modbus/tcp:502"
auto pos  = s.find(':');                 // 10   (std::string::npos if absent)
auto host = s.substr(0, pos);            // "modbus/tcp"
s.replace(0, 6, "MODBUS");               // in-place edit
bool ok = s.starts_with("MODBUS");       // C++20  (ends_with; contains is C++23)
const char* c = s.c_str();               // NUL-terminated, for C APIs

#include <charconv>
int v{};
auto [ptr, ec] = std::from_chars(s.data(), s.data() + s.size(), v);  // no throw, no alloc
if (ec == std::errc{}) use(v);

std::string t = std::to_string(42);      // convenient, allocates
int n = std::stoi("123");                // convenient, THROWS on bad input

#include <format>                          // <print> for std::print (C++23)
std::string line = std::format("reg[{}]={:#06x}", i, value);  // "reg[3]=0x00ff"
// std::print("connected {}:{}\n", host, port);

int x = 42;
int* p = &x;        // p holds the address of x
*p = 43;            // dereference: x is now 43
p = nullptr;        // use nullptr, never NULL or literal 0

int& r = x;         // r is another name for x: no storage, cannot rebind
r = 44;             // x is now 44

void legacy(const std::uint8_t* buf, std::size_t len);   // C-style: size passed separately
void modern(std::span<const std::uint8_t> buf);          // span carries .size() itself

std::array<std::uint8_t, 8> frame{};
modern(frame);                                           // span deduces the size

std::uint16_t crc16(std::span<const std::byte>) noexcept;
using CrcFn = std::uint16_t(*)(std::span<const std::byte>);  // a function-pointer type
CrcFn fp = &crc16;

std::function<void(std::string_view)> on_msg;   // holds ANY matching callable
on_msg = [prefix](std::string_view topic){ /* capture + logic */ };

void poll(const Config& cfg,             // read-only, no copy
          Stats&        out,             // written back to the caller
          Logger*       log = nullptr);  // optional; default argument (binds right-to-left)

// Overloading: same name, different PARAMETER types (return type alone can't overload).
Reading parse(std::span<const std::byte>);
Reading parse(std::string_view);

int base = 100;
auto add   = [](int a, int b){ return a + b; };      // no capture
auto shift = [base](int a){ return a + base; };      // capture by value (a copy)
auto tally = [&base](int a){ base += a; };           // capture by reference
auto gen   = [n = 0]() mutable { return n++; };      // init-capture + mutable state
auto anyT  = [](auto a, auto b){ return a + b; };    // generic (templated) lambda

struct Reading {
    std::uint16_t reg;
    std::int32_t  value;
    bool          valid = false;      // default member initializer
};

Reading a{40001, 230, true};                      // positional aggregate init
Reading b{.reg = 40001, .value = 230,             // designated (C++20); order must match
          .valid = true};

struct Bad  { std::uint8_t a; std::uint32_t b; std::uint8_t c; }; // sizeof 12 (padded)
struct Good { std::uint32_t b; std::uint8_t a; std::uint8_t c; }; // sizeof 8  (reordered)

static_assert(alignof(std::uint32_t) == 4);
alignas(64) std::array<std::byte, 64> cache_line;   // over-align (e.g. avoid false sharing)

struct Status { std::uint8_t ready:1, fault:1, mode:2, rsvd:4; };  // 1 byte, on-chip use
float f = std::bit_cast<float>(raw_u32);   // defined bit reinterpretation (no aliasing UB)

class TempSensor {
public:                                     // the interface
    explicit TempSensor(std::uint8_t addr)  // 'explicit' blocks implicit conversion
        : addr_{addr} {}                     // member initializer list (preferred)

    ~TempSensor() { disconnect(); }          // destructor: runs at end of scope (RAII)

    [[nodiscard]] std::int32_t read() const; // 'const': promises not to modify *this
    void set_offset(std::int32_t o) { offset_ = o; }

    static constexpr std::uint8_t kMaxAddr = 247;  // one value shared by all instances

private:                                     // the implementation — callers can't touch
    std::uint8_t addr_;
    std::int32_t offset_ = 0;
    void disconnect();
};

class Sensor {                              // abstract interface
public:
    virtual ~Sensor() = default;            // MUST be virtual (or protected) — see warning
    virtual std::int32_t read()       = 0;  // pure virtual: no body, class is abstract
    virtual const char*  name() const = 0;
};

class Modbus : public Sensor {
public:
    std::int32_t read() override;           // 'override' = the compiler checks the signature
    const char*  name() const override { return "modbus"; }
};

void log_all(std::span<Sensor* const> sensors) {
    for (Sensor* s : sensors)               // one interface...
        record(s->name(), s->read());       // ...dispatched to each concrete type
}

#include <unistd.h>
#include <utility>

class UniqueFd {
public:
    UniqueFd() = default;
    explicit UniqueFd(int fd) noexcept : fd_(fd) {}

    ~UniqueFd() { if (fd_ >= 0) ::close(fd_); }

    // move-only: fds are not copyable
    UniqueFd(UniqueFd&& o) noexcept : fd_(std::exchange(o.fd_, -1)) {}
    UniqueFd& operator=(UniqueFd&& o) noexcept {
        if (this != &o) { reset(); fd_ = std::exchange(o.fd_, -1); }
        return *this;
    }
    UniqueFd(const UniqueFd&)            = delete;
    UniqueFd& operator=(const UniqueFd&) = delete;

    int  get() const noexcept { return fd_; }
    int  release() noexcept   { return std::exchange(fd_, -1); }
    void reset() noexcept     { if (fd_ >= 0) ::close(fd_); fd_ = -1; }
    explicit operator bool() const noexcept { return fd_ >= 0; }
private:
    int fd_ = -1;
};

#include <memory>

auto sensor = std::make_unique<Sensor>(config);   // never `new`
auto shared = std::make_shared<Bus>();            // one alloc for ctrl+obj

// custom deleter for C resources without a wrapper type:
using FilePtr = std::unique_ptr<FILE, decltype([](FILE* f){ if(f) std::fclose(f); })>;
FilePtr fp{ std::fopen("log.bin", "rb") };

// weak_ptr to observe without extending lifetime
std::weak_ptr<Bus> watcher = shared;
if (auto b = watcher.lock()) { b->poll(); }        // safe: nullptr if gone

std::vector<int> build() {
    std::vector<int> v(1000);
    return v;                    // elided/NRVO — do NOT std::move here
}

void sink(std::string s);        // takes by value
std::string name = "modbus";
sink(std::move(name));           // move into the sink; `name` now valid-but-unspecified

// mark your own move ops noexcept — containers rely on it to move (not copy)
// on reallocation. A throwing move silently degrades vector growth to copies.
Buffer(Buffer&&) noexcept;

constexpr std::uint16_t crc16(std::span<const std::byte> d) noexcept {
    std::uint16_t crc = 0xFFFF;
    for (auto b : d) {
        crc ^= std::to_integer<std::uint16_t>(b);
        for (int i = 0; i < 8; ++i)
            crc = (crc & 1) ? (crc >> 1) ^ 0xA001 : crc >> 1;
    }
    return crc;
}
// usable at compile time AND runtime:
static_assert(crc16(/*...*/) == 0x4B37);

#include <optional>
#include <variant>
#include <expected>   // C++23

std::optional<Config> parse(std::string_view s);   // may fail to produce a value
if (auto cfg = parse(text)) { use(*cfg); }

// variant + visitor: exhaustive, no dynamic_cast
using Msg = std::variant<Ndata, Ddata, Nbirth>;
std::visit([](auto&& m){ handle(m); }, msg);         // compile-checked dispatch

// expected: value-or-error without exceptions (great for embedded/no-except builds)
std::expected<Frame, std::error_code> recv();
auto r = recv();
if (!r) return std::unexpected(r.error());
process(*r);

// accepts vector, array, C-array, part of a buffer — no copy:
std::uint16_t checksum(std::span<const std::byte> bytes);

std::array<std::byte, 64> buf;
checksum(buf);                         // whole
checksum(std::span{buf}.first(8));     // just the header

// string_view: no allocation to inspect text
bool starts_with_topic(std::string_view s) { return s.starts_with("spBv1.0/"); }

#include <concepts>

template <class T>
concept Serializable = requires(const T& t, std::vector<std::byte>& out) {
    { t.serialize(out) } -> std::same_as<void>;
    { T::type_id }       -> std::convertible_to<std::uint16_t>;
};

template <Serializable T>                 // clear constraint at declaration
void publish(const T& msg) { /* ... */ }

// constrain numeric algorithms too:
auto clamp_gain(std::floating_point auto x) { return std::min(x, 1.0); }

#include <ranges>
#include <chrono>
namespace views = std::views;
using namespace std::chrono_literals;

// lazy pipeline: only-online sensors, their ids, first 8 — no temp vectors
auto ids = sensors
         | views::filter([](auto& s){ return s.online; })
         | views::transform(&Sensor::id)
         | views::take(8);

// type-safe time: the compiler stops unit mistakes
std::chrono::milliseconds window = 500ms;
auto deadline = std::chrono::steady_clock::now() + window;
if (std::chrono::steady_clock::now() > deadline) timeout();

#include <cJSON.h>

// RAII wrapper: the tree is freed automatically, even on early return or throw.
struct CjsonDel { void operator()(cJSON* p) const noexcept { cJSON_Delete(p); } };
using CjsonPtr = std::unique_ptr<cJSON, CjsonDel>;

std::optional<Reading> parse_payload(std::string_view json) {
    CjsonPtr root{cJSON_ParseWithLength(json.data(), json.size())};
    if (!root) return std::nullopt;                       // malformed JSON

    const cJSON* reg = cJSON_GetObjectItemCaseSensitive(root.get(), "reg");
    const cJSON* val = cJSON_GetObjectItemCaseSensitive(root.get(), "value");
    if (!cJSON_IsNumber(reg) || !cJSON_IsNumber(val))     // ALWAYS type-check first
        return std::nullopt;

    return Reading{ .reg   = static_cast<std::uint16_t>(reg->valueint),
                    .value = val->valueint,
                    .valid = true };
}

CjsonPtr doc{cJSON_CreateObject()};
cJSON_AddStringToObject(doc.get(), "topic", "spBv1.0/plant/DDATA/edge/chiller");
cJSON_AddNumberToObject(doc.get(), "reg",   40001);
cJSON_AddBoolToObject  (doc.get(), "ok",    cJSON_True);

char* out = cJSON_PrintUnformatted(doc.get());  // compact; cJSON_Print for pretty output
std::string payload = out;                      // copy into owned storage
cJSON_free(out);                                // free cJSON's buffer (NOT cJSON_Delete)

#include <nlohmann/json.hpp>
using json = nlohmann::json;

json j = json::parse(payload, nullptr, /*allow_exceptions=*/false);
if (j.is_discarded()) return std::nullopt;        // parse failed, no throw
int reg = j.value("reg", 0);                       // typed get with a default
if (!j.contains("value")) return std::nullopt;

// struct <-> json with one macro:
struct Reading { std::uint16_t reg; std::int32_t value; bool valid; };
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(Reading, reg, value, valid)

Reading r = j.get<Reading>();                      // parse directly into your type
std::string s = json(r).dump();                    // ...and serialize back to text

// mark true no-throw ops noexcept: enables optimizations & container moves
void swap(Buffer& a, Buffer& b) noexcept;
~Session() noexcept;                       // destructors must not throw — ever

// expected failure: return it, force the caller to look
std::error_code connect(std::string_view host, std::uint16_t port) noexcept;
if (auto ec = connect(h, p)) {
    log.warn("connect failed: {}", ec.message());
    return ec;                              // propagate, don't swallow
}

// custom error category for your domain codes
enum class ModbusError { Timeout = 1, CrcMismatch, IllegalFunction };
std::error_code make_error_code(ModbusError);   // + register a category

#include <cassert>
void write_reg(std::uint16_t addr, std::uint16_t val) {
    assert(addr < kRegCount && "register address out of range"); // dev-time bug catch

    // always-on invariant for safety-critical paths (survives NDEBUG):
    if (!bus_.healthy()) [[unlikely]] { log_fatal("bus fault"); std::abort(); }
    // ...
}
// C++23: std::unreachable() for genuinely impossible branches (UB if reached)

#include <thread>
#include <stop_token>

std::jthread poller([](std::stop_token st){
    while (!st.stop_requested()) {
        poll_bus();
        std::this_thread::sleep_for(100ms);
    }
});
// ... on scope exit: poller.request_stop() is called AND it joins. No leak.

#include <mutex>
#include <condition_variable>
#include <queue>

template <class T>
class Mailbox {
public:
    void push(T v) {
        { std::scoped_lock lk(m_); q_.push(std::move(v)); }
        cv_.notify_one();
    }
    T pop() {                                   // blocking
        std::unique_lock lk(m_);
        cv_.wait(lk, [&]{ return !q_.empty(); });// predicate guards spurious wakeups
        T v = std::move(q_.front()); q_.pop();
        return v;
    }
private:
    std::mutex m_;
    std::condition_variable cv_;
    std::queue<T> q_;
};

#include <atomic>
std::atomic<bool> running{true};       // simple flag: default seq_cst is fine
running.store(false);                  // signal stop from another thread

std::atomic<std::uint64_t> frames{0};
frames.fetch_add(1, std::memory_order_relaxed);  // counter: relaxed is provably ok

// producer publishes data, then a ready flag with release;
// consumer reads flag with acquire -> sees the data. Textbook handoff:
data = build();
ready.store(true, std::memory_order_release);
// -- other thread --
if (ready.load(std::memory_order_acquire)) use(data);

// Factory: return the interface, hide the implementation
std::unique_ptr<Transport> make_transport(const Uri& uri) {
    if (uri.scheme == "tcp")    return std::make_unique<TcpTransport>(uri);
    if (uri.scheme == "serial") return std::make_unique<SerialTransport>(uri);
    throw std::invalid_argument("unknown scheme: " + uri.scheme);
}

// Builder: readable construction of a many-optioned object
class BrokerConfig {
public:
    BrokerConfig& host(std::string h)      && { host_ = std::move(h); return *this; }
    BrokerConfig& port(std::uint16_t p)    && { port_ = p;            return *this; }
    BrokerConfig& keepalive(std::chrono::seconds s) && { ka_ = s;    return *this; }
    Broker build() && { /* validate + construct */ return Broker{std::move(*this)}; }
private:
    std::string host_{"localhost"}; std::uint16_t port_{1883};
    std::chrono::seconds ka_{60};
};
auto b = BrokerConfig{}.host("emqx.local").port(8883).keepalive(30s).build();

// ---- session.hpp : no implementation details leak, no heavy includes ----
#pragma once
#include <memory>
#include <string_view>
class Session {
public:
    Session();
    ~Session();                              // defined in .cpp (Impl is complete there)
    Session(Session&&) noexcept;
    Session& operator=(Session&&) noexcept;
    void send(std::string_view topic, std::span<const std::byte> payload);
private:
    struct Impl;                             // opaque
    std::unique_ptr<Impl> p_;
};

// ---- session.cpp : all the real dependencies live here ----
struct Session::Impl { /* sockets, buffers, tls ctx ... */ };
Session::Session() : p_(std::make_unique<Impl>()) {}
Session::~Session() = default;               // MUST be here, not in header
Session::Session(Session&&) noexcept = default;
Session& Session::operator=(Session&&) noexcept = default;

// Strategy: inject the algorithm, no subclassing
class Retrier {
public:
    using Backoff = std::function<std::chrono::milliseconds(int attempt)>;
    explicit Retrier(Backoff b) : backoff_(std::move(b)) {}
private:
    Backoff backoff_;
};
Retrier exp{ [](int n){ return std::chrono::milliseconds(100 << n); } };

// Observer: subscribers are callbacks; RAII token auto-unsubscribes
class Signal {
public:
    using Slot = std::function<void(const Event&)>;
    [[nodiscard]] std::size_t connect(Slot s) {
        auto id = next_++; slots_.emplace(id, std::move(s)); return id;
    }
    void disconnect(std::size_t id) { slots_.erase(id); }
    void emit(const Event& e) const { for (auto& [_, s] : slots_) s(e); }
private:
    std::unordered_map<std::size_t, Slot> slots_; std::size_t next_{0};
};

template <class... Ts> struct overload : Ts... { using Ts::operator()...; };
template <class... Ts> overload(Ts...) -> overload<Ts...>;   // CTAD guide

using SpMessage = std::variant<NBirth, NData, NDeath, DBirth, DData>;

void dispatch(const SpMessage& m) {
    std::visit(overload{
        [](const NBirth& b){ register_node(b); },
        [](const NData&  d){ apply_metrics(d); },
        [](const NDeath& ){ mark_offline();   },
        [](const auto&   ){ /* DBirth/DData default */ },
    }, m);
}

template <class Derived>
class Codec {                                 // reusable behaviour, no vtable
public:
    std::vector<std::byte> encode(const Frame& f) const {
        return self().encode_impl(f);         // dispatched at compile time
    }
private:
    const Derived& self() const { return static_cast<const Derived&>(*this); }
};

class SparkplugCodec : public Codec<SparkplugCodec> {
    friend class Codec<SparkplugCodec>;
    std::vector<std::byte> encode_impl(const Frame&) const { /* ... */ return {}; }
};

class AnySensor {
    struct Concept {                          // internal interface
        virtual ~Concept() = default;
        virtual double read() const = 0;
        virtual std::unique_ptr<Concept> clone() const = 0;
    };
    template <class T>
    struct Model : Concept {                   // adapts any concrete T
        T obj;
        explicit Model(T o) : obj(std::move(o)) {}
        double read() const override { return obj.read(); }
        std::unique_ptr<Concept> clone() const override {
            return std::make_unique<Model>(*this);
        }
    };
    std::unique_ptr<Concept> self_;
public:
    template <class T>                          // T needs .read(); no inheritance!
    AnySensor(T x) : self_(std::make_unique<Model<T>>(std::move(x))) {}
    AnySensor(const AnySensor& o) : self_(o.self_->clone()) {}
    double read() const { return self_->read(); }
};

std::vector<AnySensor> sensors;               // heterogeneous, value-semantic, copyable
sensors.emplace_back(ModbusTemp{});
sensors.emplace_back(OpcUaFlow{});           // unrelated types, same container

template <class F>
struct ScopeGuard {
    F f; bool active = true;
    ~ScopeGuard() { if (active) f(); }
    void dismiss() noexcept { active = false; }
};
template <class F> ScopeGuard(F) -> ScopeGuard<F>;

void txn(Db& db) {
    db.begin();
    ScopeGuard rollback{[&]{ db.rollback(); }};   // runs if we throw / early-return
    do_work(db);
    db.commit();
    rollback.dismiss();                            // success: skip rollback
}
// (Prefer std::experimental::scope_exit / a vetted library if available.)

myproj/
├─ CMakeLists.txt            # top-level: project(), options, add_subdirectory
├─ CMakePresets.json         # named configure/build/test presets
├─ cmake/
│  └─ toolchains/aarch64-linux-gnu.cmake
├─ include/myproj/           # PUBLIC headers (installed)
│  └─ client.hpp
├─ src/                      # implementation + private headers
│  ├─ CMakeLists.txt
│  └─ client.cpp
├─ tests/
│  ├─ CMakeLists.txt
│  └─ client_test.cpp
├─ apps/                     # executables
└─ third_party/ (or use FetchContent)

cmake_minimum_required(VERSION 3.21)          # presets v3, good defaults
project(myproj VERSION 1.4.0 LANGUAGES CXX)

# Guard: no in-source builds
if(PROJECT_SOURCE_DIR STREQUAL PROJECT_BINARY_DIR)
  message(FATAL_ERROR "In-source builds are banned. Use a build/ dir.")
endif()

# Defaults only when we are the top project (don't dictate to parents)
if(PROJECT_IS_TOP_LEVEL)
  set(CMAKE_CXX_STANDARD 20)
  set(CMAKE_CXX_STANDARD_REQUIRED ON)
  set(CMAKE_CXX_EXTENSIONS OFF)
  set(CMAKE_EXPORT_COMPILE_COMMANDS ON)       # for clang-tidy / IDEs / LSP
  set_property(GLOBAL PROPERTY USE_FOLDERS ON)
endif()

option(MYPROJ_BUILD_TESTS "Build tests" ${PROJECT_IS_TOP_LEVEL})
option(MYPROJ_WARNINGS_AS_ERRORS "Treat warnings as errors" OFF)

add_subdirectory(src)
add_subdirectory(apps)

if(MYPROJ_BUILD_TESTS)
  enable_testing()
  add_subdirectory(tests)
endif()

add_library(myproj client.cpp)
add_library(myproj::myproj ALIAS myproj)       # namespaced alias for consumers

target_include_directories(myproj
  PUBLIC
    $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
    $<INSTALL_INTERFACE:include>                # correct path after install
  PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR})               # private headers

target_compile_features(myproj PUBLIC cxx_std_20)

# Warnings: attach per-target, generator-expression per compiler
target_compile_options(myproj PRIVATE
  $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra -Wpedantic -Wshadow -Wconversion>
  $<$<BOOL:${MYPROJ_WARNINGS_AS_ERRORS}>:-Werror>
  $<$<CXX_COMPILER_ID:MSVC>:/W4>)

target_link_libraries(myproj PUBLIC fmt::fmt PRIVATE Threads::Threads)

include(FetchContent)
FetchContent_Declare(fmt
  GIT_REPOSITORY https://github.com/fmtlib/fmt.git
  GIT_TAG        10.2.1                        # pin! never a moving branch
  GIT_SHALLOW    TRUE)
FetchContent_MakeAvailable(fmt)

# System/SDK dependency (found via toolchain sysroot when cross-compiling):
find_package(Threads REQUIRED)
find_package(OpenSSL 3 REQUIRED)               # target: OpenSSL::SSL

{
  "version": 6,
  "configurePresets": [
    {
      "name": "base", "hidden": true, "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/${presetName}",
      "cacheVariables": { "CMAKE_EXPORT_COMPILE_COMMANDS": "ON" }
    },
    {
      "name": "debug", "inherits": "base",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "CMAKE_CXX_FLAGS": "-fsanitize=address,undefined -fno-omit-frame-pointer"
      }
    },
    {
      "name": "release", "inherits": "base",
      "cacheVariables": { "CMAKE_BUILD_TYPE": "RelWithDebInfo",
                          "MYPROJ_WARNINGS_AS_ERRORS": "ON" }
    },
    {
      "name": "aarch64", "inherits": "release",
      "toolchainFile": "${sourceDir}/cmake/toolchains/aarch64-linux-gnu.cmake"
    }
  ],
  "buildPresets": [
    { "name": "debug",   "configurePreset": "debug" },
    { "name": "release", "configurePreset": "release" },
    { "name": "aarch64", "configurePreset": "aarch64" }
  ],
  "testPresets": [
    { "name": "debug", "configurePreset": "debug",
      "output": { "outputOnFailure": true } }
  ]
}

include(GNUInstallDirs)
include(CMakePackageConfigHelpers)

install(TARGETS myproj EXPORT myprojTargets
        ARCHIVE  DESTINATION ${CMAKE_INSTALL_LIBDIR}
        LIBRARY  DESTINATION ${CMAKE_INSTALL_LIBDIR}
        RUNTIME  DESTINATION ${CMAKE_INSTALL_BINDIR})
install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

install(EXPORT myprojTargets
        NAMESPACE myproj:: FILE myprojTargets.cmake
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/myproj)

write_basic_package_version_file(myprojConfigVersion.cmake
        VERSION ${PROJECT_VERSION} COMPATIBILITY SameMajorVersion)
# + configure_package_config_file(...) -> myprojConfig.cmake, then install it.

# --- What we're building for ---
set(CMAKE_SYSTEM_NAME       Linux)
set(CMAKE_SYSTEM_PROCESSOR  aarch64)

# --- The cross toolchain (adjust prefix to your GCC/Clang) ---
set(cross  aarch64-linux-gnu)
set(CMAKE_C_COMPILER   ${cross}-gcc)
set(CMAKE_CXX_COMPILER ${cross}-g++)
set(CMAKE_AR           ${cross}-ar)
set(CMAKE_STRIP        ${cross}-strip)

# --- The target sysroot: headers + libs for the device ---
set(CMAKE_SYSROOT      /opt/sysroots/aarch64)
set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})

# --- Search rules: programs on host, everything else in sysroot ---
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)   # use host's cmake/pkg-config
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)    # link target libs only
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)    # target headers only
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

# --- Optional: target-specific tuning ---
set(CMAKE_C_FLAGS_INIT   "-mcpu=cortex-a72")
set(CMAKE_CXX_FLAGS_INIT "-mcpu=cortex-a72")

cmake -B build/arm -G Ninja \
      -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/aarch64-linux-gnu.cmake \
      -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build/arm -j

file build/arm/apps/myapp   # -> ELF 64-bit LSB ... ARM aarch64  (verify!)

# 1. Install the SDK produced by populate_sdk
./poky-glibc-x86_64-...-aarch64-toolchain-4.0.sh -d /opt/sdk

# 2. Source its environment: sets CC, CXX, CROSS_COMPILE, OECORE_* , and
#    exports the correct sysroot + CMAKE_TOOLCHAIN_FILE for you
. /opt/sdk/environment-setup-cortexa72-poky-linux

# 3. Now CMake picks up the OE toolchain automatically
cmake -B build/yocto -G Ninja -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_TOOLCHAIN_FILE="$OECORE_NATIVE_SYSROOT/usr/share/cmake/OEToolchainConfig.cmake"
cmake --build build/yocto -j

SUMMARY = "myproj IoT edge client"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://LICENSE;md5=..."
SRC_URI = "git://example.com/myproj.git;branch=main;protocol=https"
SRCREV = "${AUTOREV}"
S = "${WORKDIR}/git"
inherit cmake
EXTRA_OECMAKE = "-DMYPROJ_BUILD_TESTS=OFF"

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
      cmake ninja-build git ca-certificates pkg-config \
      g++-aarch64-linux-gnu \
    && rm -rf /var/lib/apt/lists/*
# (mount or COPY your target sysroot to /opt/sysroots/aarch64)
WORKDIR /src
ENTRYPOINT ["cmake", "--preset", "aarch64"]

docker build -f Dockerfile.cross -t myproj-cross .
docker run --rm -v "$PWD:/src" -v /opt/sysroots:/opt/sysroots myproj-cross
docker run --rm -v "$PWD:/src" myproj-cross cmake --build --preset aarch64

# one-time: enable binfmt_misc handlers for foreign binaries
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# now target ELF "just runs":
qemu-aarch64 -L /opt/sysroots/aarch64 build/arm/tests/client_test

# or tell CMake to wrap all test invocations:
#   set(CMAKE_CROSSCOMPILING_EMULATOR qemu-aarch64;-L;/opt/sysroots/aarch64)
# then: ctest --preset ...   runs on-host via emulation

-Wall -Wextra -Wpedantic        # baseline; non-negotiable
-Wshadow                        # variable shadowing (subtle bugs)
-Wconversion -Wsign-conversion  # implicit narrowing / signedness
-Wcast-qual -Wold-style-cast    # dangerous / C-style casts
-Wnon-virtual-dtor              # base class w/ virtuals but non-virtual dtor
-Wdouble-promotion              # float silently promoted (matters on MCUs)
-Wformat=2 -Wnull-dereference -Wimplicit-fallthrough
-Werror                         # in CI: make warnings fatal

-D_FORTIFY_SOURCE=2             # runtime buffer-overflow checks (needs -O1+)
-fstack-protector-strong       # stack canaries
-fstack-clash-protection
-fPIE -pie                     # ASLR for executables
-Wl,-z,relro,-z,now            # full RELRO: GOT read-only after load
-Wl,-z,noexecstack             # non-executable stack
-fcf-protection=full           # CET/branch-protection (x86); use
                               # -mbranch-protection=standard on aarch64

cmake -B build/asan -G Ninja -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer -g"
cmake --build build/asan && ctest --test-dir build/asan --output-on-failure
# ASAN_OPTIONS=detect_leaks=1:halt_on_error=1  UBSAN_OPTIONS=print_stacktrace=1

run-clang-tidy -p build/debug            # uses compile_commands.json
cppcheck --enable=warning,performance,portability --std=c++20 \
         --project=build/debug/compile_commands.json
# In CMake, lint during build:
#   set(CMAKE_CXX_CLANG_TIDY clang-tidy;--warnings-as-errors=bugprone-*)

include(FetchContent)
FetchContent_Declare(googletest
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG v1.15.2)
FetchContent_MakeAvailable(googletest)

add_executable(client_test client_test.cpp)
target_link_libraries(client_test PRIVATE myproj::myproj GTest::gtest_main)

include(GoogleTest)
gtest_discover_tests(client_test)          # each TEST() becomes a ctest case

#include <gtest/gtest.h>
#include "myproj/client.hpp"

TEST(Crc16, KnownVector) {
    std::array<std::byte, 2> d{std::byte{0x01}, std::byte{0x04}};
    EXPECT_EQ(mbus::crc16(d), 0x0A61);
}
TEST(Client, RejectsBadScheme) {
    EXPECT_THROW(make_transport(Uri{"gopher", "x"}), std::invalid_argument);
}

name: ci
on: [push, pull_request]
jobs:
  build:
    strategy:
      matrix:
        preset: [debug, release]        # debug carries ASan+UBSan
        cxx:    [g++, clang++]
    runs-on: ubuntu-latest
    env: { CXX: "${{ matrix.cxx }}" }
    steps:
      - uses: actions/checkout@v4
      - run: sudo apt-get update && sudo apt-get install -y ninja-build clang-tidy
      - run: cmake --preset ${{ matrix.preset }} -DMYPROJ_WARNINGS_AS_ERRORS=ON
      - run: cmake --build --preset ${{ matrix.preset }}
      - run: ctest --preset ${{ matrix.preset }} --output-on-failure
  cross-aarch64:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: sudo apt-get update && sudo apt-get install -y g++-aarch64-linux-gnu ninja-build qemu-user-static
      - run: cmake --preset aarch64
      - run: cmake --build --preset aarch64

#include <spdlog/spdlog.h>
spdlog::set_level(spdlog::level::from_str(cfg.log_level));   // runtime-controlled
spdlog::info("connected broker={} port={} tls={}", host, port, use_tls);
spdlog::warn("reconnect attempt={} backoff_ms={}", n, backoff.count());
if (ec) spdlog::error("publish failed topic={} err={}", topic, ec.message());

#include <cstdint>
#include <expected>
#include <span>

namespace fieldbus {

/// @brief Synchronous Modbus/TCP client for a single device.
///
/// One instance owns one TCP connection and is **not** thread-safe;
/// serialize access or give each thread its own client. Register
/// addresses are zero-based; the wire protocol's 1-based offset is
/// applied internally.
///
/// @note Reconnection is the caller's responsibility — a dropped
///       socket surfaces as @ref Error::transport on the next call.
/// @see  https://modbus.org/specs.php
class ModbusClient {
public:
  /// Error categories returned by every operation.
  enum class Error { timeout, crc, exception_response, transport };

  /// @brief Read a block of holding registers (function code 0x03).
  ///
  /// @param unit   Modbus unit/slave id (1–247).
  /// @param addr   Zero-based starting register address.
  /// @param count  Number of 16-bit registers to read (1–125).
  /// @return The register values on success, or an Error on failure.
  ///
  /// @pre  @p count is in [1, 125]; larger reads must be split.
  /// @post On success, the returned span has exactly @p count elements.
  ///
  /// @code
  ///   auto r = client.read_holding(unit: 1, addr: 0, count: 8);
  ///   if (r) use(*r);
  ///   else   log_error(r.error());
  /// @endcode
  [[nodiscard]] std::expected<std::vector<std::uint16_t>, Error>
  read_holding(std::uint8_t unit, std::uint16_t addr, std::uint16_t count);

  /// @brief Write a single holding register (function code 0x06).
  /// @param unit  Unit id (1–247).  @param addr  Zero-based address.
  /// @param value 16-bit value to write.
  /// @retval Error::exception_response  Device rejected the write.
  std::expected<void, Error>
  write_register(std::uint8_t unit, std::uint16_t addr, std::uint16_t value);
};

/// @brief CRC-16 (Modbus polynomial 0xA001) over a byte range.
/// @tparam Bytes  A contiguous range of @c std::byte.
/// @param  data   The bytes to checksum (header + payload, no CRC).
/// @return The 16-bit CRC in little-endian wire order.
template <class Bytes>
[[nodiscard]] std::uint16_t crc16(std::span<const std::byte> data) noexcept;

} // namespace fieldbus

PROJECT_NAME           = "fieldbus"
PROJECT_NUMBER         = $(GIT_DESCRIBE)     # inject version from CMake
OUTPUT_DIRECTORY       = build/doc
INPUT                  = include README.md
FILE_PATTERNS          = *.hpp *.h *.md
RECURSIVE              = YES
USE_MDFILE_AS_MAINPAGE = README.md           # landing page from your README

EXTRACT_ALL            = NO                  # only document commented entities
EXTRACT_PRIVATE        = NO                  # keep internals out of the API ref
EXTRACT_STATIC         = YES
JAVADOC_AUTOBRIEF      = YES                 # first sentence = @brief

GENERATE_HTML          = YES
GENERATE_LATEX         = NO
GENERATE_XML           = YES                 # required if you feed Sphinx/Breathe
GENERATE_TREEVIEW      = YES                 # sidebar navigation

HAVE_DOT               = YES                 # needs Graphviz installed
CALL_GRAPH             = YES
CLASS_GRAPH            = YES

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES
WARN_AS_ERROR          = FAIL_ON_WARNINGS    # doc drift breaks the build

find_package(Doxygen REQUIRED dot)          # 'dot' component = Graphviz graphs

# Each var maps to a Doxyfile setting: DOXYGEN_<NAME> -> <NAME>.
set(DOXYGEN_EXTRACT_PRIVATE      NO)
set(DOXYGEN_GENERATE_TREEVIEW    YES)
set(DOXYGEN_GENERATE_XML         YES)       # for a later Sphinx/Breathe pass
set(DOXYGEN_WARN_AS_ERROR        FAIL_ON_WARNINGS)
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${PROJECT_SOURCE_DIR}/README.md")
set(DOXYGEN_PROJECT_NUMBER       "${PROJECT_VERSION}")

doxygen_add_docs(docs                       # target name: `cmake --build . -t docs`
  "${PROJECT_SOURCE_DIR}/include"
  "${PROJECT_SOURCE_DIR}/README.md"
  ALL                                       # build docs as part of the default target
  COMMENT "Generating API documentation with Doxygen")

pip install sphinx breathe furo             # Sphinx + the Doxygen bridge + theme
# 1) Doxygen with GENERATE_XML = YES  ->  build/doxygen/xml
# 2) Sphinx consumes that XML via Breathe  ->  build/sphinx/html

project = "fieldbus"
extensions = ["breathe", "myst_parser"]     # myst_parser = Markdown in Sphinx
html_theme = "furo"

# Point Breathe at Doxygen's XML output.
breathe_projects = {"fieldbus": "../build/doxygen/xml"}
breathe_default_project = "fieldbus"
breathe_default_members = ("members", "undoc-members")

.. doxygenclass:: fieldbus::ModbusClient
   :members:

.. doxygenfunction:: fieldbus::crc16