glfs/general/sysutils/dbus.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY dbus-download-http "http://dbus.freedesktop.org/releases/dbus-&dbus-version;.tar.gz">
  <!-- <!ENTITY dbus-download-ftp  "ftp://ftp.fu-berlin.de/unix/linux/mirrors/gentoo/distfiles/dbus-&dbus-version;.tar.gz"> -->
  <!ENTITY dbus-download-ftp  " ">
  <!ENTITY dbus-md5sum        "ba7692f63d0e9f1ef06703dff56cb650b">
  <!ENTITY dbus-size          "1.7 MB">
  <!ENTITY dbus-buildsize     "69.4 MB (includes building and installing all docs)">
  <!ENTITY dbus-time          "1.0 SBU">
]>

<sect1 id="dbus" xreflabel="D-BUS-&dbus-version;">
  <?dbhtml filename="dbus.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>D-BUS-&dbus-version;</title>

  <indexterm zone="dbus">
    <primary sortas="a-D-BUS">D-BUS</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to D-BUS</title>

    <para><application>D-BUS</application> is a message bus system, a simple
    way for applications to talk to one another.
    <application>D-BUS</application> supplies both a system daemon (for events
    such as <quote>new hardware device added</quote> or <quote>printer queue
    changed</quote>) 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
    applications to communicate directly (without going through the message bus
    daemon).</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&dbus-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&dbus-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &dbus-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &dbus-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &dbus-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &dbus-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">D-BUS Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="pkgconfig"/>,
    <xref linkend="expat"/> or <xref linkend="libxml2"/>,
    <xref linkend="glib2"/>,
    <xref linkend="gtk2"/>,
    <xref linkend="qt"/>,
    <ulink url="http://www.trolltech.com/products/qt">Qt-4.x.x</ulink>,
    <xref linkend="x-window-system"/>,
    <xref linkend="gcc"/> (for the Java compiler and tools),
    <ulink url="http://nz.cosc.canterbury.ac.nz/~greg/python/Pyrex/">Pyrex</ulink>
    (requires <xref linkend="python"/>),
    <ulink url="http://www.mono-project.com/GtkSharp">GtkSharp-1.0.x</ulink>
    (requires <ulink url="http://go-mono.org">Mono</ulink>),
    <ulink url="http://go-mono.com/sources-stable/">Monodoc</ulink>,
    <xref linkend="doxygen"/> (to generate the API documentation), and
    <ulink url="http://cyberelk.net/tim/xmlto/">xmlto</ulink>
    (to generate HTML documentation and manuals)</para>

    <para>Listed below are some additional notes about the dependencies</para>

    <itemizedlist spacing="compact">
      <listitem>
        <para>Review the information from running
        <command>./configure --help</command> for the available parameters to
        pass to the <command>configure</command> script to enable the various
        dependencies.</para>
      </listitem>
      <listitem>
        <para>To build the <application>Mono</application> bindings, you must
        have <application>GtkSharp</application> installed. If you wish to use
        recent versions of <application>GtkSharp</application>, you'll need to
        make some trivial patches to the <application>D-BUS</application>
        sources. See <ulink url="http://www.mono-project.com/GtkSharpUpgrade"/>
        for details.</para>
      </listitem>
      <listitem>
        <para>If you have a recent version of <ulink
        url="http://go-mono.com/sources-stable/">Monodoc</ulink> installed
        (&gt;= 1.1.10) and you passed the <option>--enable-mono-docs</option>
        parameter to <command>configure</command>, the
        <application>D-BUS</application> build will fail. You can review the
        parts of this patch (<ulink
        url="http://www.mail-archive.com/frugalware-darcs@frugalware.org/msg10156.html"/>)
        that apply to the <application>Monodoc</application> installation, to
        fix the build problems. Note this is untested by the BLFS Team, but
        should work just fine.</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect4" id="hal-requirements"
    xreflabel="HAL Requirements">HAL Requirements</bridgehead>

    <para><xref linkend="glib2"/> must be installed before you begin building
    <application>D-BUS</application> if you plan on installing
    <xref linkend="hal"/>. <application>GLib</application> is required to build
    the <filename class='libraryfile'>libdbus-glib</filename> library, which is
    required by the <application>HAL</application> daemon.</para>

    <para>If you plan on using <application>HAL</application> with
    <application>KDE</application>, you'll need to link
    <application>D-BUS</application> with the <application>Qt</application>
    libraries. Ensure you've installed <application>Qt</application> before
    beginning the <application>D-BUS</application> installation.</para>

    <para>If you desire to use the <xref linkend="hal-device-manager"/>
    program, <ulink url="http://nz.cosc.canterbury.ac.nz/~greg/python/Pyrex/">
    Pyrex</ulink> must be installed before you begin building
    <application>D-BUS</application> as the <application>D-BUS</application>
    <application>Python</application> bindings are required. You will also
    need to remove the <parameter>--disable-python</parameter> parameter from
    the <command>configure</command> command in the instructions below.</para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/dbus"/></para>

  </sect2>

  <sect2 role="kernel" id='dbus-kernel'>
    <title>Kernel Configuration</title>

    <para>Ensure the following option is enabled in the kernel configuration
    and recompile the kernel if necessary:</para>

