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