summaryrefslogtreecommitdiff
path: root/Software/dbus.mdwn
blob: a79df1b33e12ef9077d2d7d59d3a76ed369f942d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
[[!table header="no" class="mointable" data="""
**Contents**  
[[!toc ]] 
"""]]


# What is D-Bus?

D-Bus is a message bus system, a simple way for applications to talk to one another. In addition to interprocess communication, D-Bus helps coordinate process lifecycle; it makes it simple and reliable to code a "single instance" application or daemon, and to launch applications and daemons on demand when their services are needed. 

D-Bus supplies both a system daemon (for events such as "new hardware device added" or "printer queue changed") and a per-user-login-session daemon (for general IPC needs among user applications). Also, the message bus is built on top of a general one-to-one message passing framework, which can be used by any two apps to communicate directly (without going through the message bus daemon). Currently the communicating applications are on one computer, or through unencrypted TCP/IP suitable for use behind a firewall with shared NFS home directories. (Help wanted with [[better remote transports|Software/DBusRemote]] - the transport mechanism is well-abstracted and extensible.) 

The D-Bus [[low-level API reference implementation|http://dbus.freedesktop.org/doc/api/html/index.html]] and [[protocol|http://dbus.freedesktop.org/doc/dbus-specification.html]] have been heavily tested in the real world over several years, and are now "set in stone." Future changes will either be compatible or versioned appropriately. 

The low-level libdbus reference implementation has no required dependencies; the bus daemon's only *required* dependency is an XML parser (expat). Higher-level bindings specific to particular frameworks (Qt, GLib, Java, C#, Python, etc.) add more dependencies, but can make more assumptions and are thus much simpler to use. The bindings evolve separately from the low-level libdbus, so some are more mature and ABI-stable than others; check the docs for the binding you plan to use. 

There are also some reimplementations of the D-Bus protocol for languages such as C#, Java, and Ruby. These do not use the libdbus reference implementation. 

It should be noted that the low-level implementation is not primarily designed for application authors to use. Rather, it is a basis for binding authors and a reference for reimplementations. If you are able to do so it is recommended that you use one of the higher level bindings or implementations. A list of these can be found on the [[bindings page|Software/DBusBindings]]. 

The [[list of projects using D-Bus|Software/DbusProjects]] is growing and they provide a wealth of examples of using the various APIs to learn from. 

D-Bus is very portable to any Linux or UNIX flavor, and a port to Windows is in progress. 

If you have any trouble with D-Bus or suggestions for improvement, bug reports and comments are very welcome. 

Get on D-Bus today! 


# Mailing List

All D-Bus discussion is currently on [[dbus@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/dbus/]]. 


# Reporting Bugs & Sending Patches

Please report bugs (and submit patches) through the freedesktop.org [[Bugzilla|https://bugs.freedesktop.org/]]. 

Ideally, include test suite coverage with your patch; or if you report a bug, it's good to add a test that fails even if you don't have a patch otherwise. You can see test coverage stats in the GNOME build bot results, at [[http://build.gnome.org:8080/coverage/dbus/lcov/|http://build.gnome.org:8080/coverage/dbus/lcov/]] (note, coverage is understated since it counts the test code itself in the coverage, and the test suite does not test itself, in particular all the "test failed" codepaths are not covered). 

Patches to improve test coverage are very welcome, though D-Bus is already among the best-covered codebases around. 


# Documentation

Some stuff from the doc/ subdirectory is prebuilt and browsable here. If you're new to D-Bus, the tutorial is probably the best place to start (even though it is very incomplete, the basics are covered). 

Generic D-Bus protocol information: 

* [[D-Bus specification|http://dbus.freedesktop.org/doc/dbus-specification.html]] 
* [[D-Bus Overview|http://packages.python.org/txdbus/dbus_overview.html]] from the txdbus documentation 
* [[An introduction to the basics|IntroductionToDBus]] by Jeroen Vermeulen 
* [[Introduction to D-Bus|http://doc.trolltech.com/4.2/intro-to-dbus.html]] from the Qt documentation 
* [[FAQ|http://dbus.freedesktop.org/doc/dbus-faq.html]] 
* Overview picture [[png|http://dbus.freedesktop.org/doc/diagram.png]] [[svg|http://dbus.freedesktop.org/doc/diagram.svg]] 
* [[D-Bus tutorial (incomplete, has stuff on several bindings and reimplementations)|http://dbus.freedesktop.org/doc/dbus-tutorial.html]] 
* [[Config file DTD|http://dbus.freedesktop.org/doc/busconfig.dtd]] 
* If you are confused about some of the concepts in DBus, look at [[some analogies|Software/DBusAnalogy]] 
* Some [[tools|Software/DbusTools]] for working with D-Bus. 
Please note that the D-Bus spec is incomplete, especially in its description of the message bus daemon. The spec for the protocol itself is reasonably complete, though not always clear or precise. Your patches are welcome! In the meantime, you may need to supplement your reading of the spec with a reading of the reference implementation source code. 

Docs specific to the reference implementation: 

* [[API reference manual for the reference implementation (libdbus)|http://dbus.freedesktop.org/doc/api/html/index.html]] 
* [[@todo items from reference implementation manual|http://dbus.freedesktop.org/doc/dbus/api/html/todo.html]] and high-level [[TODO|http://dbus.freedesktop.org/doc/TODO]] 
* [[Browse reference implementation source|http://dbus.freedesktop.org/doc/dbus/api/html/files.html]] 
* [[dbus-daemon(1)|http://dbus.freedesktop.org/doc/dbus-daemon.1.html]] (includes configuration file docs) 
* [[dbus-send(1)|http://dbus.freedesktop.org/doc/dbus-send.1.html]] [[dbus-monitor(1)|http://dbus.freedesktop.org/doc/dbus-monitor.1.html]] [[dbus-launch(1)|http://dbus.freedesktop.org/doc/dbus-launch.1.html]] [[dbus-uuidgen(1)|http://dbus.freedesktop.org/doc/dbus-uuidgen.1.html]] 
* [[HACKING|http://dbus.freedesktop.org/doc/HACKING]] [[AUTHORS|http://dbus.freedesktop.org/doc/AUTHORS]] 
* [[NEWS|http://dbus.freedesktop.org/doc/NEWS]] [[ChangeLog|http://dbus.freedesktop.org/doc/ChangeLog]] [[README|http://dbus.freedesktop.org/doc/README]] 
* [[Test plan|http://dbus.freedesktop.org/doc/dbus-test-plan.html]] 
* [[Tarball|http://www.freedesktop.org/software/dbus/dbus-docs.tar.gz]] with most of the above docs. 
Keep in mind that libdbus is a low-level library, intended to be the backend for a language binding and with extra complexity needed to implement dbus-daemon. You will save yourself a lot of pain if you use a higher-level wrapper or a reimplementation. Documentation of these is usually linked from the [[bindings page|Software/DBusBindings]]. 

Articles from around the web, including some tutorials: 

* [["Connect desktop apps using D-BUS" (IBM developerWorks)|http://www-128.ibm.com/developerworks/linux/library/l-dbus.html?ca=dgr-lnxw95D-BUS]] by Ross Burton (July 2004) 
* [["Get on D-BUS" (Red Hat Magazine)|http://www.redhat.com/magazine/003jan05/features/dbus/]] by John Palmieri (January 2005) 
* [["Get on the D-BUS" (Linux Journal)|http://www.linuxjournal.com/article/7744]] by Robert Love (January 2005) 
* [["The DBus missing tutorial - DBus Activation"|http://raphael.slinckx.net/dbustutorial.php]] by Raphaël Slinckx (2005) 
* [[D-Bus Low-Level API Tutorial|http://dbus.freedesktop.org/doc/dbus/libdbus-tutorial.html]] by Matthew Johnson (Nov 2005) 
* [[Introduction To D-BUS|http://techbase.kde.org/Development/Tutorials/D-Bus/Introduction]] by Aaron Seigo & KDE community (2007) 
* [["An Introduction to the D-Bus Language Binding for ooRexx"|http://wi.wu.ac.at/rgf/rexx/orx22/201112-DBus4ooRexx-article.pdf]] by Rony G. Flatscher (December 2011, Intro to D-Bus concepts followed by intro to the ooRexx bindings) 

# Download


## Reference Implementation (dbus-daemon and libdbus)

Released versions of D-Bus can be downloaded from the [[releases directory on dbus.freedesktop.org|http://dbus.freedesktop.org/releases/dbus/]] and are available in all major Linux distributions. If in doubt, use your distribution's packages. 

The current **stable** branch is [[D-Bus 1.8.x|http://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=dbus-1.8]]. This is the recommended version for most purposes. 

The current **legacy** branch is [[D-Bus 1.6.x|http://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=dbus-1.6]]. This is still supported, but only for security fixes: only use these versions when upgrading from older stable releases, or preparing security updates for frozen/stable distributions.

Older branches are unsupported and are unlikely to have any more releases, but distributors who still provide security support for an older version are invited to share backported patches via the older branches in the same git repository.

The current **development** branch is  [[D-Bus 1.9.x|http://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=master]], which will lead to a 1.10.x stable branch in future.

## Bindings and Independent Implementations

Bindings and independent implementations are linked to from the [[Bindings Page|Software/DBusBindings]]. 

A binding wraps libdbus (and thus automatically gets e.g. new authentication mechanisms and other additions to libdbus), while a reimplementation codes the protocol from scratch (and thus avoids a dependency on the libdbus C library, but has to be kept in sync with new features). We are working on a hybrid approach where libdbus can be used to set up connections but bindings don't use the message queue or message marshaling from libdbus. 


# Windows port

The Windows port from the windbus and dbus4win projects has been merged into the freedesktop dbus development branch and the spec has been updated with windows specific stuff. Many thanks to the people who worked on the windows port (in alphabetic order): 

Marcus Brinkmann, Nguyễn Thái Ngọc Duy, Christian Ehrlicher, Peter Kümmel, Tor Lillqvist, Ralf Habacker, Frank Osterfeld, Marc Mutz, Romain Pokrzywka, Ole André Vadla Ravnås, Sebastian Sauer 

The windows port is knowing to work on Windows XP, Windows Vista and Windows 7, supported compiler/sdk are MSVC 2010, mingw-w32/w64(gcc) and cygwin(gcc). 

Everyone interested in having stable dbus on windows is invited to test the implementation, to reports bugs and/or to file patches. 


# Grab the Source

The core dbus code and the language bindings are under version control using Git. There is a [[nice tutorial for using git with freedesktop.org projects|http://freedesktop.org/wiki/Infrastructure/git]]. There is also [[another tutorial at IBM Developerworks site|http://www-128.ibm.com/developerworks/linux/library/l-git/]]. 

All components of dbus are in the dbus/ subdirectory. 

[[View the reference implementation in gitweb|http://cgit.freedesktop.org/dbus/dbus/]] 

Anonymous git for reference implementation: git://anongit.freedesktop.org/git/dbus/dbus 

Developer git for reference implementation: [[ssh://git.freedesktop.org/git/dbus/dbus|ssh://git.freedesktop.org/git/dbus/dbus]]