mirror of
https://gitlab.freedesktop.org/dbus/dbus.git
synced 2025-12-24 21:40:07 +01:00
9a97f82079
Reviewed-by: Colin Walters <walters@verbum.org> Bug: https://bugs.freedesktop.org/show_bug.cgi?id=10887
185 lines
8.3 KiB
Text
185 lines
8.3 KiB
Text
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-compiler-coverage 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.
|