<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="cairo-Version-Information">
<refmeta>
<refentrytitle role="top_of_page">Version Information</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>CAIRO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Version Information</refname>
<refpurpose>Compile-time and run-time version checks.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>



#define     <link linkend="CAIRO-VERSION:CAPS">CAIRO_VERSION</link>
#define     <link linkend="CAIRO-VERSION-MAJOR:CAPS">CAIRO_VERSION_MAJOR</link>
#define     <link linkend="CAIRO-VERSION-MINOR:CAPS">CAIRO_VERSION_MINOR</link>
#define     <link linkend="CAIRO-VERSION-MICRO:CAPS">CAIRO_VERSION_MICRO</link>
#define     <link linkend="CAIRO-VERSION-STRING:CAPS">CAIRO_VERSION_STRING</link>
#define     <link linkend="CAIRO-VERSION-ENCODE:CAPS">CAIRO_VERSION_ENCODE</link>            (major, minor, micro)
<link linkend="int">int</link>         <link linkend="cairo-version">cairo_version</link>                   (void);
const <link linkend="char">char</link>* <link linkend="cairo-version-string">cairo_version_string</link>            (void);
</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
Cairo has a three-part version number scheme. In this scheme, we use
even vs. odd numbers to distinguish fixed points in the software
vs. in-progress development, (such as from CVS instead of a tar file,
or as a "snapshot" tar file as opposed to a "release" tar file).
</para>
<para>
<informalexample><programlisting>
 _____ Major. Always 1, until we invent a new scheme.
/  ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (CVS)
| /  _ Micro. Even/Odd = Tar-file/CVS
| | /
1.0.0
</programlisting></informalexample>
</para>
<para>
Here are a few examples of versions that one might see.
<informalexample><programlisting>
Releases
--------
1.0.0 - A major release
1.0.2 - A subsequent maintenance release
1.2.0 - Another major release

Snapshots
---------
1.1.2 - A snapshot (working toward the 1.2.0 release)

In-progress development (eg. from CVS)
--------------------------------------
1.0.1 - Development on a maintenance branch (toward 1.0.2 release)
1.1.1 - Development on head (toward 1.1.2 snapshot and 1.2.0 release)
</programlisting></informalexample>
</para>

<refsect2>
<title>Compatibility</title>
<para>
The API/ABI compatibility guarantees for various versions are as
follows. First, let's assume some cairo-using application code that is
successfully using the API/ABI "from" one version of cairo. Then let's
ask the question whether this same code can be moved "to" the API/ABI
of another version of cairo.
</para>

<para>
Moving from a release to any later version (release, snapshot,
development) is always guaranteed to provide compatibility.
</para>

<para>
Moving from a snapshot to any later version is not guaranteed to
provide compatibility, since snapshots may introduce new API that ends
up being removed before the next release.
</para>

<para>
Moving from an in-development version (odd micro component) to any
later version is not guaranteed to provide compatibility. In fact,
there's not even a guarantee that the code will even continue to work
with the same in-development version number. This is because these
numbers don't correspond to any fixed state of the software, but
rather the many states between snapshots and releases.
</para>
</refsect2>

<refsect2>
<title>Examining the version</title>
<para>
Cairo provides the ability to examine the version at either
compile-time or run-time and in both a human-readable form as well as
an encoded form suitable for direct comparison. Cairo also provides a
macro (CAIRO_VERSION_ENCODE) to perform the encoding.
</para>

<para>
<informalexample><programlisting>
Compile-time
------------
<link linkend="CAIRO-VERSION-STRING:CAPS"><literal>CAIRO_VERSION_STRING</literal></link>	Human-readable
<link linkend="CAIRO-VERSION:CAPS"><literal>CAIRO_VERSION</literal></link>		Encoded, suitable for comparison

Run-time
--------
<link linkend="cairo-version-string"><function>cairo_version_string()</function></link>	Human-readable
<link linkend="cairo-version"><function>cairo_version()</function></link>		Encoded, suitable for comparison
</programlisting></informalexample>
</para>

<para>
For example, checking that the cairo version is greater than or equal
to 1.0.0 could be achieved at compile-time or run-time as follows:

