source: general/sysutils/dbus.xml@ e20b59be

10.0 10.1 11.0 11.1 7.10 7.9 8.0 8.1 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind lazarus nosym perl-modules qt5new trunk upgradedb xry111/intltool xry111/test-20220226
Last change on this file since e20b59be was e20b59be, checked in by Fernando de Oliveira <fernando@…>, 7 years ago
  • Update to libgusb-0.2.8.
  • Update to librsvg-2.40.12.
  • Update to dbus-1.10.6.
  • Update to mercurial-3.6.2.
  • Update to samba-4.3.2.
  • Update to libass-0.13.1.

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

  • Property mode set to 100644
File size: 21.3 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 "26d0cf3a1c9782cb0e342101f0450440">
10 <!ENTITY dbus-size "1.9 MB">
11 <!ENTITY dbus-buildsize "109 MB, with doxygen and xml documents (37 MB for the tests)">
12 <!ENTITY dbus-time "0.4 SBU, with doxygen and xml documents (0.4 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 &lfs78_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"/>,
98 <xref linkend="pygobject2"/>, and
99 <xref linkend="valgrind"/>;
100
101 for documentation:
102 <xref linkend="doxygen"/>,
103 <xref linkend="xmlto"/>,
104 <ulink url="https://pypi.python.org/pypi/mallard-ducktype">Ducktype</ulink>,
105 and
106 <ulink url="http://ftp.gnome.org/pub/gnome/sources/yelp-tools/">Yelp Tools</ulink>
107 </para>
108
109 <para condition="html" role="usernotes">User Notes:
110 <ulink url="&blfs-wiki;/dbus"/>
111 </para>
112 </sect2>
113
114 <sect2 role="installation">
115 <title>Installation of D-Bus</title>
116
117 <para>
118 If they do not already exist,
119 as the <systemitem class="username">root</systemitem> user, create a
120 system user and group to handle the system message bus activity:
121 </para>
122
123<screen role="root"><userinput>groupadd -g 18 messagebus &amp;&amp;
124useradd -c "D-Bus Message Daemon User" -d /var/run/dbus \
125 -u 18 -g messagebus -s /bin/false messagebus</userinput></screen>
126
127 <para>
128 Install <application>D-Bus</application> by running the following
129 commands (you may wish to review the output from <command>./configure
130 --help</command> first and add any desired parameters to the
131 <command>configure</command> command shown below):
132 </para>
133
134<screen><userinput>./configure --prefix=/usr \
135 --sysconfdir=/etc \
136 --localstatedir=/var \
137 --disable-doxygen-docs \
138 --disable-xml-docs \
139 --disable-static \
140 --disable-systemd \
141 --without-systemdsystemunitdir \
142 --with-console-auth-dir=/run/console/ \
143 --docdir=/usr/share/doc/dbus-&dbus-version; &amp;&amp;
144make</userinput></screen>
145
146 <para>
147 See below for test instructions.
148 </para>
149
150 <para>
151 Now, as the <systemitem class="username">root</systemitem> user:
152 </para>
153
154<screen role="root"><userinput>make install</userinput></screen>
155
156 <para>
157 If you are using a DESTDIR install,
158 <command>dbus-daemon-launch-helper</command> needs to be fixed
159 afterwards. Issue, as <systemitem class="username">root</systemitem>
160 user:
161 </para>
162
163<screen role="root"><userinput>chown -v root:messagebus /usr/libexec/dbus-daemon-launch-helper &amp;&amp;
164chmod -v 4750 /usr/libexec/dbus-daemon-launch-helper</userinput></screen>
165
166 <para>
167 If you are still building your system in chroot or you did not start the
168 daemon yet, but you want to compile some packages that require
169 <application>D-Bus</application>, generate
170 <application>D-Bus</application> UUID to avoid warnings when compiling
171 some packages with the following command as the
172 <systemitem class="username">root</systemitem> user:
173 </para>
174
175<screen role="root"><userinput>dbus-uuidgen --ensure</userinput></screen>
176
177 <para>
178 The dbus tests cannot be run until after <xref linkend="dbus-glib"/> has
179 been installed. They must be run as an unprivileged user from a local
180 session with bus address. Tests fail through ssh. If you want to run only
181 the unit tests, replace, below, <parameter>--enable-tests</parameter> by
182 <parameter>--enable-embedded-tests</parameter>, otherwise, <xref
183 linkend="dbus-python"/> has to be installed, before. The tests require
184 passing additional parameters to <command>configure</command> and
185 exposing additional functionality in the binaries. These interfaces are
186 not intended to be used in a production build of
187 <application>D-Bus</application>. If you would like to run the tests,
188 issue the following commands (for the tests, you don't need to build the
189 docs):
190 </para>
191
192<screen><userinput>make distclean &amp;&amp;
193./configure --enable-tests \
194 --enable-asserts \
195 --disable-doxygen-docs \
196 --disable-xml-docs &amp;&amp;
197make &amp;&amp;
198make check</userinput></screen>
199
200 <para>
201 The <quote>estimated disk space required</quote> reported above is
202 obtained in a build using the switches disabling documents generation.
203 This and the use of the <command>make distclean</command> command implies
204 that the build directory size is smaller than the one for a full build
205 with documents generated. There are two errors, for unknown reasons.
206 </para>
207<!--
208 <para>
209 If <command>run-test.sh</command> fails, it can be disabled with the
210 following sed, before running the commands for the tests:
211 </para>
212
213<screen><userinput>sed -i -e 's:run-test.sh:$(NULL):g' test/name-test/Makefile.in</userinput></screen>-->
214
215 <para>
216 There has been a report that the tests may fail if running inside a
217 Midnight Commander shell. You may get out-of-memory error messages when
218 running the tests. These are normal and can be safely ignored.
219 </para>
220
221 </sect2>
222
223 <sect2 role="commands">
224 <title>Command Explanations</title>
225
226 <para>
227 <parameter>--disable-doxygen-docs</parameter>: This switch disables
228 doxygen documentation build and install, if you have
229 <application>doxygen</application> installed. Delete, if
230 <application>doxygen</application> is installed and you wish to build and
231 install them.
232 </para>
233
234 <para>
235 <parameter>--disable-xml-docs</parameter>: This switch disables html
236 documentation build and install, if you have
237 <application>xmlto</application> installed. Delete, if
238 <application>xmlto</application> is installed and you wish to build and
239 install them.
240 </para>
241
242 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
243 href="../../xincludes/static-libraries.xml"/>
244
245 <para>
246 <parameter>--disable-systemd</parameter>: This switch disables systemd
247 support in <application>D-Bus</application>.
248 </para>
249
250 <para>
251 <parameter>--without-systemdsystemunitdir</parameter>: This switch
252 prevents installation of systemd unit files.
253 </para>
254
255 <para>
256 <parameter>--with-console-auth-dir=/run/console/</parameter>: This
257 parameter specifies location of the
258 <application>ConsoleKit</application> auth dir.
259 </para>
260
261 <para>
262 <parameter>--enable-tests</parameter>: Build extra parts of the code to
263 support all tests. Configure will end with a NOTE warning about increased
264 size of libraries and decreased security.
265 </para>
266
267 <para>
268 <parameter>--enable-embedded-tests</parameter>: Build extra parts of the
269 code to support only unit tests. Configure will end with a NOTE warning
270 about increased size of libraries and decreased security.
271 </para>
272
273 <para>
274 <parameter>--enable-asserts</parameter>: Enable debugging code to run
275 assertions for statements normally assumed to be true. This prevents a
276 warning that '<parameter>--enable-tests</parameter>' on its own is only
277 useful for profiling and might not give true results for all tests, but
278 adds its own NOTE that this should not be used in a production build.
279 </para>
280
281 </sect2>
282
283 <sect2 role="configuration">
284 <title>Configuring dbus</title>
285
286 <sect3 id="dbus-config">
287 <title>Config Files</title>
288
289 <para>
290 <filename>/etc/dbus-1/session.conf</filename>,
291 <filename>/etc/dbus-1/system.conf</filename> and
292 <filename>/etc/dbus-1/system.d/*</filename>
293 </para>
294
295 <indexterm zone="dbus dbus-config">
296 <primary sortas="e-etc-dbus-1-session.conf">/etc/dbus-1/session.conf</primary>
297 </indexterm>
298
299 <indexterm zone="dbus dbus-config">
300 <primary sortas="e-etc-dbus-1/system.conf">/etc/dbus-1/system.conf</primary>
301 </indexterm>
302
303 <indexterm zone="dbus dbus-config">
304 <primary sortas="e-etc-dbus-1-system.d-star">/etc/dbus-1/system.d/*</primary>
305 </indexterm>
306
307 </sect3>
308
309 <sect3 id="dbus-session-config" xreflabel="D-Bus custom services directory">
310 <title>Configuration Information</title>
311
312 <para>
313 The configuration files listed above should probably not be
314 modified. If changes are required, you should create
315 <filename>/etc/dbus-1/session-local.conf</filename> and/or
316 <filename>/etc/dbus-1/system-local.conf</filename> and make any
317 desired changes to these files.
318 </para>
319
320 <para>
321 If any packages install a
322 <application>D-Bus</application> <filename>.service</filename>
323 file outside of the standard <filename
324 class="directory">/usr/share/dbus-1/services</filename> directory,
325 that directory should be added to the local session configuration.
326 For instance, <filename
327 class="directory">/usr/local/share/dbus-1/services</filename> can
328 be added by performing the following commands as the
329 <systemitem class="username">root</systemitem> user:
330 </para>
331
332<screen role="root"><userinput>cat &gt; /etc/dbus-1/session-local.conf &lt;&lt; "EOF"
333<literal>&lt;!DOCTYPE busconfig PUBLIC
334 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
335 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"&gt;
336&lt;busconfig&gt;
337
338 &lt;!-- Search for .service files in /usr/local --&gt;
339 &lt;servicedir&gt;/usr/local/share/dbus-1/services&lt;/servicedir&gt;
340
341&lt;/busconfig&gt;</literal>
342EOF</userinput></screen>
343
344 </sect3>
345
346 <sect3 id="dbus-init">
347 <title>Boot Script</title>
348
349 <para>
350 To automatically start <command>dbus-daemon</command> when the
351 system is rebooted, install the
352 <filename>/etc/rc.d/init.d/dbus</filename> bootscript from the
353 <xref linkend="bootscripts"/> package.
354 </para>
355
356 <indexterm zone="dbus dbus-init">
357 <primary sortas="f-dbus">dbus</primary>
358 </indexterm>
359
360<screen role="root"><userinput>make install-dbus</userinput></screen>
361
362 <para>
363 Note that this boot script only starts the system-wide
364 <application>D-Bus</application> daemon. Each user requiring access to
365 <application>D-Bus</application> services will also need to run a
366 session daemon as well. There are many methods you can use to start a
367 session daemon using the <command>dbus-launch</command> command. Review
368 the <command>dbus-launch</command> man page for details about the
369 available parameters and options. Here are some suggestions and
370 examples:
371 </para>
372
373 <itemizedlist spacing="compact">
374 <listitem>
375 <para>
376 Add <command>dbus-launch</command> to the line in the
377 <filename>~/.xinitrc</filename> file that starts your graphical
378 desktop environment.
379 </para>
380 </listitem>
381 <listitem>
382 <para>
383 If you use <command>xdm</command> or some other display manager
384 that calls the <filename>~/.xsession</filename> file, you can add
385 <command>dbus-launch</command> to the line in your
386 <filename>~/.xsession</filename> file that starts your graphical
387 desktop environment. The syntax would be similar to the example in
388 the <filename>~/.xinitrc</filename> file.
389 </para>
390 </listitem>
391 <listitem>
392 <para>
393 The examples shown previously use
394 <command>dbus-launch</command> to specify a program to be run. This
395 has the benefit (when also using the
396 <parameter>--exit-with-session</parameter> parameter) of stopping the
397 session daemon when the specified program is stopped. You can also
398 start the session daemon in your system or personal startup scripts
399 by adding the following lines:
400 </para>
401
402<screen><userinput><literal># Start the D-Bus session daemon
403eval `dbus-launch`
404export DBUS_SESSION_BUS_ADDRESS</literal></userinput></screen>
405
406 <para>
407 This method will not stop the session daemon when you exit
408 your shell, therefore you should add the following line to your
409 <filename>~/.bash_logout</filename> file:
410 </para>
411
412<screen><userinput><literal># Kill the D-Bus session daemon
413kill $DBUS_SESSION_BUS_PID</literal></userinput></screen>
414 </listitem>
415
416 <listitem>
417 <para>
418 A hint has been written that provides ways to start scripts
419 using the KDM session manager of KDE. The concepts in this hint could
420 possibly be used with other session managers as well. The hint is
421 located at <ulink
422 url="&hints-root;/downloads/files/execute-session-scripts-using-kdm.txt"/>.
423 </para>
424 </listitem>
425
426 </itemizedlist>
427
428 </sect3>
429
430 </sect2>
431
432 <sect2 role="content">
433 <title>Contents</title>
434
435 <segmentedlist>
436 <segtitle>Installed Programs</segtitle>
437 <segtitle>Installed Library</segtitle>
438 <segtitle>Installed Directories</segtitle>
439
440 <seglistitem>
441 <seg>
442 dbus-cleanup-sockets, dbus-daemon, dbus-launch, dbus-monitor,
443 dbus-run-session, dbus-send, dbus-test-tool,
444 dbus-update-activation-environment, and dbus-uuidgen
445 </seg>
446 <seg>
447 libdbus-1.so
448 </seg>
449 <seg>
450 /etc/dbus-1,
451 /usr/{include,lib}/dbus-1.0,
452 /usr/share/dbus-1,
453 /usr/share/doc/dbus-&dbus-version;, and
454 /var/{lib,run}/dbus
455 </seg>
456 </seglistitem>
457 </segmentedlist>
458
459 <variablelist>
460 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
461 <?dbfo list-presentation="list"?>
462 <?dbhtml list-presentation="table"?>
463
464 <varlistentry id="dbus-cleanup-sockets">
465 <term><command>dbus-cleanup-sockets</command></term>
466 <listitem>
467 <para>
468 is used to clean up leftover sockets in a directory.
469 </para>
470 <indexterm zone="dbus dbus-cleanup-sockets">
471 <primary sortas="b-dbus-cleanup-sockets">dbus-cleanup-sockets</primary>
472 </indexterm>
473 </listitem>
474 </varlistentry>
475
476 <varlistentry id="dbus-daemon">
477 <term><command>dbus-daemon</command></term>
478 <listitem>
479 <para>
480 is the <application>D-Bus</application> message bus daemon.
481 </para>
482 <indexterm zone="dbus dbus-daemon">
483 <primary sortas="b-dbus-daemon">dbus-daemon</primary>
484 </indexterm>
485 </listitem>
486 </varlistentry>
487
488 <varlistentry id="dbus-launch">
489 <term><command>dbus-launch</command></term>
490 <listitem>
491 <para>
492 is used to start <command>dbus-daemon</command> from a shell
493 script. It would normally be called from a user's login
494 scripts.
495 </para>
496 <indexterm zone="dbus dbus-launch">
497 <primary sortas="b-dbus-launch">dbus-launch</primary>
498 </indexterm>
499 </listitem>
500 </varlistentry>
501
502 <varlistentry id="dbus-monitor">
503 <term><command>dbus-monitor</command></term>
504 <listitem>
505 <para>
506 is used to monitor messages going through a
507 <application>D-Bus</application> message bus.
508 </para>
509 <indexterm zone="dbus dbus-monitor">
510 <primary sortas="b-dbus-monitor">dbus-monitor</primary>
511 </indexterm>
512 </listitem>
513 </varlistentry>
514
515 <varlistentry id="dbus-run-session">
516 <term><command>dbus-run-session</command></term>
517 <listitem>
518 <para>
519 start a process as a new <application>D-Bus</application> session.
520 </para>
521 <indexterm zone="dbus dbus-run-session">
522 <primary sortas="b-dbus-run-session">dbus-run-session</primary>
523 </indexterm>
524 </listitem>
525 </varlistentry>
526
527 <varlistentry id="dbus-send">
528 <term><command>dbus-send</command></term>
529 <listitem>
530 <para>
531 is used to send a message to a <application>D-Bus</application>
532 message bus.
533 </para>
534 <indexterm zone="dbus dbus-send">
535 <primary sortas="b-dbus-send">dbus-send</primary>
536 </indexterm>
537 </listitem>
538 </varlistentry>
539
540 <varlistentry id="dbus-test-tool">
541 <term><command>dbus-test-tool</command></term>
542 <listitem>
543 <para>
544 <application>D-Bus</application> traffic generator and test tool; it
545 is a multi-purpose tool for debugging and profiling
546 <application>D-Bus</application>.
547 </para>
548 <indexterm zone="dbus dbus-test-tool">
549 <primary sortas="b-dbus-test-tool">dbus-test-tool</primary>
550 </indexterm>
551 </listitem>
552 </varlistentry>
553
554 <varlistentry id="dbus-update-activation-environment">
555 <term><command>dbus-update-activation-environment</command></term>
556 <listitem>
557 <para>
558 update environment used for <application>D-Bus</application> session
559 services; it updates the list of environment variables used by
560 <command>dbus-daemon --session</command> when it activates session
561 services without using systemd.
562 </para>
563 <indexterm zone="dbus dbus-update-activation-environment">
564 <primary sortas="b-dbus-update-activation-environment">
565 dbus-update-activation-environment</primary>
566 </indexterm>
567 </listitem>
568 </varlistentry>
569
570 <varlistentry id="dbus-uuidgen">
571 <term><command>dbus-uuidgen</command></term>
572 <listitem>
573 <para>
574 is used to generate a universally unique ID.
575 </para>
576 <indexterm zone="dbus dbus-uuidgen">
577 <primary sortas="b-dbus-uuidgen">dbus-uuidgen</primary>
578 </indexterm>
579 </listitem>
580 </varlistentry>
581
582 <varlistentry id="libdbus-1">
583 <term><filename class="libraryfile">libdbus-1.so</filename></term>
584 <listitem>
585 <para>
586 contains the API functions used by the
587 <application>D-Bus</application> message daemon.
588 <application>D-Bus</application> is first a library that provides
589 one-to-one communication between any two applications;
590 <command>dbus-daemon</command> is an application that uses this
591 library to implement a message bus daemon.
592 </para>
593 <indexterm zone="dbus libdbus-1">
594 <primary sortas="c-libdbus-1">libdbus-1.so</primary>
595 </indexterm>
596 </listitem>
597 </varlistentry>
598
599 </variablelist>
600
601 </sect2>
602
603</sect1>
604
Note: See TracBrowser for help on using the repository browser.