diff --git a/doc/Makefile.am b/doc/Makefile.am
index 7df331c5..11f7db96 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,5 @@
EXTRA_DIST= \
+ dbus-faq.xml \
dbus-specification.xml \
dbus-test-plan.xml \
dbus-tutorial.xml \
@@ -6,6 +7,7 @@ EXTRA_DIST= \
file-boilerplate.c
HTML_FILES= \
+ dbus-faq.html \
dbus-specification.html \
dbus-test-plan.html \
dbus-tutorial.html
@@ -23,6 +25,10 @@ dbus-test-plan.html: dbus-test-plan.xml
dbus-tutorial.html: dbus-tutorial.xml
$(XMLTO) html-nochunks $<
+
+dbus-faq.html: dbus-faq.xml
+ $(XMLTO) html-nochunks $<
+
endif
maintainer-clean-local:
diff --git a/doc/dbus-faq.xml b/doc/dbus-faq.xml
new file mode 100644
index 00000000..773acee7
--- /dev/null
+++ b/doc/dbus-faq.xml
@@ -0,0 +1,649 @@
+
+
+
+
+
+ D-BUS FAQ
+ Version 0.1
+ 22 January 2005
+
+
+ Havoc
+ Pennington
+
+ Red Hat, Inc.
+
+ hp@pobox.com
+
+
+
+
+ David
+ Wheeler
+
+
+
+
+
+
+
+
+
+ What is D-BUS?
+
+
+
+
+ This is probably best answered by reading the D-BUS tutorial. 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.
+
+
+
+
+
+
+
+ Is D-BUS stable/finished?
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+ How is the reference implementation licensed? Can I use it in
+ proprietary applications?
+
+
+
+
+ The short answer is yes, you can use it in proprietary applications.
+ You should read the COPYING file, which
+ offers you the choice of two licenses. These are the GPL and the
+ AFL. The GPL requires that your application be licensed under the GPL
+ as well. The AFL is an "X-style" or "BSD-style" license compatible
+ with proprietary licensing, but it does have some requirements; in
+ particular it prohibits you from filing a lawsuit alleging that the
+ D-BUS software infringes your patents while you continue to
+ use D-BUS. If you're going to sue, you have to stop using
+ the software. Read the licenses to determine their meaning, this FAQ
+ entry is not intended to change the meaning or terms of the licenses.
+
+
+
+
+
+
+
+ What is the difference between a bus name, and object path,
+ and an interface?
+
+
+
+
+ If you imagine a C++ program that implements a network
+ service, then the bus name is the domain name
+ of the computer running this C++ program, the object path
+ is a C++ object instance pointer, and an interface is a C++
+ class (a pure virtual or abstract class, to be exact).
+
+
+ In Java terms, the object path is an object reference,
+ and an interface is a Java interface.
+
+
+ People get confused because if they write an application
+ with a single object instance and a single interface,
+ then the bus name, object path, and interface look
+ redundant. For example, you might have a text editor
+ that uses the bus name org.freedesktop.TextEditor,
+ has a global singleton object called
+ /org/freedesktop/TextEditor, and
+ that singleton object could implement the interface
+ org.freedesktop.TextEditor.
+
+
+ However, a text editor application could as easily own multiple bus
+ names (for example, org.kde.KWrite), have multiple
+ objects (maybe /org/kde/documents/4352),
+ and each object could implement multiple interfaces,
+ such as org.freedesktop.Introspectable,
+ org.freedesktop.BasicTextField,
+ org.kde.RichTextDocument.
+
+
+
+
+
+
+
+
+ What is a "service"?
+
+
+
+
+ A service is a program that can be launched by the bus daemon
+ to provide some functionality to other programs. Services
+ are normally launched according to the bus name they will
+ have.
+
+
+
+
+
+
+
+ Is D-BUS a "component system"?
+
+
+
+
+ D-BUS is not a component system. "Component system" was originally
+ defined by COM, and was essentially a workaround for the limitations
+ of the C++ object system (adding introspection, runtime location of
+ objects, ABI guarantees, and so forth). With the C# language and CLR,
+ Microsoft added these features to the primary object system, leaving
+ COM obsolete. Similarly, Java has much less need for something like
+ COM than C++ did. Even QObject (from Qt) and GObject (from GLib) offer
+ some of the same features found in COM.
+
+
+ Component systems are not about GUI control embedding. Embedding
+ a spreadsheet in a word processor document is a matter of defining
+ some specific interfaces that objects
+ can implement. These interfaces provide methods related to
+ GUI controls. So an object implementing those interfaces
+ can be embedded.
+
+
+ The word "component" just means "object with some fancy features" and
+ in modern languages all objects are effectively "components."
+
+
+ A third, orthogonal feature is interprocess communication or IPC.
+ D-BUS is an IPC system. Given an object (or "component" if you must),
+ you can expose the functionality of that object over an IPC system.
+ Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-BUS.
+ You can use any of these IPC systems with any object/component system,
+ though some of them are "tuned" for specific object systems.
+ You can think of an IPC system primarily as a wire protocol.
+
+
+ If you combine an IPC system with a set of GUI control interfaces,
+ then you can have an out-of-process or dynamically-loaded GUI control.
+
+
+ Summarizing, there are three orthogonal things:
+
+
+
+ Object/component system
+
+
+
+
+ Control embedding interfaces
+
+
+
+
+ Interprocess communication system or wire protocol
+
+
+
+
+
+ Another related concept is the plugin or
+ extension. Generic plugin systems such as the
+ Eclipse system are not so different
+ from component/object systems, though perhaps a "plugin" tends to be a
+ bundle of objects with a user-visible name and can be
+ downloaded/packaged as a unit.
+
+
+
+
+
+
+
+ How fast is the D-BUS reference implementation?
+
+
+
+
+ Of course it depends a bit on what you're doing.
+
+ This mail contains some benchmarking. At the time of that
+ benchmark, D-BUS one-to-one communication was about 2.5x slower than
+ simply pushing the data raw over a socket. After the recent rewrite of
+ the marshaling code, D-BUS is slower than that because a lot of
+ optimization work was lost. But it can probably be sped up again.
+
+
+ D-BUS communication with the intermediate bus daemon should be
+ (and as last profiled, was) about twice as slow as one-to-one
+ mode, because a round trip involves four socket reads/writes rather
+ than two socket reads/writes.
+
+
+ The overhead comes from a couple of places; part of it is simply
+ "abstraction penalty" (there are layers of code to support
+ multiple main loops, multiple transport types, security, etc.).
+ Probably the largest part comes from data validation
+ (because the reference implementation does not trust incoming data).
+ It would be simple to add a "no validation" mode, but probably
+ not a good idea all things considered.
+
+
+ Raw bandwidth isn't the only concern; D-BUS is designed to
+ enable asynchronous communication and avoid round trips.
+ This is frequently a more important performance issue
+ than throughput.
+
+
+
+
+
+
+
+
+ How large is the D-BUS reference implementation?
+
+
+
+
+ A production build (with assertions, unit tests, and verbose logging
+ disabled) is on the order of a 150K shared library.
+
+
+ A much, much smaller implementation would be possible by omitting out
+ of memory handling, hardcoding a main loop (or always using blocking
+ I/O), skipping validation, and otherwise simplifying things.
+
+
+
+
+
+
+
+ How does D-BUS differ from other interprocess communication
+ or networking protocols?
+
+
+
+
+ The best place to start is to read the D-BUS tutorial, so
+ you have a concrete idea what D-BUS actually is. If you
+ understand other protocols on a wire format level, you
+ may also want to read the D-BUS specification to see what
+ D-BUS looks like on a low level.
+
+
+ As the tutorial and specification both explain, D-BUS is tuned
+ for some specific use cases. Thus, it probably isn't tuned
+ for what you want to do, unless you are doing the things
+ D-BUS was designed for. Don't make the mistake of thinking
+ that any system labeled "IPC" is the same thing.
+
+
+ The D-BUS authors would not recommend using D-BUS
+ for applications where it doesn't make sense.
+ The following questions compare D-BUS to some other
+ protocols primarily to help you understand D-BUS
+ and decide whether it's appropriate; D-BUS is neither intended
+ nor claimed to be the right choice for every application.
+
+
+ It should be possible to bridge D-BUS to other IPC systems,
+ just as D-BUS can be bridged to object systems.
+
+
+ Note: the D-BUS mailing list subscribers are very much not
+ interested in debating which IPC system is the One True
+ System. So if you want to discuss that, please use another forum.
+
+
+
+
+
+
+
+
+ How does D-BUS differ from CORBA?
+
+
+
+
+ Start by reading .
+
+
+ CORBA is designed to support
+ object-oriented IPC between objects, automatically marshalling
+ parameters as necessary. CORBA is strongly supported by the Open Management Group (OMG), which
+ produces various standards and supporting documents for CORBA and has
+ the backing of many large organizations. There are many CORBA ORBs
+ available, both proprietary ORBs and free / open source software ORBs
+ (the latter include ORBit, MICO, and The ACE Orb (TAO)). Many
+ organizations continue to use CORBA ORBs for various kinds of IPC.
+
+
+ Both GNOME and KDE have used CORBA and then moved away from it. KDE
+ had more success with a system called DCOP, and GNOME layered a system
+ called Bonobo on top of CORBA. Without custom extensions, CORBA does
+ not support many of the things one wants to do in a desktop
+ environment with the GNOME/KDE architecture.
+
+
+ CORBA on the other hand has a number of features of interest for
+ enterprise and web application development, though XML systems such as
+ SOAP are the latest fad.
+
+
+ Like D-BUS, CORBA uses a fast binary protocol (IIOP). Both systems
+ work in terms of objects and methods, and have concepts such as
+ "oneway" calls. Only D-BUS has direct support for "signals" as in
+ GLib/Qt (or Java listeners, or C# delegates).
+
+
+ D-BUS hardcodes and specifies a lot of things that CORBA leaves open-ended,
+ because CORBA is more generic and D-BUS has two specific use-cases in mind.
+ This makes D-BUS a bit simpler.
+
+
+ However, unlike CORBA D-BUS does not specify the
+ API for the language bindings. Instead, "native" bindings adapted
+ specifically to the conventions of a framework such as QObject,
+ GObject, C#, Java, Python, etc. are encouraged. The libdbus reference
+ implementation is designed to be a backend for bindings of this
+ nature, rather than to be used directly. The rationale is that an IPC
+ system API should not "leak" all over a program; it should come into
+ play only just before data goes over the wire. As an aside, OMG is
+ apparently working on a simpler C++ binding for CORBA.
+
+
+ Many CORBA implementations such as ORBit are faster than the libdbus
+ reference implementation. One reason is that D-BUS considers data
+ from the other end of the connection to be untrusted and extensively
+ validates it. But generally speaking other priorities were placed
+ ahead of raw speed in the libdbus implementation. A fast D-BUS
+ implementation along the lines of ORBit should be possible, of course.
+
+
+ On a more trivial note, D-BUS involves substantially fewer acronyms
+ than CORBA.
+
+
+
+
+
+
+
+
+ How does D-BUS differ from XML-RPC and SOAP?
+
+
+
+
+ Start by reading .
+
+
+ In SOAP and XML-RPC, RPC calls are transformed
+ into an XML-based format, then sent over the wire (typically using the
+ HTTP protocol), where they are processed and returned. XML-RPC is the
+ simple protocol (its spec is only a page or two), and SOAP is the
+ full-featured protocol.
+
+
+ XML-RPC and SOAP impose XML parsing overhead that is normally
+ irrelevant in the context of the Internet, but significant for
+ constant fine-grained IPC among applications in a desktop session.
+
+
+ D-BUS offers persistent connections and with the bus daemon
+ supports lifecycle tracking of other applications connected
+ to the bus. With XML-RPC and SOAP, typically each method call
+ exists in isolation and has its own HTTP connection.
+
+
+
+
+
+
+
+ How does D-BUS differ from DCE?
+
+
+
+
+ Start by reading .
+
+
+ Distributed Computing
+ Environment (DCE) is an industry-standard vendor-neutral
+ standard that includes an IPC mechanism. The Open Group
+ has released an implementation as open source software. DCE
+ is quite capable, and includes a vast amount of functionality such as
+ a distributed time service. As the name implies, DCE is intended for
+ use in a large, multi-computer distributed application. D-BUS would
+ not be well-suited for this.
+
+
+
+
+
+
+
+
+ How does D-BUS differ from DCOM and COM?
+
+
+
+
+ Start by reading .
+
+
+ Comparing D-BUS to COM is apples and oranges;
+ see .
+
+
+ DCOM (distributed COM) is a Windows IPC system designed for use with
+ the COM object system. It's similar in some ways to DCE and CORBA.
+
+
+
+
+
+
+
+ How does D-BUS differ from ZeroC's Internet Communications Engine (Ice)
+
+
+
+
+ Start by reading .
+
+
+ The Internet
+ Communications Engine (Ice) is a powerful IPC mechanism more
+ on the level of SOAP or CORBA than D-BUS. Ice has a "dual-license"
+ business around it; i.e. you can use it under the GPL, or pay for a
+ proprietary license.
+
+
+
+
+
+
+
+ How does D-BUS differ from Inter-Client Exchange (ICE)?
+
+
+
+
+ ICE
+ was developed for the X Session Management protocol (XSMP), as part of
+ the X Window System (X11R6.1). The idea was to allow desktop sessions
+ to contain nongraphical clients in addition to X clients.
+
+
+ ICE is a binary protocol designed for desktop use, and KDE's DCOP
+ builds on ICE. ICE is substantially simpler than D-BUS (in contrast
+ to most of the other IPC systems mentioned here, which are more
+ complex). ICE doesn't really define a mapping to objects and methods
+ (DCOP adds that layer). The reference implementation of ICE (libICE)
+ is often considered to be horrible (and horribly insecure).
+
+
+ DCOP and XSMP are the only two widely-used applications of ICE,
+ and both could in principle be replaced by D-BUS. (Though whether
+ GNOME and KDE will bother is an open question.)
+
+
+
+
+
+
+
+
+
+ How does D-BUS differ from DCOP?
+
+
+
+
+ Start by reading .
+
+
+ D-BUS is intentionally pretty similar to DCOP,
+ and can be thought of as a "DCOP the next generation" suitable for
+ sharing between the various open source desktop projects.
+
+
+ D-BUS is a bit more complex than DCOP, though the Qt binding for D-BUS
+ should not be more complex for programmers. The additional complexity
+ of D-BUS arises from its separation of object references vs. bus names
+ vs. interfaces as distinct concepts, and its support for one-to-one
+ connections in addition to connections over the bus. The libdbus
+ reference implementation has a lot of API to support multiple bindings
+ and main loops, and performs data validation and out-of-memory handling
+ in order to support secure applications such as the systemwide bus.
+
+
+ D-BUS is probably somewhat slower than DCOP due to data validation
+ and more "layers" in the reference implementation. A comparison
+ hasn't been posted to the list though.
+
+
+ At this time, KDE has not committed to using D-BUS, but there have
+ been discussions of KDE bridging D-BUS and DCOP, or even changing
+ DCOP's implementation to use D-BUS internally (so that GNOME and KDE
+ would end up using exactly the same bus). See the KDE mailing list
+ archives for some of these discussions.
+
+
+
+
+
+
+
+
+ How does D-BUS differ from [yet more IPC mechanisms]?
+
+
+
+
+ Start by reading .
+
+
+ There are countless uses of network sockets in the world. MBUS, Sun ONC/RPC, Jabber/XMPP,
+ SIP, are some we can think of quickly.
+
+
+
+
+
+
+
+
+ Which IPC mechanism should I use?
+
+
+
+
+ Start by reading .
+
+
+ If you're writing an Internet or Intranet application, XML-RPC or SOAP
+ work for many people. These are standard, available for most
+ languages, simple to debug and easy to use.
+
+
+ If you're writing a desktop application for UNIX,
+ then D-BUS is of course our recommendation for
+ talking to other parts of the desktop session.
+ (With the caveat that you should use a stable release
+ of D-BUS; until we reach 1.0, there isn't a stable release.)
+
+
+ If you're doing something complicated such as clustering,
+ distributed swarms, peer-to-peer, or whatever then
+ the authors of this FAQ don't have expertise in these
+ areas and you should ask someone else or try a search engine.
+
+
+ Note: the D-BUS mailing list is probably not the place to
+ discuss which system is appropriate for your application,
+ though you are welcome to ask specific questions about
+ D-BUS after reading this FAQ, the tutorial, and
+ searching the list archives. The best way
+ to search the list archives is probably to use
+ an Internet engine such as Google. On Google,
+ include "site:freedesktop.org" in your search.
+
+
+
+
+
+
+
+
+ How can I submit a bug or patch?
+
+
+
+
+ The D-BUS web site
+ has a link to the bug tracker, which is the best place to store
+ patches. You can also post them to the list, especially if you want
+ to discuss the patch or get feedback.
+
+
+
+
+
+
+
diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml
index ccb12d4c..6f5afc07 100644
--- a/doc/dbus-tutorial.xml
+++ b/doc/dbus-tutorial.xml
@@ -20,6 +20,10 @@
+
+ David
+ Wheeler
+
@@ -101,11 +105,16 @@
There are many, many technologies in the world that have "Inter-process
communication" or "networking" in their stated purpose: MBUS, CORBA, DCE, COM/DCOM, DCOP, XML-RPC, SOAP, and probably hundreds
- more. Each of these is tailored for particular kinds of application.
+ url="http://www.w3.org/TR/SOAP/">SOAP, MBUS, Internet Communications Engine (ICE),
+ and probably hundreds more.
+ Each of these is tailored for particular kinds of application.
D-BUS is designed for two specific cases:
@@ -130,7 +139,8 @@
have significant previous experience with different IPC solutions
such as CORBA and DCOP. D-BUS is built on that experience and
carefully tailored to meet the needs of these desktop projects
- in particular.
+ in particular. D-BUS may or may not be appropriate for other
+ applications; the FAQ has some comparisons to other IPC systems.
The problem solved by the systemwide or communication-with-the-OS case