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