xref: /openbmc/sdbusplus/README.md (revision 4ac7e56e) 
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