-D-BUS is a simple IPC library based on messages.
+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.
projects / platform / upstream / dbus.git / blobdiff