Emeric Vigier | 2f62582 | 2012-08-06 11:09:52 -0400 | [diff] [blame] | 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 our without additional configuration flags. |
| 70 | |
| 71 | When using cmake the configure step is initiated by running the cmake |
| 72 | program with our without additional configuration flags. |
| 73 | |
| 74 | Configuration flags |
| 75 | === |
| 76 | |
| 77 | When using autools the dbus-specific configuration flags that can be given to |
| 78 | the ./configure program are these |
| 79 | |
| 80 | --enable-tests enable unit test code |
| 81 | --enable-verbose-mode support verbose debug mode |
| 82 | --enable-asserts include assertion checks |
| 83 | --enable-checks include sanity checks on public API |
| 84 | --enable-xml-docs build XML documentation (requires xmlto) |
| 85 | --enable-doxygen-docs build DOXYGEN documentation (requires Doxygen) |
| 86 | --enable-gcov compile with coverage profiling instrumentation (gcc only) |
| 87 | --enable-abstract-sockets use abstract socket namespace (linux only) |
| 88 | --enable-selinux build with SELinux support |
| 89 | --enable-dnotify build with dnotify support (linux only) |
| 90 | --enable-kqueue build with kqueue support (*BSD only) |
| 91 | --with-xml=libxml/expat XML library to use |
| 92 | --with-init-scripts=redhat Style of init scripts to install |
| 93 | --with-session-socket-dir=dirname Where to put sockets for the per-login-session message bus |
| 94 | --with-test-socket-dir=dirname Where to put sockets for make check |
| 95 | --with-system-pid-file=pidfile PID file for systemwide daemon |
| 96 | --with-system-socket=filename UNIX domain socket for systemwide daemon |
| 97 | --with-console-auth-dir=dirname directory to check for console ownerhip |
| 98 | --with-dbus-user=<user> User for running the DBUS daemon (messagebus) |
| 99 | --with-gnu-ld assume the C compiler uses GNU ld [default=no] |
| 100 | --with-tags[=TAGS] include additional configurations [automatic] |
| 101 | --with-x use the X Window System |
| 102 | |
| 103 | When using the cmake build system the dbus-specific configuration flags that can be given |
| 104 | to the cmake program are these (use -D<key>=<value> on command line) |
| 105 | |
| 106 | CMAKE_BUILD_TYPE set dbus build mode - one of Debug|Release|RelWithDebInfo|MinSizeRel |
| 107 | DBUS_BUILD_TESTS enable unit test code default=ON |
| 108 | DBUS_BUILD_X11 Build X11-dependent code default=ON |
| 109 | HAVE_CONSOLE_OWNER_FILE enable console owner file (solaris only) ) default=ON |
| 110 | DBUS_DISABLE_ASSERTS Disable assertion checking default=OFF |
| 111 | DBUS_DISABLE_CHECKS Disable public API sanity checking default=OFF |
| 112 | DBUS_ENABLE_ABSTRACT_SOCKETS enable support for abstract sockets (linux only) default=ON |
| 113 | DBUS_ENABLE_ANSI enable -ansi -pedantic gcc flags default=OFF |
| 114 | DBUS_ENABLE_DNOTIFY build with dnotify support (linux only) default=ON |
| 115 | DBUS_ENABLE_VERBOSE_MODE support verbose debug mode default=ON |
| 116 | DBUS_ENABLE_DOXYGEN_DOCS build DOXYGEN documentation (requires Doxygen) default=ON |
| 117 | DBUS_GCOV_ENABLED compile with coverage profiling instrumentation (gcc only) default=OFF |
| 118 | DBUS_INSTALL_SYSTEM_LIBS install required system libraries default (windows only) =OFF |
| 119 | DBUS_USE_EXPAT Use expat (== ON) or libxml2 (==OFF) default=ON [1] |
| 120 | DBUS_USE_NONCE_TCP_DEFAULT_ADDRESS Use nonce tcp default address default=OFF |
| 121 | DBUS_USE_OUTPUT_DEBUG_STRING enable win32 debug port for message output default=OFF |
| 122 | |
| 123 | [1] requires installed development package of the related dependency |
| 124 | |
| 125 | |
| 126 | API/ABI Policy |
| 127 | === |
| 128 | |
| 129 | Now that D-Bus has reached version 1.0, the objective is that all |
| 130 | applications dynamically linked to libdbus will continue working |
| 131 | indefinitely with the most recent system and session bus daemons. |
| 132 | |
| 133 | - The protocol will never be broken again; any message bus should |
| 134 | work with any client forever. However, extensions are possible |
| 135 | where the protocol is extensible. |
| 136 | |
| 137 | - If the library API is modified incompatibly, we will rename it |
| 138 | as in http://ometer.com/parallel.html - in other words, |
| 139 | it will always be possible to compile against and use the older |
| 140 | API, and apps will always get the API they expect. |
| 141 | |
| 142 | Interfaces can and probably will be _added_. This means both new |
| 143 | functions and types in libdbus, and new methods exported to |
| 144 | applications by the bus daemon. |
| 145 | |
| 146 | The above policy is intended to make D-Bus as API-stable as other |
| 147 | widely-used libraries (such as GTK+, Qt, Xlib, or your favorite |
| 148 | example). If you have questions or concerns they are very welcome on |
| 149 | the D-Bus mailing list. |
| 150 | |
| 151 | NOTE ABOUT DEVELOPMENT SNAPSHOTS AND VERSIONING |
| 152 | |
| 153 | Odd-numbered minor releases (1.1.x, 1.3.x, 2.1.x, etc. - |
| 154 | major.minor.micro) are devel snapshots for testing, and any new ABI |
| 155 | they introduce relative to the last stable version is subject to |
| 156 | change during the development cycle. |
| 157 | |
| 158 | Any ABI found in a stable release, however, is frozen. |
| 159 | |
| 160 | ABI will not be added in a stable series if we can help it. i.e. the |
| 161 | ABI of 1.2.0 and 1.2.5 you can expect to be the same, while the ABI of |
| 162 | 1.4.x may add more stuff not found in 1.2.x. |
| 163 | |
| 164 | NOTE ABOUT STATIC LINKING |
| 165 | |
| 166 | We are not yet firmly freezing all runtime dependencies of the libdbus |
| 167 | library. For example, the library may read certain files as part of |
| 168 | its implementation, and these files may move around between versions. |
| 169 | |
| 170 | As a result, we don't yet recommend statically linking to |
| 171 | libdbus. Also, reimplementations of the protocol from scratch might |
| 172 | have to work to stay in sync with how libdbus behaves. |
| 173 | |
| 174 | To lock things down and declare static linking and reimplementation to |
| 175 | be safe, we'd like to see all the internal dependencies of libdbus |
| 176 | (for example, files read) well-documented in the specification, and |
| 177 | we'd like to have a high degree of confidence that these dependencies |
| 178 | are supportable over the long term and extensible where required. |
| 179 | |
| 180 | NOTE ABOUT HIGH-LEVEL BINDINGS |
| 181 | |
| 182 | Note that the high-level bindings are _separate projects_ from the |
| 183 | main D-Bus package, and have their own release cycles, levels of |
| 184 | maturity, and ABI stability policies. Please consult the documentation |
| 185 | for your binding. |