From 151b3aaaeff42b76ecf4bd02aa28cda3ed98a501 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Tue, 7 Nov 2006 06:13:53 +0000 Subject: 2006-11-07 Havoc Pennington * doc/dbus-specification.xml, doc/dbus-faq.xml, README: various documentation updates. Bump faq/spec versions (not to 1.0; I don't think the spec will be "finished"/1.0 when we ship the 1.0 library). --- COPYING | 4 +- ChangeLog | 6 +++ README | 129 ++++++++++++++++++++++++++++++++++----------- doc/TODO | 2 + doc/dbus-faq.xml | 30 +++++++---- doc/dbus-specification.xml | 21 ++++++-- 6 files changed, 144 insertions(+), 48 deletions(-) diff --git a/COPYING b/COPYING index 19a5a9a9..a91ca1d1 100644 --- a/COPYING +++ b/COPYING @@ -3,8 +3,8 @@ License version 2.1, or the GNU General Public License version 2. Both licenses are included here. Some of the standalone binaries are under the GPL only; in particular, but not limited to, tools/dbus-cleanup-sockets.c and test/decode-gcov.c. Each source code -file is marked with the proper copyright information. - +file is marked with the proper copyright information - if you find a +file that isn't marked please bring it to our attention. The Academic Free License diff --git a/ChangeLog b/ChangeLog index 5a0312bd..7acefc26 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2006-11-07 Havoc Pennington + + * doc/dbus-specification.xml, doc/dbus-faq.xml, README: various + documentation updates. Bump faq/spec versions (not to 1.0; I don't + think the spec will be "finished"/1.0 when we ship the 1.0 library). + 2006-11-06 John (J5) Palmieri * bus/bus.c: Missed patch - pass in the context to the directory watch diff --git a/README b/README index 77047f77..02848904 100644 --- a/README +++ b/README @@ -1,17 +1,64 @@ -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. -See also the file HACKING for notes of interest to developers working on D-BUS. +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. -Note +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, similar to Xlib. Most programmers are -intended to use the bindings to GLib, Qt, Python, Mono, Java, or -whatever. These bindings have varying levels of completeness. +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 flags === @@ -48,15 +95,9 @@ the ./configure program. API/ABI Policy === -D-BUS API/ABI and protocol necessarily remain in flux until we are -sure it will meet the various needs it's intended to meet. This means -we need to see some significant sample usage in the contexts of GNOME, -KDE, desktop applications, and systemwide uses such as print queue -monitoring, hotplug events, or whatever. We need the flexibility to -incorporate feedback from this sample usage. - -Once we feel confident in the protocol and the API, we will release a -version 1.0. At that point, the intent is: +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 @@ -67,23 +108,47 @@ version 1.0. At that point, the intent is: it will always be possible to compile against and use the older API, and apps will always get the API they expect. -Until 1.0 is released, feedback that requires API changes may be -incorporated into D-BUS. This may break the API, the ABI, the -protocol, or all three. +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. -To avoid a huge soname, the plan is to increment the soname only -between official stable releases, not with every development snapshot. -Versions numbered 0.x are considered development snapshots. +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. -Until 1.0 is released, you have to define -DDBUS_API_SUBJECT_TO_CHANGE -just as a safety check to be sure everyone is aware of this API/ABI -policy and has the right expectations. +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. -We do need people to test the APIs, so please do use the development -snapshots of D-BUS. They are intended to work and we do actively -address bugs. +NOTE ABOUT HIGH-LEVEL BINDINGS -However, if you're shipping a commercial binary-only application that -needs to keep running on M future versions of N operating systems, you -might want to include your own copy of D-BUS rather than relying on -the installed copy, for example. +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. diff --git a/doc/TODO b/doc/TODO index ace86872..7b6e1191 100644 --- a/doc/TODO +++ b/doc/TODO @@ -8,6 +8,8 @@ Important for 1.0 - the spec should say "the protocol will not be changed incompatibly after Month DD, YYYY" + - the README documents the configure flags, should check this for being in sync with reality + Important for 1.0 GLib Bindings === diff --git a/doc/dbus-faq.xml b/doc/dbus-faq.xml index 47072e9e..07324049 100644 --- a/doc/dbus-faq.xml +++ b/doc/dbus-faq.xml @@ -7,8 +7,8 @@
D-Bus FAQ - Version 0.1 - 22 January 2005 + Version 0.2 + 07 November 2006 Havoc @@ -38,10 +38,14 @@ - This is probably best answered by reading the D-Bus tutorial. In + This is probably best answered by reading the D-Bus tutorial or + the introduction to the specification. In short, it is a system consisting of 1) a wire protocol for exposing a typical object-oriented language/framework to other applications; and 2) a bus daemon that allows applications to find and monitor one another. + Phrased differently, D-Bus is 1) an interprocess communication (IPC) system and 2) some higher-level + structure (lifecycle tracking, service activation, security policy) provided by two bus daemons, + one systemwide and one per-user-session. @@ -54,12 +58,13 @@ - D-Bus has not yet reached 1.0. The README - file has a discussion of the API/ABI stability guarantees before and - after 1.0. In short, there are no guarantees before 1.0, and stability - of both protocol and reference library will be maintained after 1.0. - As of January 2005 we don't expect major protocol or API changes prior - to the 1.0 release, but anything is possible. + The low-level library "libdbus" and the protocol specification are considered + ABI stable. The README + file has a discussion of the API/ABI stability guarantees. + Higher-level bindings (such as those for Qt, GLib, Python, Java, C#) each + have their own release schedules and degree of maturity, not linked to + the low-level library and bus daemon release. Check the project page for + the binding you're considering to understand that project's policies. @@ -144,6 +149,13 @@ are normally launched according to the bus name they will have. + + People often misuse the word "service" for any + bus name, but this tends to be ambiguous and confusing so is discouraged. + In the D-Bus docs we try to use "service" only when talking about + programs the bus knows how to launch, i.e. a service always has a + .service file. + diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 1e4ac4f5..e1b02f38 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -7,8 +7,8 @@
D-Bus Specification - Version 0.11 - 6 February 2005 + Version 0.12 + 7 November 2006 Havoc @@ -114,9 +114,20 @@ D-Bus is not intended to be a generic IPC system for any possible application, and intentionally omits many features found in other - IPC systems for this reason. D-Bus may turn out to be useful - in unanticipated applications, but future versions of this - spec and the reference implementation probably will not + IPC systems for this reason. + + + + At the same time, the bus daemons offer a number of features not found in + other IPC systems, such as single-owner "bus names" (similar to X + selections), on-demand startup of services, and security policies. + In many ways, these features are the primary motivation for developing + D-Bus; other systems would have sufficed if IPC were the only goal. + + + + D-Bus may turn out to be useful in unanticipated applications, but future + versions of this spec and the reference implementation probably will not incorporate features that interfere with the core use cases. -- cgit v1.2.1