Version Information: Cairo: A Vector Graphics Library

+ + +

Version Information

Version Information — Compile-time and run-time version checks.

Functions

++++ + + + + + + + + + + + + + + + + + + +

#define	+CAIRO_VERSION_ENCODE() +
#define	+CAIRO_VERSION_STRINGIZE() +
+int +	+cairo_version () +
const char * +	+cairo_version_string () +

Types and Values

++++ + + + + + + + + + + + + + + + + + + + + + + +

#define	CAIRO_VERSION
#define	CAIRO_VERSION_MAJOR
#define	CAIRO_VERSION_MINOR
#define	CAIRO_VERSION_MICRO
#define	CAIRO_VERSION_STRING

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 git 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 (git)
+| /  _ Micro. Even/Odd = Tar-file/git
+| | /
+1.0.0
+

Here are a few examples of versions that one might see.

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

Compatibility

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

Examining the version

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

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

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

+ + + + + + + +

1
+2
+3
+4
+5
+6

##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 ());

+ +

Functions

CAIRO_VERSION_ENCODE()

#define             CAIRO_VERSION_ENCODE(major, minor, micro)

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.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

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.

Since: 1.0

CAIRO_VERSION_STRINGIZE()

#define             CAIRO_VERSION_STRINGIZE(major, minor, micro)

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.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

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

cairo_version ()

int
+cairo_version (void);

Returns the version of the cairo library encoded in a single +integer as per CAIRO_VERSION_ENCODE. The encoding ensures that +later versions compare greater than earlier versions.

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:

+ + + + + + + +

1	if (cairo_version() >= CAIRO_VERSION_ENCODE(X,Y,Z)) {...}

+ +

See also cairo_version_string() as well as the compile-time +equivalents CAIRO_VERSION and CAIRO_VERSION_STRING.

Returns

the encoded version.

Since: 1.0

cairo_version_string ()

const char *
+cairo_version_string (void);

Returns the version of the cairo library as a human-readable string +of the form "X.Y.Z".

See also cairo_version() as well as the compile-time equivalents +CAIRO_VERSION_STRING and CAIRO_VERSION.

Returns

a string containing the version.

Since: 1.0

Types and Values

CAIRO_VERSION

#define             CAIRO_VERSION

The version of cairo available at compile-time, encoded using +CAIRO_VERSION_ENCODE().

Since: 1.0

CAIRO_VERSION_MAJOR

#define CAIRO_VERSION_MAJOR USE_cairo_version_OR_cairo_version_string_INSTEAD
+

The major component of the version of cairo available at compile-time.

Since: 1.0

CAIRO_VERSION_MINOR

#define CAIRO_VERSION_MINOR USE_cairo_version_OR_cairo_version_string_INSTEAD
+

The minor component of the version of cairo available at compile-time.

Since: 1.0

CAIRO_VERSION_MICRO

#define CAIRO_VERSION_MICRO USE_cairo_version_OR_cairo_version_string_INSTEAD
+

The micro component of the version of cairo available at compile-time.

Since: 1.0

CAIRO_VERSION_STRING

#define             CAIRO_VERSION_STRING

A human-readable string literal containing the version of cairo available +at compile-time, in the form of "X.Y.Z".

Since: 1.8