diff options
Diffstat (limited to 'libs/cairo-1.16.0/doc/public/xml/cairo-version.xml')
| -rw-r--r-- | libs/cairo-1.16.0/doc/public/xml/cairo-version.xml | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/libs/cairo-1.16.0/doc/public/xml/cairo-version.xml b/libs/cairo-1.16.0/doc/public/xml/cairo-version.xml new file mode 100644 index 0000000..7825ecd --- /dev/null +++ b/libs/cairo-1.16.0/doc/public/xml/cairo-version.xml @@ -0,0 +1,278 @@ +<?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> + +<refsect1 id="cairo-Version-Information.functions" role="functions_proto"> +<title role="functions_proto.title">Functions</title> +<informaltable pgwide="1" frame="none"> +<tgroup cols="2"> +<colspec colname="functions_return" colwidth="150px"/> +<colspec colname="functions_name"/> +<tbody> +<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-ENCODE:CAPS">CAIRO_VERSION_ENCODE</link><phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-STRINGIZE:CAPS">CAIRO_VERSION_STRINGIZE</link><phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="int"><returnvalue>int</returnvalue></link> +</entry><entry role="function_name"><link linkend="cairo-version">cairo_version</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link> * +</entry><entry role="function_name"><link linkend="cairo-version-string">cairo_version_string</link> <phrase role="c_punctuation">()</phrase></entry></row> + +</tbody> +</tgroup> +</informaltable> +</refsect1> +<refsect1 id="cairo-Version-Information.other" role="other_proto"> +<title role="other_proto.title">Types and Values</title> +<informaltable role="enum_members_table" pgwide="1" frame="none"> +<tgroup cols="2"> +<colspec colname="name" colwidth="150px"/> +<colspec colname="description"/> +<tbody> +<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION:CAPS">CAIRO_VERSION</link></entry></row> +<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-MAJOR:CAPS">CAIRO_VERSION_MAJOR</link></entry></row> +<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-MINOR:CAPS">CAIRO_VERSION_MINOR</link></entry></row> +<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-MICRO:CAPS">CAIRO_VERSION_MICRO</link></entry></row> +<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-VERSION-STRING:CAPS">CAIRO_VERSION_STRING</link></entry></row> + +</tbody> +</tgroup> +</informaltable> +</refsect1> + + +<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> +<informalexample><screen> + _____ 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 +</screen></informalexample> +<para>Here are a few examples of versions that one might see.</para> +<informalexample><screen> +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) +</screen></informalexample> +<refsect2> +<title>Compatibility</title> + +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. + +Moving from a release to any later version (release, snapshot, +development) is always guaranteed to provide compatibility. + +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. + +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. + +</refsect2> +<refsect2> +<title>Examining the version</title> + +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. + +<informalexample><screen> +Compile-time +------------ +<link linkend="CAIRO-VERSION-STRING:CAPS"><type>CAIRO_VERSION_STRING</type></link> Human-readable +<link linkend="CAIRO-VERSION:CAPS"><type>CAIRO_VERSION</type></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 +</screen></informalexample> + +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> +##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> + +</refsect2> + +</refsect1> +<refsect1 id="cairo-Version-Information.functions_details" role="details"> +<title role="details.title">Functions</title> +<refsect2 id="CAIRO-VERSION-ENCODE:CAPS" role="macro" condition="since:1.0"> +<title>CAIRO_VERSION_ENCODE()</title> +<indexterm zone="CAIRO-VERSION-ENCODE:CAPS" role="1.0"><primary sortas="VERSION_ENCODE">CAIRO_VERSION_ENCODE</primary></indexterm> +<programlisting language="C">#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> +<refsect3 id="CAIRO-VERSION-ENCODE.parameters" role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>major</para></entry> +<entry role="parameter_description"><para>the major component of the version number</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>minor</para></entry> +<entry role="parameter_description"><para>the minor component of the version number</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>micro</para></entry> +<entry role="parameter_description"><para>the micro component of the version number</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><refsect3 id="CAIRO-VERSION-ENCODE.returns" role="returns"> +<title>Returns</title> +<para> the encoded version.</para> +</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> +<refsect2 id="CAIRO-VERSION-STRINGIZE:CAPS" role="macro" condition="since:1.8"> +<title>CAIRO_VERSION_STRINGIZE()</title> +<indexterm zone="CAIRO-VERSION-STRINGIZE:CAPS" role="1.8"><primary sortas="VERSION_STRINGIZE">CAIRO_VERSION_STRINGIZE</primary></indexterm> +<programlisting language="C">#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> +<refsect3 id="CAIRO-VERSION-STRINGIZE.parameters" role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>major</para></entry> +<entry role="parameter_description"><para>the major component of the version number</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>minor</para></entry> +<entry role="parameter_description"><para>the minor component of the version number</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>micro</para></entry> +<entry role="parameter_description"><para>the micro component of the version number</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><refsect3 id="CAIRO-VERSION-STRINGIZE.returns" role="returns"> +<title>Returns</title> +<para> a string literal containing the version.</para> +</refsect3><para role="since">Since: <link linkend="api-index-1.8">1.8</link></para></refsect2> +<refsect2 id="cairo-version" role="function" condition="since:1.0"> +<title>cairo_version ()</title> +<indexterm zone="cairo-version" role="1.0"><primary sortas="version">cairo_version</primary></indexterm> +<programlisting language="C"><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> +<informalexample><programlisting> +if (cairo_version() >= CAIRO_VERSION_ENCODE(X,Y,Z)) {...} +</programlisting></informalexample> +<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> +<refsect3 id="cairo-version.returns" role="returns"> +<title>Returns</title> +<para> the encoded version.</para> +</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> +<refsect2 id="cairo-version-string" role="function" condition="since:1.0"> +<title>cairo_version_string ()</title> +<indexterm zone="cairo-version-string" role="1.0"><primary sortas="version_string">cairo_version_string</primary></indexterm> +<programlisting language="C">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> +<refsect3 id="cairo-version-string.returns" role="returns"> +<title>Returns</title> +<para> a string containing the version.</para> +</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> + +</refsect1> +<refsect1 id="cairo-Version-Information.other_details" role="details"> +<title role="details.title">Types and Values</title> +<refsect2 id="CAIRO-VERSION:CAPS" role="macro" condition="since:1.0"> +<title>CAIRO_VERSION</title> +<indexterm zone="CAIRO-VERSION:CAPS" role="1.0"><primary sortas="VERSION">CAIRO_VERSION</primary></indexterm> +<programlisting language="C">#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> +<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> +<refsect2 id="CAIRO-VERSION-MAJOR:CAPS" role="macro" condition="since:1.0"> +<title>CAIRO_VERSION_MAJOR</title> +<indexterm zone="CAIRO-VERSION-MAJOR:CAPS" role="1.0"><primary sortas="VERSION_MAJOR">CAIRO_VERSION_MAJOR</primary></indexterm> +<programlisting language="C">#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> +<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> +<refsect2 id="CAIRO-VERSION-MINOR:CAPS" role="macro" condition="since:1.0"> +<title>CAIRO_VERSION_MINOR</title> +<indexterm zone="CAIRO-VERSION-MINOR:CAPS" role="1.0"><primary sortas="VERSION_MINOR">CAIRO_VERSION_MINOR</primary></indexterm> +<programlisting language="C">#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> +<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> +<refsect2 id="CAIRO-VERSION-MICRO:CAPS" role="macro" condition="since:1.0"> +<title>CAIRO_VERSION_MICRO</title> +<indexterm zone="CAIRO-VERSION-MICRO:CAPS" role="1.0"><primary sortas="VERSION_MICRO">CAIRO_VERSION_MICRO</primary></indexterm> +<programlisting language="C">#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> +<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> +<refsect2 id="CAIRO-VERSION-STRING:CAPS" role="macro" condition="since:1.8"> +<title>CAIRO_VERSION_STRING</title> +<indexterm zone="CAIRO-VERSION-STRING:CAPS" role="1.8"><primary sortas="VERSION_STRING">CAIRO_VERSION_STRING</primary></indexterm> +<programlisting language="C">#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> +<para role="since">Since: <link linkend="api-index-1.8">1.8</link></para></refsect2> + +</refsect1> + +</refentry> |