# openbmc/sdbusplus architecture

> Architecture diagram of the GitHub repository openbmc/sdbusplus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbmc/sdbusplus
- Repository: https://github.com/openbmc/sdbusplus

## Overview

##### Project type and purpose
- This is an open-source project that provides:
- A modern C++ wrapper library (“libsdbusplus”) on top of systemd’s sd-bus API for D-Bus programming.
- A Python-based code‐generation tool (“sdbus++”) that consumes YAML interface/error definitions and emits C++ binding code.

##### Main components
a. External dependencies
- libsystemd/sd-bus (C API for D-Bus)
- Python runtime with Mako & Inflection
- Meson/Ninja build system
b. Core library (C++ – “libsdbusplus”)
- bus namespace (bus connection, method‐call, match, event loop integration via asio)
- message namespace (marshalling, signatures, read/unpack, append)
- server namespace (object server, vtable abstraction, transactions)
- async/stdexec namespace (senders/receivers, timer, context, fdio)
- utility & vtable helpers
c. Code‐generator tool (Python – “sdbus++”)
- Input: YAML files (interface, error definitions)
- Renderer: Mako templates under tools/sdbusplus/templates
- Output: generated C++ .hpp/.cpp for server stubs, client proxies, exception classes, Markdown docs
d. Examples & Tests
- example/… demonstrating direct library use or generated-code use
- test/… exercising library modules and codegen outputs

##### Relationships and interactions
- Developers write YAML interface/error files → feed into sdbus++ tool → generates C++ binding code
- Generated code plus handwritten application code link against libsdbusplus
- libsdbusplus makes sd-bus calls to communicate over the D-Bus socket
- Meson orchestrates building of libsdbusplus, examples, tests, and installs the Python tool

##### Architectural patterns & noteworthy design
- Layered architecture: Python codegen sits above C++ library, YAML definitions at top
- Adapter/facade: libsdbusplus wraps sd-bus C API in modern C++ classes and patterns (RAII, template metaprogramming)
- Template‐driven codegen: Mako templates for generating boilerplate D-Bus object and method dispatch code
- Modular C++ namespaces (bus, message, server, async/stdexec, utility) for separation of concerns