<screen><literal>General Setup
  System V IPC</literal></screen>

    <indexterm zone="dbus dbus-kernel">
      <primary sortas="d-dbus">dbus</primary>
    </indexterm>

  </sect2>

  <sect2 role="installation">
    <title>Installation of D-BUS</title>

    <para>As the <systemitem class="username">root</systemitem> user, create a
    system user and group to handle the system message bus activity:</para>

<screen role="root"><userinput>groupadd -g 18 messagebus &amp;&amp;
useradd -c "D-BUS Message Daemon User" -d /dev/null \
        -u 18 -g messagebus -s /bin/false messagebus</userinput></screen>

    <para>Install <application>D-BUS</application> by running the following
    commands (you may wish to review the output from
    <command>./configure --help</command> first and add any desired parameters
    to the <command>configure</command> command shown below):</para>

<screen><userinput>./configure --prefix=/usr \
            --sysconfdir=/etc \
            --localstatedir=/var \
            --disable-python &amp;&amp;
make</userinput></screen>

    <para>The <option>--enable-doxygen-docs</option> parameter does not work
    properly. If you have <application>Doxygen</application> installed and you
    wish to build the API documentation, issue
    <command>doxygen</command>.</para>

    <para>This package's test suite cannot be run without passing additional
    parameters to <command>configure</command>. These parameters are not
    intended to be used in a production build of
    <application>D-BUS</application> so you will have to build twice (issuing
    <command>make distclean</command> after the first build) if you
    want to run the regression tests.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;
install -v -m755 -d /usr/share/doc/dbus-&dbus-version; &amp;&amp;
install -v -m644 doc/{TODO,*.{dtd,xml,xsl,html,txt,c}} \
    /usr/share/doc/dbus-&dbus-version;</userinput></screen>

    <para>If you built the API documentation, install it by issuing the
    following commands as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m755 -d /usr/share/doc/dbus-&dbus-version;/api &amp;&amp;
