<?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" id="cairo-Version-Information.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> </refnamediv> <refsynopsisdiv id="cairo-Version-Information.synopsis" 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) #define <link linkend="CAIRO-VERSION-STRINGIZE:CAPS">CAIRO_VERSION_STRINGIZE</link> (major, minor, micro) <link linkend="int"><returnvalue>int</returnvalue></link> <link linkend="cairo-version">cairo_version</link> (<parameter><type>void</type></parameter>); const <link linkend="char"><returnvalue>char</returnvalue></link> * <link linkend="cairo-version-string">cairo_version_string</link> (<parameter><type>void</type></parameter>); </synopsis> </refsynopsisdiv> <refsect1 id="cairo-Version-Information.description" 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 git 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 (git) | / _ Micro. Even/Odd = Tar-file/git | | / 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 git) -------------------------------------- 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 the macro <link linkend="CAIRO-VERSION-ENCODE:CAPS"><function>CAIRO_VERSION_ENCODE()</function></link> to perform the encoding. </para> <para> <informalexample><programlisting> Compile-time ------------ CAIRO_VERSION_STRING Human-readable CAIRO_VERSION Encoded, suitable for comparison Run-time -------- cairo_version_string() Human-readable cairo_version() 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: </para> <para> <informalexample><programlisting> ##if CAIRO_VERSION >= CAIRO_VERSION_ENCODE(1, 0, 0) printf ("Compiling with suitable cairo version: %s\n", %CAIRO_VERSION_STRING); ##endif if (cairo_version() >= CAIRO_VERSION_ENCODE(1, 0, 0)) printf ("Running with suitable cairo version: %s\n", cairo_version_string ()); </programlisting></informalexample> </para> </refsect2> </refsect1> <refsect1 id="cairo-Version-Information.details" role="details"> <title role="details.title">Details</title> <refsect2 id="CAIRO-VERSION:CAPS" role="macro"> <title>CAIRO_VERSION</title> <indexterm zone="CAIRO-VERSION:CAPS"><primary sortas="VERSION">CAIRO_VERSION</primary></indexterm> <programlisting>#define CAIRO_VERSION</programlisting> <para> The version of cairo available at compile-time, encoded using <link linkend="CAIRO-VERSION-ENCODE:CAPS"><function>CAIRO_VERSION_ENCODE()</function></link>. </para></refsect2> <refsect2 id="CAIRO-VERSION-MAJOR:CAPS" role="macro"> <title>CAIRO_VERSION_MAJOR</title> <indexterm zone="CAIRO-VERSION-MAJOR:CAPS"><primary sortas="VERSION_MAJOR">CAIRO_VERSION_MAJOR</primary></indexterm> <programlisting>#define CAIRO_VERSION_MAJOR USE_cairo_version_OR_cairo_version_string_INSTEAD </programlisting> <para> The major component of the version of cairo available at compile-time. </para></refsect2> <refsect2 id="CAIRO-VERSION-MINOR:CAPS" role="macro"> <title>CAIRO_VERSION_MINOR</title> <indexterm zone="CAIRO-VERSION-MINOR:CAPS"><primary sortas="VERSION_MINOR">CAIRO_VERSION_MINOR</primary></indexterm> <programlisting>#define CAIRO_VERSION_MINOR USE_cairo_version_OR_cairo_version_string_INSTEAD </programlisting> <para> The minor component of the version of cairo available at compile-time. </para></refsect2> <refsect2 id="CAIRO-VERSION-MICRO:CAPS" role="macro"> <title>CAIRO_VERSION_MICRO</title> <indexterm zone="CAIRO-VERSION-MICRO:CAPS"><primary sortas="VERSION_MICRO">CAIRO_VERSION_MICRO</primary></indexterm> <programlisting>#define CAIRO_VERSION_MICRO USE_cairo_version_OR_cairo_version_string_INSTEAD </programlisting> <para> The micro component of the version of cairo available at compile-time. </para></refsect2> <refsect2 id="CAIRO-VERSION-STRING:CAPS" role="macro"> <title>CAIRO_VERSION_STRING</title> <indexterm zone="CAIRO-VERSION-STRING:CAPS"><primary sortas="VERSION_STRING">CAIRO_VERSION_STRING</primary></indexterm> <programlisting>#define CAIRO_VERSION_STRING</programlisting> <para> A human-readable string literal containing the version of cairo available at compile-time, in the form of "X.Y.Z". </para></refsect2> <refsect2 id="CAIRO-VERSION-ENCODE:CAPS" role="macro"> <title>CAIRO_VERSION_ENCODE()</title> <indexterm zone="CAIRO-VERSION-ENCODE:CAPS"><primary sortas="VERSION_ENCODE">CAIRO_VERSION_ENCODE</primary></indexterm> <programlisting>#define CAIRO_VERSION_ENCODE(major, minor, micro)</programlisting> <para> This macro encodes the given cairo version into an integer. The numbers returned by <link linkend="CAIRO-VERSION:CAPS"><literal>CAIRO_VERSION</literal></link> and <link linkend="cairo-version"><function>cairo_version()</function></link> are encoded using this macro. Two encoded version numbers can be compared as integers. The encoding ensures that later versions compare greater than earlier versions. </para> <para> <parameter>Returns</parameter>: the encoded version. </para><variablelist role="params"> <varlistentry><term><parameter>major</parameter> :</term> <listitem><simpara>the major component of the version number </simpara></listitem></varlistentry> <varlistentry><term><parameter>minor</parameter> :</term> <listitem><simpara>the minor component of the version number </simpara></listitem></varlistentry> <varlistentry><term><parameter>micro</parameter> :</term> <listitem><simpara>the micro component of the version number </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="CAIRO-VERSION-STRINGIZE:CAPS" role="macro"> <title>CAIRO_VERSION_STRINGIZE()</title> <indexterm zone="CAIRO-VERSION-STRINGIZE:CAPS"><primary sortas="VERSION_STRINGIZE">CAIRO_VERSION_STRINGIZE</primary></indexterm> <programlisting>#define CAIRO_VERSION_STRINGIZE(major, minor, micro)</programlisting> <para> This macro encodes the given cairo version into an string. The numbers returned by <link linkend="CAIRO-VERSION-STRING:CAPS"><literal>CAIRO_VERSION_STRING</literal></link> and <link linkend="cairo-version-string"><function>cairo_version_string()</function></link> are encoded using this macro. The parameters to this macro must expand to numerical literals. </para> <para> <parameter>Returns</parameter>: a string literal containing the version. </para> <para> <parameter>Since</parameter>: 1.8 </para><variablelist role="params"> <varlistentry><term><parameter>major</parameter> :</term> <listitem><simpara>the major component of the version number </simpara></listitem></varlistentry> <varlistentry><term><parameter>minor</parameter> :</term> <listitem><simpara>the minor component of the version number </simpara></listitem></varlistentry> <varlistentry><term><parameter>micro</parameter> :</term> <listitem><simpara>the micro component of the version number </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="cairo-version" role="function"> <title>cairo_version ()</title> <indexterm zone="cairo-version"><primary sortas="version">cairo_version</primary></indexterm> <programlisting><link linkend="int"><returnvalue>int</returnvalue></link> cairo_version (<parameter><type>void</type></parameter>);</programlisting> <para> Returns the version of the cairo library encoded in a single integer as per <link linkend="CAIRO-VERSION-ENCODE:CAPS"><literal>CAIRO_VERSION_ENCODE</literal></link>. 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 (cairo_version() >= 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><variablelist role="params"> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the encoded version. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="cairo-version-string" role="function"> <title>cairo_version_string ()</title> <indexterm zone="cairo-version-string"><primary sortas="version_string">cairo_version_string</primary></indexterm> <programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> * cairo_version_string (<parameter><type>void</type></parameter>);</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><variablelist role="params"> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a string containing the version. </simpara></listitem></varlistentry> </variablelist></refsect2> </refsect1> </refentry>