README

   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 http://www.freedesktop.org/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 dbus-security@lists.freedesktop.org
  38 or by reporting a freedesktop.org bug that is marked as
  39 restricted to the "D-BUS security group" (you might need to "Show
  40 Advanced Fields" to have that option).
  41
  42 On Unix systems, the system bus (dbus-daemon --system) is designed
  43 to be a security boundary between users with different privileges.
  44
  45 On Unix systems, the session bus (dbus-daemon --session) is designed
  46 to be used by a single user, and only accessible by that user.
  47
  48 We do not currently consider D-Bus on Windows to be security-supported,
  49 and we do not recommend allowing untrusted users to access Windows
  50 D-Bus via TCP.
  51
  52 Note: low-level API vs. high-level binding APIs
  53 ===
  54
  55 A core concept of the D-Bus implementation is that "libdbus" is
  56 intended to be a low-level API. Most programmers are intended to use
  57 the bindings to GLib, Qt, Python, Mono, Java, or whatever. These
  58 bindings have varying levels of completeness and are maintained as
  59 separate projects from the main D-Bus package. The main D-Bus package
  60 contains the low-level libdbus, the bus daemon, and a few command-line
  61 tools such as dbus-launch.
  62
  63 If you use the low-level API directly, you're signing up for some
  64 pain. Think of the low-level API as analogous to Xlib or GDI, and the
  65 high-level API as analogous to Qt/GTK+/HTML.
  66
  67 Version numbers
  68 ===
  69
  70 D-Bus uses the common "Linux kernel" versioning system, where
  71 even-numbered minor versions are stable and odd-numbered minor
  72 versions are development snapshots.
  73
  74 So for example, development snapshots: 1.1.1, 1.1.2, 1.1.3, 1.3.4
  75 Stable versions: 1.0, 1.0.1, 1.0.2, 1.2.1, 1.2.3
  76
  77 All pre-1.0 versions were development snapshots.
  78
  79 Development snapshots make no ABI stability guarantees for new ABI
  80 introduced since the last stable release. Development snapshots are
  81 likely to have more bugs than stable releases, obviously.
  82
  83 Configuration
  84 ===
  85
  86 dbus could be build by using autotools or cmake.
  87
  88 When using autotools the configure step is initiated by running ./configure
  89 with or without additional configuration flags. dbus requires GNU Make
  90 (on BSD systems, this is typically called gmake) or a "make" implementation
  91 with compatible extensions.
  92
  93 When using cmake the configure step is initiated by running the cmake
  94 program with or without additional configuration flags.
  95
  96 Configuration flags
  97 ===
  98
  99 When using autotools, run "./configure --help" to see the possible
 100 configuration options and environment variables.
 101
 102 When using cmake, inspect README.cmake to see the possible
 103 configuration options and environment variables.
 104
 105 API/ABI Policy
 106 ===
 107
 108 Now that D-Bus has reached version 1.0, the objective is that all
 109 applications dynamically linked to libdbus will continue working
 110 indefinitely with the most recent system and session bus daemons.
 111
 112  - The protocol will never be broken again; any message bus should
 113    work with any client forever. However, extensions are possible
 114    where the protocol is extensible.
 115
 116  - If the library API is modified incompatibly, we will rename it
 117    as in http://ometer.com/parallel.html - in other words,
 118    it will always be possible to compile against and use the older
 119    API, and apps will always get the API they expect.
 120
 121 Interfaces can and probably will be _added_. This means both new
 122 functions and types in libdbus, and new methods exported to
 123 applications by the bus daemon.
 124
 125 The above policy is intended to make D-Bus as API-stable as other
 126 widely-used libraries (such as GTK+, Qt, Xlib, or your favorite
 127 example). If you have questions or concerns they are very welcome on
 128 the D-Bus mailing list.
 129
 130 NOTE ABOUT DEVELOPMENT SNAPSHOTS AND VERSIONING
 131
 132 Odd-numbered minor releases (1.1.x, 1.3.x, 2.1.x, etc. -
 133 major.minor.micro) are devel snapshots for testing, and any new ABI
 134 they introduce relative to the last stable version is subject to
 135 change during the development cycle.
 136
 137 Any ABI found in a stable release, however, is frozen.
 138
 139 ABI will not be added in a stable series if we can help it. i.e. the
 140 ABI of 1.2.0 and 1.2.5 you can expect to be the same, while the ABI of
 141 1.4.x may add more stuff not found in 1.2.x.
 142
 143 NOTE ABOUT STATIC LINKING
 144
 145 We are not yet firmly freezing all runtime dependencies of the libdbus
 146 library. For example, the library may read certain files as part of
 147 its implementation, and these files may move around between versions.
 148
 149 As a result, we don't yet recommend statically linking to
 150 libdbus. Also, reimplementations of the protocol from scratch might
 151 have to work to stay in sync with how libdbus behaves.
 152
 153 To lock things down and declare static linking and reimplementation to
 154 be safe, we'd like to see all the internal dependencies of libdbus
 155 (for example, files read) well-documented in the specification, and
 156 we'd like to have a high degree of confidence that these dependencies
 157 are supportable over the long term and extensible where required.
 158
 159 NOTE ABOUT HIGH-LEVEL BINDINGS
 160
 161 Note that the high-level bindings are _separate projects_ from the
 162 main D-Bus package, and have their own release cycles, levels of
 163 maturity, and ABI stability policies. Please consult the documentation
 164 for your binding.
 165
 166 Bootstrapping D-Bus on new platforms
 167 ===
 168
 169 A full build of D-Bus, with all regression tests enabled and run, has some
 170 dependencies which themselves depend on D-Bus, either for compilation or
 171 for some of *their* regression tests: GLib, dbus-glib and dbus-python are
 172 currently affected.
 173
 174 To avoid circular dependencies, when bootstrapping D-Bus for the first time
 175 on a new OS or CPU architecture, you can either cross-compile some of
 176 those components, or choose the build order and options carefully:
 177
 178 * build and install D-Bus without tests
 179   - do not use the --enable-modular-tests=yes configure option
 180   - do not use the --enable-tests=yes configure option
 181 * build and install GLib, again without tests
 182 * use those versions of libdbus and GLib to build and install dbus-glib
 183 * ... and use those to install dbus-python
 184 * rebuild libdbus; this time you can run all of the tests
 185 * rebuild GLib; this time you can run all of the tests