source: general/sysutils/dbus.xml@ 5fc3250

10.0 10.1 11.0 7.10 7.8 7.9 8.0 8.1 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind ken/refactor-virt lazarus nosym perl-modules qt5new trunk upgradedb xry111/git-date xry111/git-date-for-trunk xry111/git-date-test
Last change on this file since 5fc3250 was 5fc3250, checked in by Fernando de Oliveira <fernando@…>, 7 years ago

Update to dbus-1.8.18.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@15976 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 19.5 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY dbus-download-http "http://dbus.freedesktop.org/releases/dbus/dbus-&dbus-version;.tar.gz">
8 <!ENTITY dbus-download-ftp " ">
9 <!ENTITY dbus-md5sum "83e607e9ccb1c921d5b6bbea2376a36c">
10 <!ENTITY dbus-size "1.8 MB">
11 <!ENTITY dbus-buildsize "38 MB (additional 16 MB for the tests)">
12 <!ENTITY dbus-time "0.3 SBU (additional 0.5 SBU for the tests)">
13]>
14
15<sect1 id="dbus" xreflabel="D-Bus-&dbus-version;">
16 <?dbhtml filename="dbus.html"?>
17
18 <sect1info>
19 <othername>$LastChangedBy$</othername>
20 <date>$Date$</date>
21 </sect1info>
22
23 <title>D-Bus-&dbus-version;</title>
24
25 <indexterm zone="dbus">
26 <primary sortas="a-D-Bus">D-Bus</primary>
27 </indexterm>
28
29 <sect2 role="package">
30 <title>Introduction to D-Bus</title>
31
32 <para>
33 <application>D-Bus</application> is a message bus system, a simple way
34 for applications to talk to one another.
35 <application>D-Bus</application> supplies both a system daemon (for
36 events such as <quote>new hardware device added</quote> or <quote>printer
37 queue changed</quote>) and a per-user-login-session daemon (for general
38 IPC needs among user applications). Also, the message bus is built on top
39 of a general one-to-one message passing framework, which can be used by
40 any two applications to communicate directly (without going through the
41 message bus daemon).
42 </para>
43
44 &lfs77_checked; &gcc5_checked;
45
46 <bridgehead renderas="sect3">Package Information</bridgehead>
47 <itemizedlist spacing="compact">
48 <listitem>
49 <para>
50 Download (HTTP): <ulink url="&dbus-download-http;"/>
51 </para>
52 </listitem>
53 <listitem>
54 <para>
55 Download (FTP): <ulink url="&dbus-download-ftp;"/>
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 Download MD5 sum: &dbus-md5sum;
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 Download size: &dbus-size;
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 Estimated disk space required: &dbus-buildsize;
71 </para>
72 </listitem>
73 <listitem>
74 <para>
75 Estimated build time: &dbus-time;
76 </para>
77 </listitem>
78 </itemizedlist>
79
80 <bridgehead renderas="sect3">D-Bus Dependencies</bridgehead>
81
82<!--
83 <bridgehead renderas="sect4">Required</bridgehead>
84 <para role="required">
85 <xref linkend="expat"/>
86 </para>
87-->
88 <bridgehead renderas="sect4">Recommended</bridgehead>
89 <para role="recommended">
90 <xref linkend="xorg7-lib"/> (for <command>dbus-launch</command> program)
91 </para>
92
93 <bridgehead renderas="sect4">Optional</bridgehead>
94 <para role="optional">
95 For the tests:
96 <xref linkend="dbus-glib"/>,
97 <xref linkend="dbus-python"/>, and
98 <xref linkend="pygobject2"/>;
99
100 for the development documentation:
101 <xref linkend="doxygen"/>;
102
103 for man pages and XML/HTML documentation:
104 <xref linkend="xmlto"/>
105 </para>
106
107 <para condition="html" role="usernotes">User Notes:
108 <ulink url="&blfs-wiki;/dbus"/>
109 </para>
110 </sect2>
111
112 <sect2 role="installation">
113 <title>Installation of D-Bus</title>
114
115 <para>
116 If they do not already exist,
117 as the <systemitem class="username">root</systemitem> user, create a
118 system user and group to handle the system message bus activity:
119 </para>
120
121<screen role="root"><userinput>groupadd -g 18 messagebus &amp;&amp;
122useradd -c "D-Bus Message Daemon User" -d /var/run/dbus \
123 -u 18 -g messagebus -s /bin/false messagebus</userinput></screen>
124
125 <para>
126 Install <application>D-Bus</application> by running the following
127 commands (you may wish to review the output from <command>./configure
128 --help</command> first and add any desired parameters to the
129 <command>configure</command> command shown below):
130 </para>
131
132<screen><userinput>./configure --prefix=/usr \
133 --sysconfdir=/etc \
134 --localstatedir=/var \
135 --disable-doxygen-docs \
136 --disable-xml-docs \
137 --disable-static \
138 --disable-systemd \
139 --without-systemdsystemunitdir \
140 --with-console-auth-dir=/run/console/ \
141 --docdir=/usr/share/doc/dbus-&dbus-version; &amp;&amp;
142make</userinput></screen>
143
144 <para>
145 See below for test instructions.
146 </para>
147
148 <para>
149 Now, as the <systemitem class="username">root</systemitem> user:
150 </para>
151
152<screen role="root"><userinput>make install</userinput></screen>
153
154 <para>
155 If you are using a DESTDIR install,
156 <command>dbus-daemon-launch-helper</command> needs to be fixed
157 afterwards. Issue, as <systemitem class="username">root</systemitem>
158 user:
159 </para>
160
161<screen role="root"><userinput>chown -v root:messagebus /usr/libexec/dbus-daemon-launch-helper &amp;&amp;
162chmod -v 4750 /usr/libexec/dbus-daemon-launch-helper</userinput></screen>
163
164 <para>
165 If you are still building your system in chroot or you did not start the
166 daemon yet, but you want to compile some packages that require
167 <application>D-Bus</application>, generate
168 <application>D-Bus</application> UUID to avoid warnings when compiling
169 some packages with the following command as the
170 <systemitem class="username">root</systemitem> user:
171 </para>
172
173<screen role="root"><userinput>dbus-uuidgen --ensure</userinput></screen>
174
175 <para>
176 The dbus tests cannot be run until after <xref linkend="dbus-glib"/> has
177 been installed. They must be run as an unprivileged user from a local
178 session with bus address. Tests fail through ssh. If you want to run only
179 the unit tests, replace, below, <parameter>--enable-tests</parameter> by
180 <parameter>--enable-embedded-tests</parameter>, otherwise, <xref
181 linkend="dbus-python"/> has to be installed, before. The tests require
182 passing additional parameters to <command>configure</command> and
183 exposing additional functionality in the binaries. These interfaces are
184 not intended to be used in a production build of
185 <application>D-Bus</application>. If you would like to run the tests,
186 issue the following commands (for the tests, you don't need to build the
187 docs):
188 </para>
189
190<screen><userinput>make distclean &amp;&amp;
191./configure --enable-tests \
192 --enable-asserts \
193 --disable-doxygen-docs \
194 --disable-xml-docs &amp;&amp;
195make &amp;&amp;
196make check</userinput></screen>
197
198 <para>
199 If <command>run-test.sh</command> fails, it can be disabled with the
200 following sed, before running the commands for the tests:
201 </para>
202
203<screen><userinput>sed -i -e 's:run-test.sh:$(NULL):g' test/name-test/Makefile.in</userinput></screen>
204
205 <para>
206 There has been a report that the tests may fail if running inside a
207 Midnight Commander shell. You may get out-of-memory error messages when
208 running the tests. These are normal and can be safely ignored.
209 </para>
210
211 </sect2>
212
213 <sect2 role="commands">
214 <title>Command Explanations</title>
215
216 <para>
217 <parameter>--disable-doxygen-docs</parameter>: This switch disables
218 doxygen documentation build and install, if you have
219 <application>doxygen</application> installed. Delete, if
220 <application>doxygen</application> is installed and you wish to build and
221 install them.
222 </para>
223
224 <para>
225 <parameter>--disable-xml-docs</parameter>: This switch disables html
226 documentation build and install, if you have
227 <application>xmlto</application> installed. Delete, if
228 <application>xmlto</application> is installed and you wish to build and
229 install them.
230 </para>
231
232 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
233 href="../../xincludes/static-libraries.xml"/>
234
235 <para>
236 <parameter>--disable-systemd</parameter>: This switch disables systemd
237 support in <application>D-Bus</application>.
238 </para>
239
240 <para>
241 <parameter>--without-systemdsystemunitdir</parameter>: This switch
242 prevents installation of systemd unit files.
243 </para>
244
245 <para>
246 <parameter>--with-console-auth-dir=/run/console/</parameter>: This
247 parameter specifies location of the
248 <application>ConsoleKit</application> auth dir.
249 </para>
250
251 <para>
252 <parameter>--enable-tests</parameter>: Build extra parts of the code to
253 support all tests. Configure will end with a NOTE warning about increased
254 size of libraries and decreased security.
255 </para>
256
257 <para>
258 <parameter>--enable-embedded-tests</parameter>: Build extra parts of the
259 code to support only unit tests. Configure will end with a NOTE warning
260 about increased size of libraries and decreased security.
261 </para>
262
263 <para>
264 <parameter>--enable-asserts</parameter>: Enable debugging code to run
265 assertions for statements normally assumed to be true. This prevents a
266 warning that '<parameter>--enable-tests</parameter>' on its own is only
267 useful for profiling and might not give true results for all tests, but
268 adds its own NOTE that this should not be used in a production build.
269 </para>
270
271 </sect2>
272
273 <sect2 role="configuration">
274 <title>Configuring dbus</title>
275
276 <sect3 id="dbus-config">
277 <title>Config Files</title>
278
279 <para>
280 <filename>/etc/dbus-1/session.conf</filename>,
281 <filename>/etc/dbus-1/system.conf</filename> and
282 <filename>/etc/dbus-1/system.d/*</filename>
283 </para>
284
285 <indexterm zone="dbus dbus-config">
286 <primary sortas="e-etc-dbus-1-session.conf">/etc/dbus-1/session.conf</primary>
287 </indexterm>
288
289 <indexterm zone="dbus dbus-config">
290 <primary sortas="e-etc-dbus-1/system.conf">/etc/dbus-1/system.conf</primary>
291 </indexterm>
292
293 <indexterm zone="dbus dbus-config">
294 <primary sortas="e-etc-dbus-1-system.d-star">/etc/dbus-1/system.d/*</primary>
295 </indexterm>
296
297 </sect3>
298
299 <sect3 id="dbus-session-config" xreflabel="D-Bus custom services directory">
300 <title>Configuration Information</title>
301
302 <para>
303 The configuration files listed above should probably not be
304 modified. If changes are required, you should create
305 <filename>/etc/dbus-1/session-local.conf</filename> and/or
306 <filename>/etc/dbus-1/system-local.conf</filename> and make any
307 desired changes to these files.
308 </para>
309
310 <para>
311 If any packages install a
312 <application>D-Bus</application> <filename>.service</filename>
313 file outside of the standard <filename
314 class="directory">/usr/share/dbus-1/services</filename> directory,
315 that directory should be added to the local session configuration.
316 For instance, <filename
317 class="directory">/usr/local/share/dbus-1/services</filename> can
318 be added by performing the following commands as the
319 <systemitem class="username">root</systemitem> user:
320 </para>
321
322<screen role="root"><userinput>cat &gt; /etc/dbus-1/session-local.conf &lt;&lt; "EOF"
323<literal>&lt;!DOCTYPE busconfig PUBLIC
324 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
325 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"&gt;
326&lt;busconfig&gt;
327
328 &lt;!-- Search for .service files in /usr/local --&gt;
329 &lt;servicedir&gt;/usr/local/share/dbus-1/services&lt;/servicedir&gt;
330
331&lt;/busconfig&gt;</literal>
332EOF</userinput></screen>
333
334 </sect3>
335
336 <sect3 id="dbus-init">
337 <title>Boot Script</title>
338
339 <para>
340 To automatically start <command>dbus-daemon</command> when the
341 system is rebooted, install the
342 <filename>/etc/rc.d/init.d/dbus</filename> bootscript from the
343 <xref linkend="bootscripts"/> package.
344 </para>
345
346 <indexterm zone="dbus dbus-init">
347 <primary sortas="f-dbus">dbus</primary>
348 </indexterm>
349
350<screen role="root"><userinput>make install-dbus</userinput></screen>
351
352 <para>
353 Note that this boot script only starts the system-wide
354 <application>D-Bus</application> daemon. Each user requiring access to
355 <application>D-Bus</application> services will also need to run a
356 session daemon as well. There are many methods you can use to start a
357 session daemon using the <command>dbus-launch</command> command. Review
358 the <command>dbus-launch</command> man page for details about the
359 available parameters and options. Here are some suggestions and
360 examples:
361 </para>
362
363 <itemizedlist spacing="compact">
364 <listitem>
365 <para>
366 Add <command>dbus-launch</command> to the line in the
367 <filename>~/.xinitrc</filename> file that starts your graphical
368 desktop environment.
369 </para>
370 </listitem>
371 <listitem>
372 <para>
373 If you use <command>xdm</command> or some other display manager
374 that calls the <filename>~/.xsession</filename> file, you can add
375 <command>dbus-launch</command> to the line in your
376 <filename>~/.xsession</filename> file that starts your graphical
377 desktop environment. The syntax would be similar to the example in
378 the <filename>~/.xinitrc</filename> file.
379 </para>
380 </listitem>
381 <listitem>
382 <para>
383 The examples shown previously use
384 <command>dbus-launch</command> to specify a program to be run. This
385 has the benefit (when also using the
386 <parameter>--exit-with-session</parameter> parameter) of stopping the
387 session daemon when the specified program is stopped. You can also
388 start the session daemon in your system or personal startup scripts
389 by adding the following lines:
390 </para>
391
392<screen><userinput><literal># Start the D-Bus session daemon
393eval `dbus-launch`
394export DBUS_SESSION_BUS_ADDRESS</literal></userinput></screen>
395
396 <para>
397 This method will not stop the session daemon when you exit
398 your shell, therefore you should add the following line to your
399 <filename>~/.bash_logout</filename> file:
400 </para>
401
402<screen><userinput><literal># Kill the D-Bus session daemon
403kill $DBUS_SESSION_BUS_PID</literal></userinput></screen>
404 </listitem>
405
406 <listitem>
407 <para>
408 A hint has been written that provides ways to start scripts
409 using the KDM session manager of KDE. The concepts in this hint could
410 possibly be used with other session managers as well. The hint is
411 located at <ulink
412 url="&hints-root;/downloads/files/execute-session-scripts-using-kdm.txt"/>.
413 </para>
414 </listitem>
415
416 </itemizedlist>
417
418 </sect3>
419
420 </sect2>
421
422 <sect2 role="content">
423 <title>Contents</title>
424
425 <segmentedlist>
426 <segtitle>Installed Programs</segtitle>
427 <segtitle>Installed Library</segtitle>
428 <segtitle>Installed Directories</segtitle>
429
430 <seglistitem>
431 <seg>
432 dbus-cleanup-sockets, dbus-daemon, dbus-launch, dbus-monitor,
433 dbus-run-session, dbus-send and dbus-uuidgen
434 </seg>
435 <seg>
436 libdbus-1.so
437 </seg>
438 <seg>
439 /etc/dbus-1,
440 /usr/include/dbus-1.0,
441 /usr/lib/dbus-1.0,
442 /usr/share/dbus-1,
443 /usr/share/doc/dbus-&dbus-version;,
444 /var/lib/dbus and
445 /var/run/dbus
446 </seg>
447 </seglistitem>
448 </segmentedlist>
449
450 <variablelist>
451 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
452 <?dbfo list-presentation="list"?>
453 <?dbhtml list-presentation="table"?>
454
455 <varlistentry id="dbus-cleanup-sockets">
456 <term><command>dbus-cleanup-sockets</command></term>
457 <listitem>
458 <para>
459 is used to clean up leftover sockets in a directory.
460 </para>
461 <indexterm zone="dbus dbus-cleanup-sockets">
462 <primary sortas="b-dbus-cleanup-sockets">dbus-cleanup-sockets</primary>
463 </indexterm>
464 </listitem>
465 </varlistentry>
466
467 <varlistentry id="dbus-daemon">
468 <term><command>dbus-daemon</command></term>
469 <listitem>
470 <para>
471 is the <application>D-Bus</application> message bus daemon.
472 </para>
473 <indexterm zone="dbus dbus-daemon">
474 <primary sortas="b-dbus-daemon">dbus-daemon</primary>
475 </indexterm>
476 </listitem>
477 </varlistentry>
478
479 <varlistentry id="dbus-launch">
480 <term><command>dbus-launch</command></term>
481 <listitem>
482 <para>
483 is used to start <command>dbus-daemon</command> from a shell
484 script. It would normally be called from a user's login
485 scripts.
486 </para>
487 <indexterm zone="dbus dbus-launch">
488 <primary sortas="b-dbus-launch">dbus-launch</primary>
489 </indexterm>
490 </listitem>
491 </varlistentry>
492
493 <varlistentry id="dbus-monitor">
494 <term><command>dbus-monitor</command></term>
495 <listitem>
496 <para>
497 is used to monitor messages going through a
498 <application>D-Bus</application> message bus.
499 </para>
500 <indexterm zone="dbus dbus-monitor">
501 <primary sortas="b-dbus-monitor">dbus-monitor</primary>
502 </indexterm>
503 </listitem>
504 </varlistentry>
505
506 <varlistentry id="dbus-run-session">
507 <term><command>dbus-run-session</command></term>
508 <listitem>
509 <para>
510 start a process as a new <application>D-Bus</application> session.
511 </para>
512 <indexterm zone="dbus dbus-run-session">
513 <primary sortas="b-dbus-run-session">dbus-run-session</primary>
514 </indexterm>
515 </listitem>
516 </varlistentry>
517
518 <varlistentry id="dbus-send">
519 <term><command>dbus-send</command></term>
520 <listitem>
521 <para>
522 is used to send a message to a <application>D-Bus</application>
523 message bus.
524 </para>
525 <indexterm zone="dbus dbus-send">
526 <primary sortas="b-dbus-send">dbus-send</primary>
527 </indexterm>
528 </listitem>
529 </varlistentry>
530
531 <varlistentry id="dbus-uuidgen">
532 <term><command>dbus-uuidgen</command></term>
533 <listitem>
534 <para>
535 is used to generate a universally unique ID.
536 </para>
537 <indexterm zone="dbus dbus-uuidgen">
538 <primary sortas="b-dbus-uuidgen">dbus-uuidgen</primary>
539 </indexterm>
540 </listitem>
541 </varlistentry>
542
543 <varlistentry id="libdbus-1">
544 <term><filename class="libraryfile">libdbus-1.so</filename></term>
545 <listitem>
546 <para>
547 contains the API functions used by the
548 <application>D-Bus</application> message daemon.
549 <application>D-Bus</application> is first a library that provides
550 one-to-one communication between any two applications;
551 <command>dbus-daemon</command> is an application that uses this
552 library to implement a message bus daemon.
553 </para>
554 <indexterm zone="dbus libdbus-1">
555 <primary sortas="c-libdbus-1">libdbus-1.so</primary>
556 </indexterm>
557 </listitem>
558 </varlistentry>
559
560 </variablelist>
561
562 </sect2>
563
564</sect1>
565
Note: See TracBrowser for help on using the repository browser.