source: x/lib/cairo.xml@ 97ccf511

<?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 cairo-download-http "http://cairographics.org/releases/cairo-&cairo-version;.tar.gz">
  <!ENTITY cairo-download-ftp  " ">
  <!ENTITY cairo-md5sum        "e6c85575ba7094f88b637bdfd835a751">
  <!ENTITY cairo-size          "61 MB">
  <!ENTITY cairo-buildsize     "170 MB (up to an additional 454 MB to run the test suite)">
  <!ENTITY cairo-time          "0.8 SBU (up to an additional 2 SBU to run the test suite)">
]>

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

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

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

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

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

    <para><application>Cairo</application> is a 2D graphics library with
    support for multiple output devices. Currently supported output targets
    include the <application>X</application> Window System, win32, image
    buffers, PostScript, PDF and SVG. Experimental backends include OpenGL
    Quartz and XCB file output. cairo is designed to produce consistent output
    on all output media while taking advantage of display hardware acceleration
    when available (e.g., through the X Render Extension). The
    <application>Cairo</application> API provides operations similar to the
    drawing operators of PostScript and PDF. Operations in
    <application>Cairo</application> include stroking and filling cubic
    B&eacute;zier splines, transforming and compositing translucent images, and
    antialiased text rendering. All drawing operations can be transformed by
    any <ulink url="http://en.wikipedia.org/wiki/Affine_transformation">affine
    transformation</ulink> (scale, rotation, shear, etc.).</para>

    &lfs71_checked;

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

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

    <!-- Cairo is here only because GTK+ and friends, so I'll make Xorg Libraries
    a dependency here -->
    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="fontconfig"/>, <xref linkend="libpng"/>,
    <xref linkend="pixman"/>, <xref linkend="pkgconfig"/> and 
    <xref linkend="xorg7-lib"/></para>

    <!-- I've never seen any package that needs Cairo GL backend -->
    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="cogl"/>,
    <ulink url="http://www.directfb.org/">DirectFB</ulink>,
    <xref linkend="libdrm"/>,
    <xref linkend="gtk-doc"/>,
    <xref linkend="mesalib"/>,
    <xref linkend="qt4"/>,
    <ulink url="http://code.google.com/p/skia/">Skia</ulink> and
    <ulink url="http://www.valgrind.org">Valgrind</ulink></para>

    <bridgehead renderas="sect4">Optional (to provide extended test suite
    coverage)</bridgehead>
    <para role="optional"><xref linkend="gs"/> (to test the postscript
    backend), <xref linkend="gtk2"/> (for testing the PDF backend),
    <xref linkend="poppler"/> (for testing the PDF backend),
    <ulink url="http://libspectre.freedesktop.org">libspectre</ulink> (to test
    the PDF backend) and <xref linkend="librsvg"/> (for testing the SVG
    backend)</para>

    <note><para>There is a reciprocal dependency with cairo and libdrm. Best
    practice is to install cairo without the OpenGL backend, and return to
    re-install cairo after the full Xorg installation has been completed. Also
    note that the GTK, Poppler and librsvg packages are also reciprocal. As the
    test suite is currently unreliable, it is best to simply skip it at this
    time.</para></note>

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

  </sect2>

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

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

<screen><userinput>./configure --prefix=/usr \
            --enable-tee --enable-xcb &amp;&amp;
make</userinput></screen>

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

    <para>Note that the tests take a long time to run and many of them fail for
    unknown reasons.</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>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
    href="../../xincludes/gtk-doc-rebuild.xml"/>

    <para><option>--enable-tee</option>: This is used by
    <application>Firefox</application>. If you don't enable the Cairo's tee
    surface backend you won't be able to build
    <application>Firefox</application> with
    <option>--enable-system-cairo</option>.</para>

    <para><option>--enable-drm</option>: Enable 
    <application>Cairo</application>'s libdrm backend.</para>

    <para><option>--enable-gl</option>: Enable
    <application>Cairo</application>'s OpenGL backend.</para>

    <para><option>--enable-xcb</option>: Enable
    <application>Cairo</application>'s libxcb backend.
    </para>

    <para><option>--enable-vg</option>: Enable the
    <application>Cairo</application> 
    <ulink url="http://en.wikipedia.org/wiki/OpenVG">OpenVG</ulink> backend 
    (requires <xref linkend="mesalib"/> installed, configured with
    --enable-gallium-egl and --enable-openvg).</para>

    <para><option>--disable-static</option>: Prevent static libraries being
    built and installed.</para>

  </sect2>

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

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

      <seglistitem>
        <seg>cairo-sphinx and cairo-trace</seg>
        <seg>libcairo.{so,a}, libcairo-gobject.{so,a} and
        libcairo-script-interpreter.{so,a}</seg>
        <seg>/usr/include/cairo, /usr/lib/cairo and
        /usr/share/gtk-doc/html/cairo</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="cairo-trace">
        <term><command>cairo-trace</command></term>
        <listitem>
          <para>generates a log of all calls made by an application to
          <application>Cairo</application>.</para>
          <indexterm zone="cairo cairo-trace">
            <primary sortas="b-cairo-trace">cairo-trace</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libcairo">
        <term><filename class='libraryfile'>libcairo.{so,a}</filename></term>
        <listitem>
          <para>contains the 2D graphics functions required for rendering to
          the various output targets.</para>
          <indexterm zone="cairo libcairo">
            <primary sortas="c-libcairo">libcairo.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libcairo-gobject">
        <term><filename class='libraryfile'>libcairo-gobject.{so,a}</filename></term>
        <listitem>
          <para>contains functions that integrate
          <application>Cairo</application> with <xref linkend="glib2"/>'s
          GObject type system.</para>
          <indexterm zone="cairo libcairo-gobject">
            <primary sortas="c-libcairo-gobject">libcairo-gobject.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libcairo-script-interpreter">
        <term><filename class='libraryfile'>libcairo-script-interpreter.{so,a}</filename></term>
        <listitem>
          <para>contains the script interpreter functions for executing and
          manipulating <application>Cairo</application> execution traces.</para>
          <indexterm zone="cairo libcairo-script-interpreter">
            <primary sortas="c-libcairo-script-interpreter">libcairo-script-interpreter.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>