##### Essential details to capture
- The dual nature of the project (library vs. codegen tool)
- The build dependencies and toolchain (Meson → Ninja, setuptools for Python)
- The flow of data: YAML → code → compile/link → runtime D-Bus interaction
- Core C++ namespaces and their roles in handling D-Bus messaging, object servers, and asynchronous operations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        SD["libsystemd/sd-bus (C API)"]:::external
        PY["Python Runtime (Mako, Inflection)"]:::external
        MESON["Meson/Ninja Build"]:::build
    end

    %% Inputs
    subgraph "YAML Definitions" 
        Y1["Calculator.interface.yaml"]:::data
        Y2["Calculator.events.yaml"]:::data
        Y3["interface.md & error.md"]:::data
    end

    %% Code-Generator Tool
    subgraph "Code-Generator (sdbus++)" 
        CG_MAIN["main.py"]:::python
        CG_INT["interface.py"]:::python
        CG_ERR["error.py"]:::python
        CG_RND["renderer.py"]:::python
        CG_TMP["Mako Templates"]:::template
    end

    %% Generated Code
    GEN["Generated C++ Code (.hpp/.cpp)"]:::generated

    %% Application Code
    APP["Handwritten Application Code"]:::cpp

    %% Core Library
    subgraph "libsdbusplus (C++ Library)"
        subgraph "bus namespace"
            BUS["libsdbusplus::bus"]:::cpp
        end
        subgraph "message namespace"
            MSG["libsdbusplus::message"]:::cpp
        end
        subgraph "server namespace"
            SRV["libsdbusplus::server"]:::cpp
        end
        subgraph "async namespace"
            ASY["libsdbusplus::async"]:::cpp
        end
        subgraph "async/stdexec namespace"
            STD["libsdbusplus::async::stdexec"]:::cpp
        end
        subgraph "utility & vtable"
            UTIL["libsdbusplus::utility & vtable"]:::cpp
        end
    end

    %% Examples & Tests
    subgraph "Examples"
        EX1["asio-example.cpp"]:::example
        EX2["calculator-server.cpp"]:::example
        EX3["calculator-client.cpp"]:::example
    end

    subgraph "Tests"
        T_LIB["Library Module Tests"]:::test
        T_GEN["Codegen Output Tests"]:::test
    end

    %% Runtime Path
    APP -->|links against| BUS
    APP -->|links against| MSG
    APP -->|links against| SRV
    APP -->|links against| ASY
    APP -->|links against| STD
    APP -->|links against| UTIL
    BUS -->|"D-Bus API calls"| SD
    MSG -->|"D-Bus API calls"| SD
    SRV -->|"D-Bus API calls"| SD
    ASY -->|"D-Bus API calls"| SD
    STD -->|"D-Bus API calls"| SD
    UTIL -->|"helpers"| BUS

    %% Build-time Path
    Y1 -->|input| CG_MAIN
    Y2 -->|input| CG_MAIN
    Y3 -->|schema| CG_MAIN
    CG_MAIN -->|imports| CG_INT
    CG_MAIN -->|imports| CG_ERR
    CG_MAIN -->|uses| CG_RND
    CG_RND -->|templates| CG_TMP
    CG_MAIN -->|emits| GEN
    GEN -->|compiled with| MESON
    APP -->|compiled with| MESON
    MESON -->|runs| CG_MAIN
    MESON -->|builds| BUS
    MESON -->|builds| MSG
    MESON -->|builds| SRV
    MESON -->|builds| ASY
    MESON -->|builds| STD
    MESON -->|builds| UTIL
    MESON -->|builds| EX1 & EX2 & EX3
    MESON -->|runs tests| T_LIB & T_GEN
    PY -->|provides| CG_MAIN
    MESON -->|uses Python| PY

    %% Examples & Tests linkage
    EX1 -->|uses| BUS
    EX2 -->|uses generated & BUS| GEN & BUS
    EX3 -->|uses generated & BUS| GEN & BUS
    T_LIB -->|tests| BUS & MSG & SRV & ASY & STD & UTIL
    T_GEN -->|tests| GEN

    %% Click Events
    click BUS "https://github.com/openbmc/sdbusplus/blob/master/include/sdbusplus/bus.hpp"
    click MSG "https://github.com/openbmc/sdbusplus/blob/master/include/sdbusplus/message/append.hpp"
    click SRV "https://github.com/openbmc/sdbusplus/blob/master/include/sdbusplus/server/interface.hpp"
    click ASY "https://github.com/openbmc/sdbusplus/blob/master/include/sdbusplus/async/callback.hpp"
    click STD "https://github.com/openbmc/sdbusplus/tree/master/include/sdbusplus/async/stdexec/"
    click UTIL "https://github.com/openbmc/sdbusplus/blob/master/include/sdbusplus/utility/consteval_string.hpp"
    click CG_MAIN "https://github.com/openbmc/sdbusplus/blob/master/tools/sdbusplus/main.py"
    click CG_TMP "https://github.com/openbmc/sdbusplus/tree/master/tools/sdbusplus/templates/"
    click Y1 "https://github.com/openbmc/sdbusplus/blob/master/example/yaml/net/poettering/Calculator.interface.yaml"
    click EX1 "https://github.com/openbmc/sdbusplus/blob/master/example/asio-example.cpp"
    click T_LIB "https://github.com/openbmc/sdbusplus/tree/master/test/bus/"
    click T_GEN "https://github.com/openbmc/sdbusplus/blob/master/test/gen/server/Test.interface.yaml"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef python fill:#ffe4b5,stroke:#bf8f00,stroke-width:1px
    classDef cpp fill:#add8e6,stroke:#036,stroke-width:1px
    classDef build fill:#d3d3d3,stroke:#555,stroke-width:1px
    classDef data fill:#ffffe0,stroke:#aa0,stroke-width:1px
    classDef template fill:#e0ffff,stroke:#008b8b,stroke-width:1px
    classDef generated fill:#d0f0c0,stroke:#228b22,stroke-width:1px
    classDef example fill:#ffebcd,stroke:#cd853f,stroke-width:1px
    classDef test fill:#f0d0d0,stroke:#a00,stroke-width:1px
```
