source: x/installing/libxcb.xml@ 2626874

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

  <!ENTITY libxcb-download-http "http://xcb.freedesktop.org/dist/libxcb-&libxcb-version;.tar.bz2">
  <!ENTITY libxcb-download-ftp  "ftp://ftp.x.org/pub/current/src/extras/libxcb-&libxcb-version;.tar.bz2">
  <!ENTITY libxcb-md5sum        "0eb951fd0fa9542dbe4fc3530b81a3b6">
  <!ENTITY libxcb-size          "410 KB">
  <!ENTITY libxcb-buildsize     "15.0 MB">
  <!ENTITY libxcb-time          "0.4 SBU">
]>

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

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

  <title>libxcb-&libxcb-version;</title>

  <indexterm zone="libxcb">
    <primary sortas="a-libxcb">libxcb</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to libxcb</title>

    <para>The <application>libxcb</application> package provides an interface
    to the X Window System protocol, which replaces the current Xlib interface.
    Xlib can also use XCB as a transport layer, allowing software to make
    requests and receive responses with both.</para>

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

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Required patch to workaround X11 locking bugs in other
        applications: <ulink
        url="&patch-root;/libxcb-&libxcb-version;-sloppy_lock-1.patch"/></para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">libxcb Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="libXau"/>,
    <xref linkend="libXdmcp"/>,
    <xref linkend="libpthread-stubs"/>,
    <xref linkend="xcb-proto"/>, and
    <xref linkend="libxslt"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="doxygen"/> (to generate API
    documentation) and <ulink url="http://check.sourceforge.net/">Check</ulink>
    (to run tests)</para>

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

  </sect2>

  <sect2 role="installation">
    <title>Installation of libxcb</title>

    <para>Install <application>libxcb</application> by running the following
    commands:</para>

<screen><userinput>patch -Np1 -i ../libxcb-&libxcb-version;-sloppy_lock-1.patch &amp;&amp;
./configure $XORG_CONFIG --docdir='${datadir}'/doc/libxcb-&libxcb-version; &amp;&amp;
make</userinput></screen>

    <para>To test the results, issue: <command>make check</command>.</para>

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

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

  </sect2>

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

    <para><parameter>--docdir='${datadir}'/doc/libxcb-&libxcb-version;</parameter>:
    This parameter ensures the <application>libxcb</application> documentation
    is installed to a versioned directory.</para>

    <para><parameter>--without-doxygen</parameter>: This switch can be used
    to disable the API documentation if <xref linkend="doxygen"/> is
    installed.</para>

  </sect2>

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

    <sect3 id="libxcb-config">
      <title>Configuration Information</title>

      <para>The <application>libxcb</application> developers have decided
      to be strict in asserting locking bugs in X11 applications. This is
      different than the behavior of <application>libX11</application> when
      used on its own, and it will cause some applications to crash when
      they previously did not. When an application has these types of bugs,
      it will crash with the following assertion:</para>

<screen><literal>xcb_xlib_lock: Assertion `!c->xlib.lock' failed.</literal></screen>

      <para>The patch applied above to <application>libxcb</application> adds
      an environment variable, <envar>LIBXCB_ALLOW_SLOPPY_LOCK</envar>, to
      be set which will allow the locking bugs to not crash the application.
      It is a workaround that is known to be needed in a few cases. If it is
      found that these bugs affect an application in use, add the following
      to your system or personal profile:</para>

<screen><literal>export LIBXCB_ALLOW_SLOPPY_LOCK=1</literal></screen>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>None</seg>
        <seg>libxcb.{so,a} and libxcb-*.{so,a}</seg>
        <seg><envar>$XORG_PREFIX</envar>/include/xcb and
        <envar>$XORG_PREFIX</envar>/share/doc/libxcb-&libxcb-version;</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="libxcb-lib">
        <term><filename class='libraryfile'>libxcb.{so,a}</filename></term>
        <listitem>
          <para>is an interface to the X Window System protocol.</para>
          <indexterm zone="libxcb libxcb-lib">
            <primary sortas="c-libxcb">libxcb.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>