X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=README;h=fd832ca94b8e677f28a8952270468ba1c956d764;hb=3ccb027c907f9ee2890028e83b60296204bbf478;hp=4ac8cb244d9d9189af2a37d72a0657732da1f51f;hpb=ea4bf5322b6b282cf1a334d26cb86d2aa500d603;p=platform%2Fupstream%2Fdbus.git diff --git a/README b/README index 4ac8cb2..fd832ca 100644 --- a/README +++ b/README @@ -1,52 +1,163 @@ -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 -Configuration flags +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 === -These are the configuration flags that can be given to the ./configure program. +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 ---enable-qt enable Qt-friendly client library ---enable-glib enable GLib-friendly client library ---enable-tests enable unit test code ---enable-ansi enable -ansi -pedantic gcc flags ---enable-verbose-mode support verbose debug mode ---enable-asserts include assertion checks ---enable-gcov compile with coverage profiling instrumentation (gcc only) +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. -Environment variables +Configuration === -These are the environment variables that are used by the D-BUS client library +dbus could be build by using autotools or cmake. -DBUS_VERBOSE=1 -Turns on printing verbose messages. This only works if D-BUS has been -compiled with --enable-verbose-mode +When using autotools the configure step is initiated by running ./configure +with or without additional configuration flags. -DBUS_MALLOC_FAIL_NTH=n -Can be set to a number, causing every nth call to dbus_alloc or -dbus_realloc to fail. This only works if D-BUS has been compiled with ---enable-tests. +When using cmake the configure step is initiated by running the cmake +program with or without additional configuration flags. -DBUS_MALLOC_FAIL_GREATER_THAN=n -Can be set to a number, causing every call to dbus_alloc or -dbus_realloc to fail if the number of bytes to be allocated is greater -than the specified number. This only works if D-BUS has been compiled with ---enable-tests. +Configuration flags +=== +When using autotools, run "./configure --help" to see the possible +configuration options and environment variables. -Tests +When using cmake, inspect README.cmake to see the possible +configuration options and environment variables. + +API/ABI Policy === -These are the test programs that are built if dbus is compiled using ---enable-tests. +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. + +Bootstrapping D-Bus on new platforms +=== -dbus/dbus-test -This is the main unit test program that tests all aspects of the D-BUS -client library. +A full build of D-Bus, with all regression tests enabled and run, has some +dependencies which themselves depend on D-Bus, either for compilation or +for some of *their* regression tests: GLib, dbus-glib and dbus-python are +currently affected. -test/break-loader -A test that tries to break the message loader by passing it invalid messages. +To avoid circular dependencies, when bootstrapping D-Bus for the first time +on a new OS or CPU architecture, you can either cross-compile some of +those components, or choose the build order and options carefully: -test/bus-test -A test that simulates a bus daemon and tests it. +* build and install D-Bus without tests + - do not use the --enable-modular-tests=yes configure option + - do not use the --enable-tests=yes configure option +* build and install GLib, again without tests +* use those versions of libdbus and GLib to build and install dbus-glib +* ... and use those to install dbus-python +* rebuild libdbus; this time you can run all of the tests +* rebuild GLib; this time you can run all of the tests