Debian Codegraph @

README

raw
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.