install -v -m644 doc/api/html/* \
    /usr/share/doc/dbus-&dbus-version;/api</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>--localstatedir=/var</parameter>: This parameter causes
    the daemon PID file to be created in
    <filename class="directory">/var/run/dbus</filename> instead of
    <filename class="directory">/usr/var/run/dbus</filename>.</para>

    <para><parameter>--disable-python</parameter>: This parameter is required
    if <application>Python</application> is not installed. Remove the parameter
    if <application>Python</application> (and <application>Pyrex</application>)
    is installed and you wish to build the
    <application>Python</application> bindings.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring dbus</title>

    <sect3 id="dbus-config">
      <title>Config Files</title>
      <para><filename>/etc/dbus-1/session.conf</filename>,
      <filename>/etc/dbus-1/system.conf</filename> and
      <filename>/etc/dbus-1/system.d/*</filename></para>

      <indexterm zone="dbus dbus-config">
        <primary sortas="e-etc-dbus-1-session.conf">/etc/dbus-1/session.conf</primary>
      </indexterm>

      <indexterm zone="dbus dbus-config">
        <primary sortas="e-etc-dbus-1/system.conf">/etc/dbus-1/system.conf</primary>
      </indexterm>

      <indexterm zone="dbus dbus-config">
        <primary sortas="e-etc-dbus-1-system.d-star">/etc/dbus-1/system.d/*</primary>
      </indexterm>

    </sect3>

    <sect3><title>Configuration Information</title>

      <para>The configuration files listed above should probably not be
      modified. If changes are required, you should create
      <filename>/etc/dbus-1/session-local.conf</filename> and/or
      <filename>/etc/dbus-1/system-local.conf</filename> and make any
      desired changes to these files.</para>

    </sect3>

    <sect3  id="dbus-init">
      <title>Boot Script</title>

      <para>To automatically start <command>dbus-daemon</command> when the
      system is rebooted, install the
      <filename>/etc/rc.d/init.d/dbus</filename> bootscript from the
      <xref linkend="bootscripts"/> package.</para>

      <indexterm zone="dbus dbus-init">
        <primary sortas="f-dbus">dbus</primary>
      </indexterm>

<screen role="root"><userinput>make install-dbus</userinput></screen>

      <para>Note that this boot script only starts the system-wide
      <application>D-BUS</application> daemon. Each user requiring access to
      <application>D-BUS</application> services will also need to run a
      session daemon as well. There are many methods you can use to start a
      session daemon using the <command>dbus-launch</command> command. Review
      the <command>dbus-launch</command> man page for details about the
      available parameters and options. Here are some suggestions and
      examples:</para>

      <itemizedlist spacing="compact">
        <listitem>
          <para>Add <command>dbus-launch</command> to the line in the
          <filename>~/.xinitrc</filename> file that starts your graphical
          desktop environment as shown in <xref linkend="gnome-config"/>.</para>
        </listitem>
        <listitem>
          <para>If you use <command>xdm</command> or some other display manager
          that calls the <filename>~/.xsession</filename> file, you can add
          <command>dbus-launch</command> to the line in your
          <filename>~/.xsession</filename> file that starts your graphical
          desktop environment. The syntax would be similar to the example in
          the <filename>~/.xinitrc</filename> file.</para>
        </listitem>
        <listitem>
          <para>If you use <command>gdm</command> or some other display manager
          that utilizes custom files to initiate sessions, use the example in
          <xref linkend="gdm-config-dbus"/> of the
          <application>GDM</application> instructions to create a file
          containing <command>dbus-launch</command>.</para>
        </listitem>
        <listitem>
          <para>The examples shown previously use
          <command>dbus-launch</command> to specify a program to be run. This
          has the benefit (when also using the
          <parameter>--exit-with-session</parameter> parameter) of stopping the
          session daemon when the specified program is stopped. You can also
          start the session daemon in your system or personal startup scripts
          by adding the following lines:</para>

<screen><userinput><literal># Start the D-BUS session daemon
eval `dbus-launch`
export DBUS_SESSION_BUS_ADDRESS</literal></userinput></screen>

          <para>This method will not stop the session daemon when you exit
          your shell, therefore you should add the following line to your
          <filename>~/.bash_logout</filename> file:</para>

<screen><userinput><literal># Kill the D-BUS session daemon
kill $DBUS_SESSION_BUS_PID</literal></userinput></screen>
        </listitem>

        <listitem>
          <para>A hint has been written that provides ways to start scripts
          using the KDM session manager of KDE. The concepts in this hint could
          possibly used with other session managers as well. The hint is
          located at <ulink
          url="&hints-root;/downloads/files/execute-session-scripts-using-kdm.txt"/>.
          </para>
        </listitem>

      </itemizedlist>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>dbus-binding-tool, dbus-cleanup-sockets, dbus-daemon, dbus-launch,
        dbus-monitor, dbus-send and dbus-viewer</seg>
        <seg>libdbus-1.{so,a} and optionally, dbus-1.jar, libdbus-gcj-1.{so,a},
        libdbus-glib-1.{so,a}, libdbus-qt-1.{so,a}, libdbus-qt4-1.{so,a},
        libdbus-mono-1.{so,a} and <application>Python</application>
        modules</seg>
        <seg>/etc/dbus-1, /usr/include/dbus-1.0, /usr/lib/dbus-1.0,
        /usr/lib/python2.4/site-packages/dbus, /usr/share/dbus-1,
        /usr/share/doc/dbus-&dbus-version; and /var/run/dbus</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="dbus-binding-tool">
        <term><command>dbus-binding-tool</command></term>
        <listitem>
          <para>is used to create header files from
          <application>GLib</application> object files.</para>
          <indexterm zone="dbus dbus-binding-tool">
            <primary sortas="b-dbus-binding-tool">dbus-binding-tool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-cleanup-sockets">
        <term><command>dbus-cleanup-sockets</command></term>
        <listitem>
          <para>is used to clean up leftover sockets in a directory.</para>
          <indexterm zone="dbus dbus-cleanup-sockets">
            <primary sortas="b-dbus-cleanup-sockets">dbus-cleanup-sockets</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-daemon">
        <term><command>dbus-daemon</command></term>
        <listitem>
          <para>is the <application>D-BUS</application> message bus
          daemon.</para>
          <indexterm zone="dbus dbus-daemon">
            <primary sortas="b-dbus-daemon">dbus-daemon</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-launch">
        <term><command>dbus-launch</command></term>
        <listitem>
          <para>is used to start <command>dbus-daemon</command> from a shell
          script. It  would  normally be called from a user's login
          scripts.</para>
          <indexterm zone="dbus dbus-launch">
            <primary sortas="b-dbus-launch">dbus-launch</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-monitor">
        <term><command>dbus-monitor</command></term>
        <listitem>
          <para>is used to monitor messages going through a
          <application>D-BUS</application> message bus.</para>
          <indexterm zone="dbus dbus-monitor">
            <primary sortas="b-dbus-monitor">dbus-monitor</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-send">
        <term><command>dbus-send</command></term>
        <listitem>
          <para>is used to send a message to a <application>D-BUS</application>
          message bus.</para>
          <indexterm zone="dbus dbus-send">
            <primary sortas="b-dbus-send">dbus-send</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbus-viewer">
        <term><command>dbus-viewer</command></term>
        <listitem>
          <para>is a graphical <application>D-BUS</application> frontend
          utility.</para>
          <indexterm zone="dbus dbus-viewer">
            <primary sortas="b-dbus-viewer">dbus-viewer</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libdbus-1">
        <term><filename class='libraryfile'>libdbus-1.{so,a}</filename></term>
        <listitem>
          <para>contains the API functions used by the
          <application>D-BUS</application> message daemon.
          <application>D-BUS</application> is first a library that provides
          one-to-one communication between any two applications;
          <command>dbus-daemon</command> is an application that uses this
          library to implement a message bus daemon.</para>
          <indexterm zone="dbus libdbus-1">
            <primary sortas="c-libdbus-1">libdbus-1.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>