source: x/lib/cairo.xml@ 1f7aca6

<?xml version="1.0" encoding="UTF-8"?>
<!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 "https://www.cairographics.org/releases/cairo-&cairo-version;.tar.xz">
  <!ENTITY cairo-download-ftp  " ">
  <!ENTITY cairo-md5sum        "5ad67c707edd0003f1b91c8bbc0005c1">
  <!ENTITY cairo-size          "31 MB">
  <!ENTITY cairo-buildsize     "93 MB">
  <!ENTITY cairo-time          "0.2 SBU (Using parallelism=4)">
]>

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


  <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="https://en.wikipedia.org/wiki/Affine_transformation">affine
      transformation</ulink> (scale, rotation, shear, etc.)
    </para>

    &lfs122_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:
          <ulink url="&patch-root;/cairo-&cairo-version;-upstream_fixes-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="libpng"/> and
      <xref linkend="pixman"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="fontconfig"/>,
      <xref linkend="glib2"/> (required for most GUIs), and
      <xref linkend="xorg7-lib"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gs"/>,
      <xref linkend="gtk-doc"/>,
      <xref linkend="libdrm"/>,
      <xref linkend="librsvg"/>,
      <xref linkend="libxml2"/>,
      <xref linkend="lzo"/>,
      <xref linkend="poppler"/>,
      <xref linkend="valgrind"/>,
      &gtk2;, and
      <ulink url="https://www.freedesktop.org/wiki/Software/libspectre/">libspectre</ulink>
    </para>

    <note>
      <para>
        There is a circular dependency between cairo and harfbuzz.
        If cairo is built before harfbuzz, it is necessary to rebuild cairo
        after harfbuzz in order to build pango.
      </para>
    </note>

  </sect2>

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

    <para>
      First, fix a bug that causes problems with printing PDF files:
    </para>

<screen><userinput remap="pre">patch -Np1 -i ../cairo-&cairo-version;-upstream_fixes-1.patch</userinput></screen>

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

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup --prefix=/usr --buildtype=release .. &amp;&amp;
ninja</userinput></screen>

    <para>
      This package does not have a working test suite.
      <!-- The test suite can be run with 'ninja test', but 488 tests fail and
      59 tests pass. This seems to be due to minute changes in the expected
      output, similar to librsvg's tests. Since it's a huge chunk of the tests,
      let's keep it as "broken" for now.-->
    </para>

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

<screen role="root"><userinput>ninja install</userinput></screen>
  </sect2>

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

<!-- Enabled by default in 1.18.0 (would be -D tee=enabled otherwise)
    <para>
      <parameter>- -enable-tee</parameter>: This switch enables the
      experimental tee surface backend which is required if using
      system-installed <application>Cairo</application> with Mozilla applications.
    </para>
-->

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

    <para>
      <option>-D xlib-xcb=enabled</option>: This switch enables several
      experimental Xlib/XCB functions used by some window managers.
    </para>

    <para>
      <option>-D gtk_doc=true</option>: Use this parameter if GTK-Doc is
      installed and you wish to create and install the documentation.
    </para>

  </sect2>

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

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

      <seglistitem>
        <seg>
          cairo-trace
        </seg>
        <seg>
          libcairo.so,
          libcairo-gobject.so, and
          libcairo-script-interpreter.so
        </seg>
        <seg>
          /usr/include/cairo and
          /usr/lib/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
            <application>Glib</application>'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>