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