xref: /openbmc/sdbusplus/README.md (revision 9ede18b4) 
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```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
33using `setuptools`.
34
35```sh
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
51```cpp
52auto b = bus::new_default_system();
53auto m = b.new_method_call("org.freedesktop.login1",
54                           "/org/freedesktop/login1",
55                           "org.freedesktop.login1.Manager",
56                           "ListUsers");
57auto reply = b.call(m);
58
59std::vector<std::tuple<uint32_t, std::string, message::object_path>> users;
60reply.read(users);
61```
62
63In a few, relatively succinct, C++ lines this snippet will create a D-Bus
64connection to the system bus, and call the systemd login manager to get a
65list of active users. The message and bus objects are automatically freed
66when they leave scope and the message format strings are generated at compile
67time based on the types being read. Compare this to the corresponding server
68code within [logind](https://github.com/systemd/systemd/blob/d60c527009133a1ed3d69c14b8c837c790e78d10/src/login/logind-dbus.c#L496).
69
70In general, the library attempts to mimic the naming conventions of the sd-bus
71library: ex. `sd_bus_call` becomes `sdbusplus::bus::call`,
72`sd_bus_get_unique_name` becomes `sdbusplus::bus::get_unique_name`,
73`sd_bus_message_get_signature` becomes `sdbusplus::message::get_signature`,
74etc. This allows a relatively straight-forward translation back to the sd-bus
75functions for looking up the manpage details.
76
77## Binding generation tool
78
79sdbusplus also contains a bindings generator tool: `sdbus++`. The purpose of
80a bindings generator is to reduce the boilerplate associated with creating
81D-Bus server or client applications. When creating a server application,
82rather than creating sd-bus vtables and writing C-style functions to handle
83each vtable callback, you can create a small YAML file to define your D-Bus
84interface and the `sdbus++` tool will create a C++ class that implements your
85D-Bus interface. This class has a set of virtual functions for each method
86and property, which you can overload to create your own customized behavior
87for the interface.
88
89There are currently two types of YAML files: [interface](docs/interface.md) and
90[error](docs/error.md). Interfaces are used to create server and client D-Bus
91interfaces. Errors are used to define C++ exceptions which can be thrown and
92will automatically turn into D-Bus error responses.
93
94[[D-Bus client bindings are not yet implemented.  See openbmc/openbmc#851.]]
95
96### Generating bindings
97
98## How to use tools/sdbus++
99
100The path of your file will be the interface name. For example, for an interface
101`org.freedesktop.Example`, you would create the files
102`org/freedesktop/Example.interface.yaml` and
103`org/freedesktop/Example.errors.yaml]` for interfaces and errors respectively.
104These can then be used to generate the server and error bindings:
105
106```sh
107sdbus++ interface server-header org.freedesktop.Example > \
108    org/freedesktop/Example/server.hpp
109sdbus++ interface server-cpp org.freedesktop.Example > \
110    org/freedesktop/Example/server.cpp
111sdbus++ error exception-header org.freedesktop.Example > \
112    org/freedesktop/Example/error.hpp \
113sdbus++ error exception-cpp org.freedesktop.Example > \
114    org/freedesktop/Example/error.cpp
115```
116
117Markdown-based documentation can also be generated from the interface and
118exception files:
119
120```sh
121sdbus++ interface markdown org.freedesktop.Example > \
122    org/freedesktop/Example.md
123sdbus++ error markdown org.freedesktop.Example >> \
124    org/freedesktop/Example.md
125```
126
127See the `example/meson.build` for more details.
128
129## Installing sdbusplus on custom distributions
130
131Installation of sdbusplus bindings on a custom distribution requires a few
132packages to be installed prior. Although these packages are the same for several
133distributions the names of these packages do differ. Below are the packages
134needed for Ubuntu and Fedora.
135
136### Installation on Ubuntu
137
138```sh
139sudo apt install git meson libtool pkg-config g++ libsystemd-dev \
140    python3 python3-pip python3-yaml python3-mako python3-inflection
141```
142
143### Installation on Fedora
144
145```sh
146sudo dnf install git meson libtool gcc-c++ pkgconfig systemd-devel \
147    python3 python3-pip python3-yaml python3-mako
148```
149
150Install the inflection package using the pip utility (on Fedora)
151
152```sh
153pip3 install inflection
154```
155