[cairo-commit] cairo/doc/public/tmpl cairo-version.sgml,1.2,1.3
commit at pdx.freedesktop.org
Sat Sep 3 06:42:36 EST 2005
Committed by: cworth
Update of /cvs/cairo/cairo/doc/public/tmpl
In directory gabe:/tmp/cvs-serv29958/doc/public/tmpl
2005-09-02 Carl Worth <cworth at cworth.org>
* doc/public/tmpl/cairo-version.sgml: Add description of cairo's
RCS file: /cvs/cairo/cairo/doc/public/tmpl/cairo-version.sgml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- cairo-version.sgml 25 Aug 2005 02:20:08 -0000 1.2
+++ cairo-version.sgml 2 Sep 2005 20:42:34 -0000 1.3
@@ -2,13 +2,113 @@
<!-- ##### SECTION Short_Description ##### -->
-Compile and run time version checks
+Compile-time and run-time version checks.
<!-- ##### SECTION Long_Description ##### -->
+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).
+ _____ 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
+| | /
+Here are a few examples of versions that one might see.
+1.0.0 - A major release
+1.0.2 - A subsequent maintenance release
+1.2.0 - Another major release
+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)
+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.
+<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 a
+macro (CAIRO_VERSION_ENCODE) to perform the encoding.
+%CAIRO_VERSION Encoded, suitable for comparison
+cairo_version() Encoded, suitable for comparison
+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:
+##if %CAIRO_VERSION >= %CAIRO_VERSION_ENCODE(1, 0, 0)
+printf ("Compiling with suitable cairo version: %%s\n", CAIRO_VERSION_STRING);
+if (cairo_version() >= %CAIRO_VERSION_ENCODE(1, 0, 0))
+ printf ("Running with suitable cairo version: %%s\n", cairo_version_string ());
<!-- ##### SECTION See_Also ##### -->
More information about the cairo-commit