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