mirror of
https://gitlab.freedesktop.org/cairo/cairo.git
synced 2026-01-03 12:50:20 +01:00
185 lines
4.9 KiB
Text
185 lines
4.9 KiB
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 a
|
|
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
|
|
|
|
|
|
<!-- ##### FUNCTION cairo_version ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION cairo_version_string ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|