source: x/lib/cairo.xml@ 1497c445

<?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.xz">
  <!ENTITY cairo-download-ftp  " ">
  <!ENTITY cairo-md5sum        "87649eb75789739d517c743e94879e51">
  <!ENTITY cairo-size          "41 MB">
  <!ENTITY cairo-buildsize     "178 MB">
  <!ENTITY cairo-time          "1.1 SBU">
]>

<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. <application>Cairo</application> 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>

    &lfs72_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">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch (if you intend to compile any Mozilla products):
          <ulink url="&patch-root;/cairo-&cairo-version;-expose-snapshot-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <!-- Just a note: png is REQUIRED, since something that isn't REQUIRED
      does not need bunch of DISABLE switches. You are breaking the package
      for those that don't want to install recommended deps, and I've seen
      lot of people like that. Leave it, it is not a big dep, and I suspect
      that someone will install cairo just to test gobject-introspection, since
      I doubt someone will need that unless building gnome stuff, and it is 
      really wrong way of thinking that someone might need cairo JUST to test
      introspection. No offense. -->
      <xref linkend="libpng"/>,
      <xref linkend="glib2"/> and
      <xref linkend="pixman"/>
    </para>

    <bridgehead renderas="sect4">Recommended (Required if building GTK+)</bridgehead>
    <para role="recommended">
      <xref linkend="fontconfig"/>,
      <xref linkend="xorg7-lib"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="cogl"/>,
      <ulink url="http://www.directfb.org/">DirectFB</ulink>,
      <xref linkend="gs"/> (for testing the postscript backend),
      <xref linkend="gtk2"/> (for testing the PDF backend),
      <xref linkend="gtk-doc"/>,
      <xref linkend="libdrm"/>,
      <xref linkend="librsvg"/> (for testing the SVG backend),
      <ulink url="http://libspectre.freedesktop.org">libspectre</ulink> (for
      testing the PDF backend),
      <xref linkend="mesalib"/>,
      <xref linkend="poppler"/> (for testing the PDF backend),
      <xref linkend="qt"/>,
      <ulink url="http://code.google.com/p/skia/">Skia</ulink> and
      <ulink url="http://www.valgrind.org">Valgrind</ulink>.
    </para>

    <note>
      <para>
        There is a reciprocal dependency with the
        <application>GTK+ 2</application>, <application>librsvg</application> and
        <application>Poppler</application> packages. 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>sed -i 's#check-plt.sh ##' src/Makefile.in &amp;&amp;
patch -p1 &lt; ../cairo-&cairo-version;-expose-snapshot-1.patch &amp;&amp;
./configure --prefix=/usr --disable-static --enable-tee --enable-xcb &amp;&amp;
make</userinput></screen>

    <para>
      Note that the tests take a long time to run, many of them fail for unknown
      reasons and it has been known to cause a kernel panic. If you want to run
      the tests issue: <command>make -k 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>
      <command>sed -i 's#check-plt.sh ##' src/Makefile.in</command>: This sed
      disables running a test which is known to fail with the expose-snapshot
      patch.
    </para>

    <para>
      <command>patch -p1 &lt;
      ../cairo-&cairo-version;-expose-snapshot-1.patch</command>: This patch
      exposes some private functions that <application>Firefox</application>
      relies on. Applying this patch allows <application>Firefox</application>
      to use the system installed <application>Cairo</application>.
    </para>

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

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

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

  </sect2>

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

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

      <seglistitem>
        <seg>
          cairo-sphinx and cairo-trace
        </seg>
        <seg>
          libcairo.so, libcairo-gobject.so and
          libcairo-script-interpreter.so
        </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</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</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libcairo-gobject">
        <term><filename class='libraryfile'>libcairo-gobject.so</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</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libcairo-script-interpreter">
        <term><filename class='libraryfile'>libcairo-script-interpreter.so</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</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>