| 1 |
Sections in this file describe: |
| 2 |
- introduction and overview |
| 3 |
- low-level vs. high-level API |
| 4 |
- version numbers |
| 5 |
- options to the configure script |
| 6 |
- ABI stability policy |
| 7 |
|
| 8 |
Introduction |
| 9 |
=== |
| 10 |
|
| 11 |
D-Bus is a simple system for interprocess communication and coordination. |
| 12 |
|
| 13 |
The "and coordination" part is important; D-Bus provides a bus daemon that does things like: |
| 14 |
- notify applications when other apps exit |
| 15 |
- start services on demand |
| 16 |
- support single-instance applications |
| 17 |
|
| 18 |
See https://www.freedesktop.org/wiki/Software/dbus/ for lots of documentation, |
| 19 |
mailing lists, etc. |
| 20 |
|
| 21 |
See also the file CONTRIBUTING.md for notes of interest to developers |
| 22 |
working on D-Bus. |
| 23 |
|
| 24 |
If you're considering D-Bus for use in a project, you should be aware |
| 25 |
that D-Bus was designed for a couple of specific use cases, a "system |
| 26 |
bus" and a "desktop session bus." These are documented in more detail |
| 27 |
in the D-Bus specification and FAQ available on the web site. |
| 28 |
|
| 29 |
If your use-case isn't one of these, D-Bus may still be useful, but |
| 30 |
only by accident; so you should evaluate carefully whether D-Bus makes |
| 31 |
sense for your project. |
| 32 |
|
| 33 |
Security |
| 34 |
=== |
| 35 |
|
| 36 |
If you find a security vulnerability that is not known to the public, |
| 37 |
please report it privately to [email protected] |
| 38 |
or by reporting a Gitlab issue at |
| 39 |
https://gitlab.freedesktop.org/dbus/dbus/issues/new and marking it |
| 40 |
as "confidential". |
| 41 |
Please do not open merge requests for security issues: if you have a |
| 42 |
proposed patch, it can be discussed on the confidential issue or by |
| 43 |
private email. |
| 44 |
|
| 45 |
On Unix systems, the system bus (dbus-daemon --system) is designed |
| 46 |
to be a security boundary between users with different privileges. |
| 47 |
|
| 48 |
On Unix systems, the session bus (dbus-daemon --session) is designed |
| 49 |
to be used by a single user, and only accessible by that user. |
| 50 |
|
| 51 |
We do not currently consider D-Bus on Windows to be security-supported, |
| 52 |
and we do not recommend allowing untrusted users to access Windows |
| 53 |
D-Bus via TCP. |
| 54 |
|
| 55 |
Note: low-level API vs. high-level binding APIs |
| 56 |
=== |
| 57 |
|
| 58 |
A core concept of the D-Bus implementation is that "libdbus" is |
| 59 |
intended to be a low-level API. Most programmers are intended to use |
| 60 |
the bindings to GLib, Qt, Python, Mono, Java, or whatever. These |
| 61 |
bindings have varying levels of completeness and are maintained as |
| 62 |
separate projects from the main D-Bus package. The main D-Bus package |
| 63 |
contains the low-level libdbus, the bus daemon, and a few command-line |
| 64 |
tools such as dbus-launch. |
| 65 |
|
| 66 |
If you use the low-level API directly, you're signing up for some |
| 67 |
pain. Think of the low-level API as analogous to Xlib or GDI, and the |
| 68 |
high-level API as analogous to Qt/GTK+/HTML. |
| 69 |
|
| 70 |
Version numbers |
| 71 |
=== |
| 72 |
|
| 73 |
D-Bus uses the same odd/even versioning system as GLib, SDL and older |
| 74 |
Linux kernels, where even-numbered minor versions are stable and |
| 75 |
odd-numbered minor versions are development snapshots. |
| 76 |
|
| 77 |
So for example, development snapshots: 1.1.1, 1.1.2, 1.1.3, 1.3.4 |
| 78 |
Stable versions: 1.0, 1.0.1, 1.0.2, 1.2.1, 1.2.3 |
| 79 |
|
| 80 |
All pre-1.0 versions were development snapshots. |
| 81 |
|
| 82 |
Development snapshots make no ABI stability guarantees for new ABI |
| 83 |
introduced since the last stable release. Development snapshots are |
| 84 |
likely to have more bugs than stable releases, obviously. |
| 85 |
|
| 86 |
Since 1.16.0, development snapshots will also have an -alpha, -beta or -rc |
| 87 |
suffix on the version number to make their development status more obvious. |
| 88 |
|
| 89 |
Configuration and installation |
| 90 |
=== |
| 91 |
|
| 92 |
This branch of dbus can be built by using Meson or CMake. |
| 93 |
The Meson build system is the recommended build system since version 1.16.0, |
| 94 |
except when building on Windows, for which CMake is recommended (this |
| 95 |
recommendation might change to Meson in future). |
| 96 |
|
| 97 |
Please see `INSTALL` for full details. |
| 98 |
|
| 99 |
API/ABI Policy |
| 100 |
=== |
| 101 |
|
| 102 |
Now that D-Bus has reached version 1.0, the objective is that all |
| 103 |
applications dynamically linked to libdbus will continue working |
| 104 |
indefinitely with the most recent system and session bus daemons. |
| 105 |
|
| 106 |
- The protocol will never be broken again; any message bus should |
| 107 |
work with any client forever. However, extensions are possible |
| 108 |
where the protocol is extensible. |
| 109 |
|
| 110 |
- If the library API is modified incompatibly, we will rename it |
| 111 |
as in http://ometer.com/parallel.html - in other words, |
| 112 |
it will always be possible to compile against and use the older |
| 113 |
API, and apps will always get the API they expect. |
| 114 |
|
| 115 |
Interfaces can and probably will be _added_. This means both new |
| 116 |
functions and types in libdbus, and new methods exported to |
| 117 |
applications by the bus daemon. |
| 118 |
|
| 119 |
The above policy is intended to make D-Bus as API-stable as other |
| 120 |
widely-used libraries (such as GTK+, Qt, Xlib, or your favorite |
| 121 |
example). If you have questions or concerns they are very welcome on |
| 122 |
the D-Bus mailing list. |
| 123 |
|
| 124 |
NOTE ABOUT DEVELOPMENT SNAPSHOTS AND VERSIONING |
| 125 |
|
| 126 |
Odd-numbered minor releases (1.1.x, 1.3.x, 2.1.x, etc. - |
| 127 |
major.minor.micro) are devel snapshots for testing, and any new ABI |
| 128 |
they introduce relative to the last stable version is subject to |
| 129 |
change during the development cycle. |
| 130 |
|
| 131 |
Any ABI found in a stable release, however, is frozen. |
| 132 |
|
| 133 |
ABI will not be added in a stable series if we can help it. i.e. the |
| 134 |
ABI of 1.2.0 and 1.2.5 you can expect to be the same, while the ABI of |
| 135 |
1.4.x may add more stuff not found in 1.2.x. |
| 136 |
|
| 137 |
NOTE ABOUT STATIC LINKING |
| 138 |
|
| 139 |
We are not yet firmly freezing all runtime dependencies of the libdbus |
| 140 |
library. For example, the library may read certain files as part of |
| 141 |
its implementation, and these files may move around between versions. |
| 142 |
|
| 143 |
As a result, we don't yet recommend statically linking to |
| 144 |
libdbus. Also, reimplementations of the protocol from scratch might |
| 145 |
have to work to stay in sync with how libdbus behaves. |
| 146 |
|
| 147 |
To lock things down and declare static linking and reimplementation to |
| 148 |
be safe, we'd like to see all the internal dependencies of libdbus |
| 149 |
(for example, files read) well-documented in the specification, and |
| 150 |
we'd like to have a high degree of confidence that these dependencies |
| 151 |
are supportable over the long term and extensible where required. |
| 152 |
|
| 153 |
NOTE ABOUT HIGH-LEVEL BINDINGS |
| 154 |
|
| 155 |
Note that the high-level bindings are _separate projects_ from the |
| 156 |
main D-Bus package, and have their own release cycles, levels of |
| 157 |
maturity, and ABI stability policies. Please consult the documentation |
| 158 |
for your binding. |
| 159 |
|
| 160 |
Bootstrapping D-Bus on new platforms |
| 161 |
=== |
| 162 |
|
| 163 |
A full build of dbus, with all regression tests enabled and run, depends |
| 164 |
on GLib. A full build of GLib, with all regression tests enabled and run, |
| 165 |
depends on dbus. |
| 166 |
|
| 167 |
To break this cycle, don't enable full test coverage (for at least one |
| 168 |
of those projects) during bootstrapping. You can rebuild with full test |
| 169 |
coverage after you have built both dbus and GLib at least once. |