| Sections in this file describe: |
| - introduction and overview |
| - low-level vs. high-level API |
| - version numbers |
| - options to the configure script |
| - ABI stability policy |
| |
| Introduction |
| === |
| |
| D-Bus is a simple system for interprocess communication and coordination. |
| |
| The "and coordination" part is important; D-Bus provides a bus daemon that does things like: |
| - notify applications when other apps exit |
| - start services on demand |
| - support single-instance applications |
| |
| See http://www.freedesktop.org/software/dbus/ for lots of documentation, |
| mailing lists, etc. |
| |
| See also the file HACKING for notes of interest to developers working on D-Bus. |
| |
| If you're considering D-Bus for use in a project, you should be aware |
| that D-Bus was designed for a couple of specific use cases, a "system |
| bus" and a "desktop session bus." These are documented in more detail |
| in the D-Bus specification and FAQ available on the web site. |
| |
| If your use-case isn't one of these, D-Bus may still be useful, but |
| only by accident; so you should evaluate carefully whether D-Bus makes |
| sense for your project. |
| |
| Note: low-level API vs. high-level binding APIs |
| === |
| |
| A core concept of the D-Bus implementation is that "libdbus" is |
| intended to be a low-level API. Most programmers are intended to use |
| the bindings to GLib, Qt, Python, Mono, Java, or whatever. These |
| bindings have varying levels of completeness and are maintained as |
| separate projects from the main D-Bus package. The main D-Bus package |
| contains the low-level libdbus, the bus daemon, and a few command-line |
| tools such as dbus-launch. |
| |
| If you use the low-level API directly, you're signing up for some |
| pain. Think of the low-level API as analogous to Xlib or GDI, and the |
| high-level API as analogous to Qt/GTK+/HTML. |
| |
| Version numbers |
| === |
| |
| D-Bus uses the common "Linux kernel" versioning system, where |
| even-numbered minor versions are stable and odd-numbered minor |
| versions are development snapshots. |
| |
| So for example, development snapshots: 1.1.1, 1.1.2, 1.1.3, 1.3.4 |
| Stable versions: 1.0, 1.0.1, 1.0.2, 1.2.1, 1.2.3 |
| |
| All pre-1.0 versions were development snapshots. |
| |
| Development snapshots make no ABI stability guarantees for new ABI |
| introduced since the last stable release. Development snapshots are |
| likely to have more bugs than stable releases, obviously. |
| |
| Configuration |
| === |
| |
| dbus could be build by using autotools or cmake. |
| |
| When using autotools the configure step is initiated by running ./configure |
| with our without additional configuration flags. |
| |
| When using cmake the configure step is initiated by running the cmake |
| program with our without additional configuration flags. |
| |
| Configuration flags |
| === |
| |
| When using autools the dbus-specific configuration flags that can be given to |
| the ./configure program are these |
| |
| --enable-tests enable unit test code |
| --enable-verbose-mode support verbose debug mode |
| --enable-asserts include assertion checks |
| --enable-checks include sanity checks on public API |
| --enable-xml-docs build XML documentation (requires xmlto) |
| --enable-doxygen-docs build DOXYGEN documentation (requires Doxygen) |
| --enable-gcov compile with coverage profiling instrumentation (gcc only) |
| --enable-abstract-sockets use abstract socket namespace (linux only) |
| --enable-selinux build with SELinux support |
| --enable-dnotify build with dnotify support (linux only) |
| --enable-kqueue build with kqueue support (*BSD only) |
| --with-xml=libxml/expat XML library to use |
| --with-init-scripts=redhat Style of init scripts to install |
| --with-session-socket-dir=dirname Where to put sockets for the per-login-session message bus |
| --with-test-socket-dir=dirname Where to put sockets for make check |
| --with-system-pid-file=pidfile PID file for systemwide daemon |
| --with-system-socket=filename UNIX domain socket for systemwide daemon |
| --with-console-auth-dir=dirname directory to check for console ownerhip |
| --with-dbus-user=<user> User for running the DBUS daemon (messagebus) |
| --with-gnu-ld assume the C compiler uses GNU ld [default=no] |
| --with-tags[=TAGS] include additional configurations [automatic] |
| --with-x use the X Window System |
| |
| When using the cmake build system the dbus-specific configuration flags that can be given |
| to the cmake program are these (use -D<key>=<value> on command line) |
| |
| CMAKE_BUILD_TYPE set dbus build mode - one of Debug|Release|RelWithDebInfo|MinSizeRel |
| DBUS_BUILD_TESTS enable unit test code default=ON |
| DBUS_BUILD_X11 Build X11-dependent code default=ON |
| HAVE_CONSOLE_OWNER_FILE enable console owner file (solaris only) ) default=ON |
| DBUS_DISABLE_ASSERTS Disable assertion checking default=OFF |
| DBUS_DISABLE_CHECKS Disable public API sanity checking default=OFF |
| DBUS_ENABLE_ABSTRACT_SOCKETS enable support for abstract sockets (linux only) default=ON |
| DBUS_ENABLE_ANSI enable -ansi -pedantic gcc flags default=OFF |
| DBUS_ENABLE_DNOTIFY build with dnotify support (linux only) default=ON |
| DBUS_ENABLE_VERBOSE_MODE support verbose debug mode default=ON |
| DBUS_ENABLE_DOXYGEN_DOCS build DOXYGEN documentation (requires Doxygen) default=ON |
| DBUS_GCOV_ENABLED compile with coverage profiling instrumentation (gcc only) default=OFF |
| DBUS_INSTALL_SYSTEM_LIBS install required system libraries default (windows only) =OFF |
| DBUS_USE_EXPAT Use expat (== ON) or libxml2 (==OFF) default=ON [1] |
| DBUS_USE_NONCE_TCP_DEFAULT_ADDRESS Use nonce tcp default address default=OFF |
| DBUS_USE_OUTPUT_DEBUG_STRING enable win32 debug port for message output default=OFF |
| |
| [1] requires installed development package of the related dependency |
| |
| |
| API/ABI Policy |
| === |
| |
| Now that D-Bus has reached version 1.0, the objective is that all |
| applications dynamically linked to libdbus will continue working |
| indefinitely with the most recent system and session bus daemons. |
| |
| - The protocol will never be broken again; any message bus should |
| work with any client forever. However, extensions are possible |
| where the protocol is extensible. |
| |
| - If the library API is modified incompatibly, we will rename it |
| as in http://ometer.com/parallel.html - in other words, |
| it will always be possible to compile against and use the older |
| API, and apps will always get the API they expect. |
| |
| Interfaces can and probably will be _added_. This means both new |
| functions and types in libdbus, and new methods exported to |
| applications by the bus daemon. |
| |
| The above policy is intended to make D-Bus as API-stable as other |
| widely-used libraries (such as GTK+, Qt, Xlib, or your favorite |
| example). If you have questions or concerns they are very welcome on |
| the D-Bus mailing list. |
| |
| NOTE ABOUT DEVELOPMENT SNAPSHOTS AND VERSIONING |
| |
| Odd-numbered minor releases (1.1.x, 1.3.x, 2.1.x, etc. - |
| major.minor.micro) are devel snapshots for testing, and any new ABI |
| they introduce relative to the last stable version is subject to |
| change during the development cycle. |
| |
| Any ABI found in a stable release, however, is frozen. |
| |
| ABI will not be added in a stable series if we can help it. i.e. the |
| ABI of 1.2.0 and 1.2.5 you can expect to be the same, while the ABI of |
| 1.4.x may add more stuff not found in 1.2.x. |
| |
| NOTE ABOUT STATIC LINKING |
| |
| We are not yet firmly freezing all runtime dependencies of the libdbus |
| library. For example, the library may read certain files as part of |
| its implementation, and these files may move around between versions. |
| |
| As a result, we don't yet recommend statically linking to |
| libdbus. Also, reimplementations of the protocol from scratch might |
| have to work to stay in sync with how libdbus behaves. |
| |
| To lock things down and declare static linking and reimplementation to |
| be safe, we'd like to see all the internal dependencies of libdbus |
| (for example, files read) well-documented in the specification, and |
| we'd like to have a high degree of confidence that these dependencies |
| are supportable over the long term and extensible where required. |
| |
| NOTE ABOUT HIGH-LEVEL BINDINGS |
| |
| Note that the high-level bindings are _separate projects_ from the |
| main D-Bus package, and have their own release cycles, levels of |
| maturity, and ABI stability policies. Please consult the documentation |
| for your binding. |