cairo-version.sgml   [plain text]

<!-- ##### SECTION Title ##### -->
Version Information

<!-- ##### SECTION Short_Description ##### -->
Compile-time and run-time version checks.

<!-- ##### SECTION Long_Description ##### -->
<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 CAIRO_VERSION_ENCODE() 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:

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

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### MACRO CAIRO_VERSION ##### -->
<para>
The version of cairo available at compile-time, encoded using
CAIRO_VERSION_ENCODE().
</para>



<!-- ##### MACRO CAIRO_VERSION_MAJOR ##### -->
<para>
The major component of the version of cairo available at compile-time.
</para>



<!-- ##### MACRO CAIRO_VERSION_MINOR ##### -->
<para>
The minor component of the version of cairo available at compile-time.
</para>



<!-- ##### MACRO CAIRO_VERSION_MICRO ##### -->
<para>
The micro component of the version of cairo available at compile-time.
</para>



<!-- ##### MACRO CAIRO_VERSION_STRING ##### -->
<para>
A human-readable string literal containing the version of cairo available
at compile-time, in the form of "X.Y.Z".
</para>



<!-- ##### MACRO CAIRO_VERSION_ENCODE ##### -->
<para>
This macro encodes the given cairo version into an integer.  The numbers
returned by %CAIRO_VERSION and cairo_version() 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>

@major: the major component of the version number
@minor: the minor component of the version number
@micro: the micro component of the version number
@Returns: the encoded version.


<!-- ##### MACRO CAIRO_VERSION_STRINGIZE ##### -->
<para>
This macro encodes the given cairo version into an string.  The numbers
returned by %CAIRO_VERSION_STRING and cairo_version_string() are encoded using this macro.
The parameters to this macro must expand to numerical literals.
</para>

@major: the major component of the version number
@minor: the minor component of the version number
@micro: the micro component of the version number
@Returns: a string literal containing the version.
@Since: 1.8


<!-- ##### FUNCTION cairo_version ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION cairo_version_string ##### -->
<para>

</para>

@Returns: