1# sdbusplus 2 3sdbusplus contains two parts: 4 51. A C++ library (libsdbusplus) for interacting with D-Bus, built on top of 6 the sd-bus library from systemd. 72. A tool (sdbus++) to generate C++ bindings to simplify the development of 8 D-Bus-based applications. 9 10## Dependencies 11 12The sdbusplus library requires sd-bus, which is contained in libsystemd. 13 14The sdbus++ application requires Python 3 and the Python libraries mako 15and inflection. 16 17## Building 18 19The sdbusplus library is built using meson. 20 21``` 22meson build 23cd build 24ninja 25ninja test 26ninja install 27``` 28 29Optionally, building the tests and examples can be disabled by passing 30`-Dtests=disabled` and `-Dexamples=disabled` respectively to `meson. 31 32The sdbus++ application is installed as a standard Python package 33using `setuptools`. 34 35``` 36cd tools 37./setup.py install 38``` 39 40## C++ library 41 42The sdbusplus library builds on top of the 43[sd-bus](http://0pointer.net/blog/the-new-sd-bus-api-of-systemd.html) 44library to create a modern C++ API for D-Bus. The library attempts to be 45as lightweight as possible, usually compiling to exactly the sd-bus API 46calls that would have been necessary, while also providing compile-time 47type-safety and memory leak protection afforded by modern C++ practices. 48 49Consider the following code: 50``` 51auto b = bus::new_default_system(); 52auto m = b.new_method_call("org.freedesktop.login1", 53 "/org/freedesktop/login1", 54 "org.freedesktop.login1.Manager", 55 "ListUsers"); 56auto reply = b.call(m); 57 58std::vector<std::tuple<uint32_t, std::string, message::object_path>> users; 59reply.read(users); 60``` 61 62In a few, relatively succinct, C++ lines this snippet will create a D-Bus 63connection to the system bus, and call the systemd login manager to get a 64list of active users. The message and bus objects are automatically freed 65when they leave scope and the message format strings are generated at compile 66time based on the types being read. Compare this to the corresponding server 67code within [logind](https://github.com/systemd/systemd/blob/d60c527009133a1ed3d69c14b8c837c790e78d10/src/login/logind-dbus.c#L496). 68 69In general, the library attempts to mimic the naming conventions of the sd-bus 70library: ex. `sd_bus_call` becomes `sdbusplus::bus::call`, 71`sd_bus_get_unique_name` becomes `sdbusplus::bus::get_unique_name`, 72`sd_bus_message_get_signature` becomes `sdbusplus::message::get_signature`, 73etc. This allows a relatively straight-forward translation back to the sd-bus 74functions for looking up the manpage details. 75 76## Binding generation tool 77 78sdbusplus also contains a bindings generator tool: `sdbus++`. The purpose of 79a bindings generator is to reduce the boilerplate associated with creating 80D-Bus server or client applications. When creating a server application, 81rather than creating sd-bus vtables and writing C-style functions to handle 82each vtable callback, you can create a small YAML file to define your D-Bus 83interface and the `sdbus++` tool will create a C++ class that implements your 84D-Bus interface. This class has a set of virtual functions for each method 85and property, which you can overload to create your own customized behavior 86for the interface. 87 88There are currently two types of YAML files: [interface](docs/interface.md) and 89[error](docs/error.md). Interfaces are used to create server and client D-Bus 90interfaces. Errors are used to define C++ exceptions which can be thrown and 91will automatically turn into D-Bus error responses. 92 93[[ D-Bus client bindings are not yet implemented. See openbmc/openbmc#851. ]] 94 95### Generating bindings 96 97## How to use tools/sdbus++ 98 99The path of your file will be the interface name. For example, for an interface 100`org.freedesktop.Example`, you would create the files 101`org/freedesktop/Example.interface.yaml` and 102`org/freedesktop/Example.errors.yaml]` for interfaces and errors respectively. 103These can then be used to generate the server and error bindings: 104``` 105sdbus++ interface server-header org.freedesktop.Example > \ 106 org/freedesktop/Example/server.hpp 107sdbus++ interface server-cpp org.freedesktop.Example > \ 108 org/freedesktop/Example/server.cpp 109sdbus++ error exception-header org.freedesktop.Example > \ 110 org/freedesktop/Example/error.hpp \ 111sdbus++ error exception-cpp org.freedesktop.Example > \ 112 org/freedesktop/Example/error.cpp 113``` 114 115Markdown-based documentation can also be generated from the interface and 116exception files: 117``` 118sdbus++ interface markdown org.freedesktop.Example > \ 119 org/freedesktop/Example.md 120sdbus++ error markdown org.freedesktop.Example >> \ 121 org/freedesktop/Example.md 122``` 123 124See the `example/meson.build` for more details. 125 126## Installing sdbusplus on custom distributions 127 128Installation of sdbusplus bindings on a custom distribution requires a few 129packages to be installed prior. Although these packages are the same for several 130distributions the names of these packages do differ. Below are the packages 131needed for Ubuntu and Fedora. 132 133### Installation on Ubuntu 134 135``` 136sudo apt install git meson libtool pkg-config g++ libsystemd-dev python3 python3-pip python3-yaml python3-mako python3-inflection 137``` 138 139### Installation on Fedora 140 141``` 142sudo dnf install git meson libtool gcc-c++ pkgconfig systemd-devel python3 python3-pip python3-yaml python3-mako 143``` 144Install the inflection package using the pip utility (on Fedora) 145``` 146pip3 install inflection 147``` 148 149