<informalexample><programlisting>
#<link linkend="if"><type>if</type></link> <link linkend="CAIRO-VERSION:CAPS"><literal>CAIRO_VERSION</literal></link> >= <link linkend="CAIRO-VERSION-ENCODE:CAPS"><literal>CAIRO_VERSION_ENCODE</literal></link>(1, 0, 0)
printf ("Compiling with suitable cairo version: %<link linkend="s"><literal>s</literal></link>\n", CAIRO_VERSION_STRING);
#<link linkend="endif"><type>endif</type></link>

if (<link linkend="cairo-version"><function>cairo_version()</function></link> >= <link linkend="CAIRO-VERSION-ENCODE:CAPS"><literal>CAIRO_VERSION_ENCODE</literal></link>(1, 0, 0))
    printf ("Running with suitable cairo version: %<link linkend="s"><literal>s</literal></link>\n", <link linkend="cairo-version-string"><function>cairo_version_string()</function></link>);
</programlisting></informalexample>
</para>
</refsect2>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="CAIRO-VERSION:CAPS" role="macro"/>CAIRO_VERSION</title>
<indexterm><primary>CAIRO_VERSION</primary></indexterm><programlisting>#define     CAIRO_VERSION</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="CAIRO-VERSION-MAJOR:CAPS" role="macro"/>CAIRO_VERSION_MAJOR</title>
<indexterm><primary>CAIRO_VERSION_MAJOR</primary></indexterm><programlisting>#define CAIRO_VERSION_MAJOR 1
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="CAIRO-VERSION-MINOR:CAPS" role="macro"/>CAIRO_VERSION_MINOR</title>
<indexterm><primary>CAIRO_VERSION_MINOR</primary></indexterm><programlisting>#define CAIRO_VERSION_MINOR 2
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="CAIRO-VERSION-MICRO:CAPS" role="macro"/>CAIRO_VERSION_MICRO</title>
<indexterm><primary>CAIRO_VERSION_MICRO</primary></indexterm><programlisting>#define CAIRO_VERSION_MICRO 4
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="CAIRO-VERSION-STRING:CAPS" role="macro"/>CAIRO_VERSION_STRING</title>
<indexterm><primary>CAIRO_VERSION_STRING</primary></indexterm><programlisting>#define CAIRO_VERSION_STRING "1.2.4"
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="CAIRO-VERSION-ENCODE:CAPS" role="macro"/>CAIRO_VERSION_ENCODE()</title>
<indexterm><primary>CAIRO_VERSION_ENCODE</primary></indexterm><programlisting>#define     CAIRO_VERSION_ENCODE(major, minor, micro)</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>major</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>minor</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>micro</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-version" role="function"/>cairo_version ()</title>
<indexterm><primary>cairo_version</primary></indexterm><programlisting><link linkend="int">int</link>         cairo_version                   (void);</programlisting>
<para>
Returns the version of the cairo library encoded in a single
integer as per CAIRO_VERSION_ENCODE. The encoding ensures that
later versions compare greater than earlier versions.
</para>
<para>
A run-time comparison to check that cairo's version is greater than
or equal to version X.Y.Z could be performed as follows:
</para>
<para>
<informalexample><programlisting>
if (<link linkend="cairo-version"><function>cairo_version()</function></link> &gt;= CAIRO_VERSION_ENCODE(X,Y,Z)) {...}
</programlisting></informalexample>
</para>
<para>
See also <link linkend="cairo-version-string"><function>cairo_version_string()</function></link> as well as the compile-time
equivalents <link linkend="CAIRO-VERSION:CAPS"><literal>CAIRO_VERSION</literal></link> and <link linkend="CAIRO-VERSION-STRING:CAPS"><literal>CAIRO_VERSION_STRING</literal></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the encoded version.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-version-string" role="function"/>cairo_version_string ()</title>
<indexterm><primary>cairo_version_string</primary></indexterm><programlisting>const <link linkend="char">char</link>* cairo_version_string            (void);</programlisting>
<para>
Returns the version of the cairo library as a human-readable string
of the form "X.Y.Z".
</para>
<para>
See also <link linkend="cairo-version"><function>cairo_version()</function></link> as well as the compile-time equivalents
<link linkend="CAIRO-VERSION-STRING:CAPS"><literal>CAIRO_VERSION_STRING</literal></link> and <link linkend="CAIRO-VERSION:CAPS"><literal>CAIRO_VERSION</literal></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a string containing the version.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>