source: x/lib/cairo.xml@ 852f5146

<?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        "a5067e355e78294db2485aa97afd1115">
  <!ENTITY cairo-size          "6.7 MB">
  <!ENTITY cairo-buildsize     "27 MB (without static libs, additional 270 MB to run the test suite)">
  <!ENTITY cairo-time          "0.3 SBU (additional 2.9 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
    (through glitz), 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ézier splines, transforming and compositing translucent images, and
    antialiased text rendering. All drawing operations can be transformed by
    any affine transformation (scale, rotation, shear, etc.).</para>

    <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>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="x-window-system"/> and
    <xref linkend="pkgconfig"/></para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="optional"><ulink
    url="http://xcb.freedesktop.org/dist/xcb-util-0.3.0.tar.bz2">
    xcb-util-0.3.0</ulink> and<ulink
    url="http://www.cairographics.org/releases/pixman-0.12.0.tar.gz">
    pixman-0.12.0</ulink>.</para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><ulink
    url="http://www.freedesktop.org/Software/glitz">glitz</ulink>,
    <ulink url="http://www.directfb.org/">DirectFB</ulink>,
    <ulink url="http://openquartz.sourceforge.net/">Open Quartz</ulink>,
    <xref linkend="libxcb"/> (also requires
    <ulink url="http://xcb.freedesktop.org/dist/">xcb-util</ulink>), and
    <xref linkend="gtk-doc"/></para>

    <bridgehead renderas="sect4">Optional (to provide extended test suite
    coverage)</bridgehead>
    <para role="optional"><xref linkend="gtk2"/> (for testing the PDF backend),
    <xref linkend="poppler"/> (for testing the PDF backend),
    <xref linkend="librsvg"/> (for testing the SVG backend).
    <!-- [ comment this pending clarification - not presently required] , and
    <ulink url="http://ltp.sourceforge.net/">LTP</ulink>--></para>

    <para>Note that the GTK, Poppler and librsvg packages are circular in that
    using them for test suite coverage requires installing cairo first,
    then installing the desired package(s), then installing cairo again.</para>

    <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-xcb=yes &amp;&amp;
make</userinput></screen>

    <para>To test the results, issue: <command>make check</command>. Note that
    as many as 24 of the tests are known to fail for unknown reasons.
    If you do not have a <command>gs</command> binary in your path, many
    <!-- used to be (87 of $total), needs to be updated by someone who can
    get them to run through without hanging -->
    of the 205 tests will fail. Also, to enhance test
    coverage, the tests should be run with an available X Window screen (e.g.
    from a local xterm or equivalent window).</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/2003/XInclude"
    href="../../xincludes/gtk-doc-rebuild.xml"/>

    <para><parameter>--enable-xcb=yes</parameter>: Enable the xcb
    back end. Omit this if you did not install xcb-util and pixman.</para>

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

  </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>libcairo.{so,a}</seg>
        <seg>/usr/include/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="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>

    </variablelist>

  </sect2>

</sect1>