README
1Sections 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
8Introduction
9===
10
11D-Bus is a simple system for interprocess communication and coordination.
12
13The "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
18See http://www.freedesktop.org/software/dbus/ for lots of documentation,
19mailing lists, etc.
20
21See also the file HACKING for notes of interest to developers working on D-Bus.
22
23If you're considering D-Bus for use in a project, you should be aware
24that D-Bus was designed for a couple of specific use cases, a "system
25bus" and a "desktop session bus." These are documented in more detail
26in the D-Bus specification and FAQ available on the web site.
27
28If your use-case isn't one of these, D-Bus may still be useful, but
29only by accident; so you should evaluate carefully whether D-Bus makes
30sense for your project.
31
32Note: low-level API vs. high-level binding APIs
33===
34
35A core concept of the D-Bus implementation is that "libdbus" is
36intended to be a low-level API. Most programmers are intended to use
37the bindings to GLib, Qt, Python, Mono, Java, or whatever. These
38bindings have varying levels of completeness and are maintained as
39separate projects from the main D-Bus package. The main D-Bus package
40contains the low-level libdbus, the bus daemon, and a few command-line
41tools such as dbus-launch.
42
43If you use the low-level API directly, you're signing up for some
44pain. Think of the low-level API as analogous to Xlib or GDI, and the
45high-level API as analogous to Qt/GTK+/HTML.
46
47Version numbers
48===
49
50D-Bus uses the common "Linux kernel" versioning system, where
51even-numbered minor versions are stable and odd-numbered minor
52versions are development snapshots.
53
54So for example, development snapshots: 1.1.1, 1.1.2, 1.1.3, 1.3.4
55Stable versions: 1.0, 1.0.1, 1.0.2, 1.2.1, 1.2.3
56
57All pre-1.0 versions were development snapshots.
58
59Development snapshots make no ABI stability guarantees for new ABI
60introduced since the last stable release. Development snapshots are
61likely to have more bugs than stable releases, obviously.
62
63Configuration
64===
65
66dbus could be build by using autotools or cmake.
67
68When using autotools the configure step is initiated by running ./configure
69with or without additional configuration flags.
70
71When using cmake the configure step is initiated by running the cmake
72program with or without additional configuration flags.
73
74Configuration flags
75===
76
77When using autotools, run "./configure --help" to see the possible
78configuration options and environment variables.
79
80When using cmake, inspect README.cmake to see the possible
81configuration options and environment variables.
82
83API/ABI Policy
84===
85
86Now that D-Bus has reached version 1.0, the objective is that all
87applications dynamically linked to libdbus will continue working
88indefinitely with the most recent system and session bus daemons.
89
90 - The protocol will never be broken again; any message bus should
91 work with any client forever. However, extensions are possible
92 where the protocol is extensible.
93
94 - If the library API is modified incompatibly, we will rename it
95 as in http://ometer.com/parallel.html - in other words,
96 it will always be possible to compile against and use the older
97 API, and apps will always get the API they expect.
98
99Interfaces can and probably will be _added_. This means both new
100functions and types in libdbus, and new methods exported to
101applications by the bus daemon.
102
103The above policy is intended to make D-Bus as API-stable as other
104widely-used libraries (such as GTK+, Qt, Xlib, or your favorite
105example). If you have questions or concerns they are very welcome on
106the D-Bus mailing list.
107
108NOTE ABOUT DEVELOPMENT SNAPSHOTS AND VERSIONING
109
110Odd-numbered minor releases (1.1.x, 1.3.x, 2.1.x, etc. -
111major.minor.micro) are devel snapshots for testing, and any new ABI
112they introduce relative to the last stable version is subject to
113change during the development cycle.
114
115Any ABI found in a stable release, however, is frozen.
116
117ABI will not be added in a stable series if we can help it. i.e. the
118ABI of 1.2.0 and 1.2.5 you can expect to be the same, while the ABI of
1191.4.x may add more stuff not found in 1.2.x.
120
121NOTE ABOUT STATIC LINKING
122
123We are not yet firmly freezing all runtime dependencies of the libdbus
124library. For example, the library may read certain files as part of
125its implementation, and these files may move around between versions.
126
127As a result, we don't yet recommend statically linking to
128libdbus. Also, reimplementations of the protocol from scratch might
129have to work to stay in sync with how libdbus behaves.
130
131To lock things down and declare static linking and reimplementation to
132be safe, we'd like to see all the internal dependencies of libdbus
133(for example, files read) well-documented in the specification, and
134we'd like to have a high degree of confidence that these dependencies
135are supportable over the long term and extensible where required.
136
137NOTE ABOUT HIGH-LEVEL BINDINGS
138
139Note that the high-level bindings are _separate projects_ from the
140main D-Bus package, and have their own release cycles, levels of
141maturity, and ABI stability policies. Please consult the documentation
142for your binding.
143
144Bootstrapping D-Bus on new platforms
145===
146
147A full build of D-Bus, with all regression tests enabled and run, has some
148dependencies which themselves depend on D-Bus, either for compilation or
149for some of *their* regression tests: GLib, dbus-glib and dbus-python are
150currently affected.
151
152To avoid circular dependencies, when bootstrapping D-Bus for the first time
153on a new OS or CPU architecture, you can either cross-compile some of
154those components, or choose the build order and options carefully:
155
156* build and install D-Bus without tests
157 - do not use the --enable-modular-tests=yes configure option
158 - do not use the --enable-tests=yes configure option
159* build and install GLib, again without tests
160* use those versions of libdbus and GLib to build and install dbus-glib
161* ... and use those to install dbus-python
162* rebuild libdbus; this time you can run all of the tests
163* rebuild GLib; this time you can run all of the tests
164
README.cygwin
README.launchd
1Launchd[1,2] replaces init, inetd and cron on Mac OS X since 10.4 "Tiger".
2dbus uses this service to provide a common session bus address for each user
3and so deprecates the X11 enabled dbus-launcher.
4
5[1] http://developer.apple.com/MacOsX/launchd.html
6[2] http://launchd.macosforge.org/
7
8
9Setup
10===
11
12Configure with --enable-launchd and --without-x (X11 should not harm but it's
13simply not necessary any more)
14After installation, to prevent a reboot, load the dbus session starter into
15launchd by executing:
16$ launchctl load /Library/LaunchAgents/org.freedesktop.dbus-session.plist
17
18You can change the launch agent dir via configure, but it's not recommended.
19Make sure to execute the above line as the actual user for which you want to
20use a session bus since launchd manages its agents on a per user basis.
21
22
23How it works
24===
25
26Launchd allocates a socket and provides the unix path to it via the variable
27DBUS_LAUNCHD_SESSION_BUS_SOCKET in launchd's environment. Every process
28spawned by launchd (or dbus-daemon, if stared by launchd) can access it through
29its own environment. Other processes can query launchd for it by executing:
30$ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET
31However, this is normally done by the dbus client lib for you.
32
33If launchd start dbus-daemon with a config file containing a "launchd:env=FOO"
34address, as the default session config does with env=DBUS_LAUNCHD_SESSION_BUS_SOCKET,
35the daemon will get the file descriptor from launchd and start listening on it.
36The environment variable is used to get the actual socket path which is passed
37to every service spawned by dbus-daemon as a result from autolaunch messages.
38Please note that it's not possible to start dbus-daemon manually when using a
39"launchd:" address. Only child processes of launchd can access the above
40mentioned file descriptor!
41
42To create custom buses just set up an other launch agent. As a quick start copy
43/Library/LaunchAgents/org.freedesktop.dbus-session.plist, change the label
44to i.e. "org.freedesktop.dbus-foo" and change the SecureSocketWithKey value,
45i.e. to "DBUS_LAUNCHD_FOO_BUS_SOCKET". This environment variable has to be set
46in the config file for your new bus in the <listen> element (see session.config).
47Then edit your /Library/LaunchAgents/org.freedesktop.dbus-foo.plist to start
48dbus-daemon with "--config-file=/opt/local/etc/dbus-1/foo.conf" instead of
49"--session". Now load the new plist onto launchd as described in the setup
50section of this document.
51Executing "launchctl export" should now give you two sockets, one in
52DBUS_LAUNCHD_SESSION_BUS_SOCKET and the new DBUS_LAUNCHD_FOO_BUS_SOCKET.
53To connect to this new bus use "launchd:env=DBUS_LAUNCHD_FOO_BUS_SOCKET".
54
55Since Mac OS X 10.5 "Leopard" you can also configure launchd to start
56dbus-daemon on demand as soon as some process connects to the socket. Since
57it's broken on 10.4 this feature is disabled per default. Look at
58/Library/LaunchAgents/org.freedesktop.dbus-session.plist to change it.
59
60On the client side, the envvar DBUS_SESSION_BUS_ADDRESS can be normally used
61but if it's not set, launchd is queried for the session bus socket.
62
README.win
1-----------------------------------------
2Windows port of the freedesktop.org D-Bus
3-----------------------------------------
4
5Features and completeness
6-------------------------
7The windows port of dbus provides the dbus-1 library and mostly
8applications which are already available on unix. These applications
9are: dbus-daemon, dbus-launch, dbus-monitor and dbus-send.
10DBus comes with a test suite which is used on unix to guarantate
11production quality and this test suite runs mostly. There are some
12test not running yet and there is help needed to get them running.
13
14Supported compilers
15-------------------
16On windows Microsoft Visual Studio 2010 (Express and professional variants)
17and mingw-w64|32 are known to work.
18
19Building
20--------
21DBus can be built on windows using automake or cmake. See the
22file README for more information.
23Special cmake build instructions can be found in cmake/readme-cmake.txt
24
25
26windbus and dbus4win Ports
27--------------------------
28The Windows ports from the windbus and dbus4win projects has been merged
29into the freedesktop git master branch, as applicable. The spec has been
30updated with windows specific stuff.
31
32
33Tests
34-----
35 - dbus library check
36 bin\dbus-test.exe <build-root>\test\data
37
38 - bus daemon check
39 bin\bus-test.exe <build-root>\test\data
40
41 - check available names
42 bin\test_names.exe
43
44 - check if dbus-daemon is accessable
45 bin\dbus-send.exe --session --type=method_call --print-reply --dest=org.freedesktop.DBus / org.freedesktop.DBus.ListNames method return sender=org.freedesktop.DBus -> dest=:1.4 array [ string "org.freedesktop.DBus"string ":1.4"]
46
47 - start session dbus-daemon
48 either by running
49 bin\dbus-launch
50 or
51 start bin\dbus-daemon --session
52
53 Before running these commands you may execute
54 set DBUS_VERBOSE=1
55 for getting debug infos
56
57
58 - call function registerd in dbus
59 bin\dbus-send.exe --dest=org.freedesktop.DBus --print-reply --type=method_call / org.freedesktop.DBus.StartServiceByName string:org.freedesktop.DBus.TestSuiteEchoService uint32:455 method return sender=org.freedesktop.DBus -> dest=:1.8 uint32 2
60
61 note: When building with the Visual C++ IDE the *.exe files are in
62 the bin/Debug and bin/Release folder, not in the bin folder.
63
64
65FAQ
66---
67
68- How far is WinDBus from being usable for production ?
69
70 dbus comes with a test suite which is used on unix to guarantate
71 production quality and this test suite runs mostly. There are some
72 test not running and we need help to get them running.
73 In the pratice I and some other people are using dbus for at least more
74 than four years in conjunction with kde on windows without any problems.
75
76- On UNIX D-Bus uses UNIX sockets to communicate (correct me if I'm wrong).
77 What is used on Windows ?
78
79 tcp sockets, there are some efforts to get named pipe running, but some
80 design problems of the win32 api, we are not able to solve without
81 bigger changes to the dbus code base let us stop this effort.
82
83- Do you have any clue if dbus-win32 can run in a Windows CE environment?
84
85 dbus has been ported to wince, see README.wince for more information
86
87- Do you know if the C++ binding made by OpenWengo will be easily portable to Windows?
88
89 The OpenWengo dbus-c++ binding has been ported to windows see in WinDBus svn
90 (http://sf.net/projects/windbus)
91 The related test applicationa are running well.
92
93
94TODO
95----
96
97Oktober 2010:
98
99- the code wrapped with DBUS_WIN_FIXME should be inspected if it required for windows
100
101- create a dbus setup installer
102
103- implement system bus and system bus service starter
104 see http://windbus.svn.sourceforge.net/viewvc/windbus/trunk/bus/bus-service-win.c
105 for a starting point
106
107- implement a real login session bus
108 The scope parameter of the autolaunch meta protocol could be extended to support user
109 specific session busses (like already done with the amarok bundled dbus which use a
110 shared memory area named "DBusDaemonAddressInfo:<username>".
111 Also the dbus installer should start a session bus on user login.
112
README.wince
1DBus Daemon for Windows CE/Windows Mobile 6.5
2=============================================
3
4Bugs in upstream for any window version:
5* MoveFileExA < 0 result check bug
6* double dbus_free somewhere I forgot where (check in -ugly)
7* alignment issue
8* CreateProcess process information handle leak
9* _dbus_getsid NULL vs INVALID_HANDLE_VALUE
10* win_account_to_sid
11
12Customisation
13=============
14
151) At installation, the following registry value should be set to the
16installation directory of the dbus installation (the directory
17containing the bin, etc, share folders):
18
19HKLM\Software\freedesktop\DBus\Install Directory
20
212) Instead of environment variable DBUS_VERBOSE, use
22HKLM\Software\freedesktop\DBus\Verbose
23
242) The keyring directory is MYDOCUMENTS\dbus-keyrings, not
25HOMEPATH\.dbus-keyrings.
26
27
28Compilation
29===========
30
31./configure --host=arm-mingw32ce CPPFLAGS=-I/path/to/expat/include LDFLAGS=-L/path/to/expat/lib
32
33A recent version of libtool is required, with this change:
34
352010-02-28 Pierre Ossman <ossman@ossman.lkpg.cendio.se> (tiny change)
36 Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
37
38 Fix deplibs check fallback for 64-bit Windows and Windows CE.
39 * libltdl/m4/libtool.m4 (_LT_CHECK_MAGIC_METHOD): Accept file formats
40 'pe-arm-wince' and 'pe-x86-64'. Add note about consistency with ...
41 * libltdl/config/ltmain.m4sh (func_win32_libid): ... the respective
42 pattern here; sync pattern from the former.
43 * tests/deplibs-mingw.at (deplibs without file command): New
44 file, new test.
45 * Makefile.am (TESTSUITE_AT): Update.
46 * NEWS: Update.
47
48
49MB vs WCHAR
50===========
51
52Windows CE only supports the Unicode interface, while DBus Daemon uses
53the Multi-Byte interface on Windows by default. The glue code does
54not support multibyte in all cases. In particular, the _mbsrchr
55function is not correctly implemented. It could be correctly
56implemented, or dbus daemon could use the wchar interface more
57consistently on all Windows targets. For now, the Windows CE port
58will only work for filesystems without some weird characters in file
59names. Is this a serious limitation?
60
61
62Known Issues
63============
64
65Autolaunch is broken so far.
66
67Environment variables are faked. Some are punted to the registry, but
68in any case they can not be used reliably for IPC.
69
70The test suite is not ported yet.
71
72dbus-pipe.c:
73 * Uses libc file descriptors. Needed for --print-address and
74 --print-pid which probably don't work yet.
75
76dbus-sysdeps-win.c:
77 * Backtraces have been disabled.
78 * _dbus_fd_set_close_on_exec Not supported, maybe we should disable
79 the warning.
80 * SearchPathA: Uses HKLM\\Software\\freedesktop\\DBus\\Install Directory
81 to locate binaries.
82