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