Line data Source code
1 : /* -*- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -*- */
2 : /* cairo - a vector graphics library with display and print output
3 : *
4 : * Copyright © 2002 University of Southern California
5 : * Copyright © 2005 Red Hat, Inc.
6 : *
7 : * This library is free software; you can redistribute it and/or
8 : * modify it either under the terms of the GNU Lesser General Public
9 : * License version 2.1 as published by the Free Software Foundation
10 : * (the "LGPL") or, at your option, under the terms of the Mozilla
11 : * Public License Version 1.1 (the "MPL"). If you do not alter this
12 : * notice, a recipient may use your version of this file under either
13 : * the MPL or the LGPL.
14 : *
15 : * You should have received a copy of the LGPL along with this library
16 : * in the file COPYING-LGPL-2.1; if not, write to the Free Software
17 : * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
18 : * You should have received a copy of the MPL along with this library
19 : * in the file COPYING-MPL-1.1
20 : *
21 : * The contents of this file are subject to the Mozilla Public License
22 : * Version 1.1 (the "License"); you may not use this file except in
23 : * compliance with the License. You may obtain a copy of the License at
24 : * http://www.mozilla.org/MPL/
25 : *
26 : * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
27 : * OF ANY KIND, either express or implied. See the LGPL or the MPL for
28 : * the specific language governing rights and limitations.
29 : *
30 : * The Original Code is the cairo graphics library.
31 : *
32 : * The Initial Developer of the Original Code is University of Southern
33 : * California.
34 : *
35 : * Contributor(s):
36 : * Carl D. Worth <cworth@cworth.org>
37 : */
38 :
39 : #define CAIRO_VERSION_H 1
40 :
41 : #include "cairoint.h"
42 :
43 : /* get the "real" version info instead of dummy cairo-version.h */
44 : #undef CAIRO_VERSION_H
45 : #include "cairo-features.h"
46 :
47 : /**
48 : * SECTION:cairo-version
49 : * @Title: Version Information
50 : * @Short_Description: Compile-time and run-time version checks.
51 : *
52 : * Cairo has a three-part version number scheme. In this scheme, we use
53 : * even vs. odd numbers to distinguish fixed points in the software
54 : * vs. in-progress development, (such as from git instead of a tar file,
55 : * or as a "snapshot" tar file as opposed to a "release" tar file).
56 : *
57 : * <informalexample><programlisting>
58 : * _____ Major. Always 1, until we invent a new scheme.
59 : * / ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (git)
60 : * | / _ Micro. Even/Odd = Tar-file/git
61 : * | | /
62 : * 1.0.0
63 : * </programlisting></informalexample>
64 : *
65 : * Here are a few examples of versions that one might see.
66 : * <informalexample><programlisting>
67 : * Releases
68 : * --------
69 : * 1.0.0 - A major release
70 : * 1.0.2 - A subsequent maintenance release
71 : * 1.2.0 - Another major release
72 : *
73 : * Snapshots
74 : * ---------
75 : * 1.1.2 - A snapshot (working toward the 1.2.0 release)
76 : *
77 : * In-progress development (eg. from git)
78 : * --------------------------------------
79 : * 1.0.1 - Development on a maintenance branch (toward 1.0.2 release)
80 : * 1.1.1 - Development on head (toward 1.1.2 snapshot and 1.2.0 release)
81 : * </programlisting></informalexample>
82 : * </para>
83 : * <refsect2>
84 : * <title>Compatibility</title>
85 : * <para>
86 : * The API/ABI compatibility guarantees for various versions are as
87 : * follows. First, let's assume some cairo-using application code that is
88 : * successfully using the API/ABI "from" one version of cairo. Then let's
89 : * ask the question whether this same code can be moved "to" the API/ABI
90 : * of another version of cairo.
91 : *
92 : * Moving from a release to any later version (release, snapshot,
93 : * development) is always guaranteed to provide compatibility.
94 : *
95 : * Moving from a snapshot to any later version is not guaranteed to
96 : * provide compatibility, since snapshots may introduce new API that ends
97 : * up being removed before the next release.
98 : *
99 : * Moving from an in-development version (odd micro component) to any
100 : * later version is not guaranteed to provide compatibility. In fact,
101 : * there's not even a guarantee that the code will even continue to work
102 : * with the same in-development version number. This is because these
103 : * numbers don't correspond to any fixed state of the software, but
104 : * rather the many states between snapshots and releases.
105 : * </para>
106 : * </refsect2>
107 : * <refsect2>
108 : * <title>Examining the version</title>
109 : * <para>
110 : * Cairo provides the ability to examine the version at either
111 : * compile-time or run-time and in both a human-readable form as well as
112 : * an encoded form suitable for direct comparison. Cairo also provides the
113 : * macro CAIRO_VERSION_ENCODE() to perform the encoding.
114 : *
115 : * <informalexample><programlisting>
116 : * Compile-time
117 : * ------------
118 : * CAIRO_VERSION_STRING Human-readable
119 : * CAIRO_VERSION Encoded, suitable for comparison
120 : *
121 : * Run-time
122 : * --------
123 : * cairo_version_string() Human-readable
124 : * cairo_version() Encoded, suitable for comparison
125 : * </programlisting></informalexample>
126 : *
127 : * For example, checking that the cairo version is greater than or equal
128 : * to 1.0.0 could be achieved at compile-time or run-time as follows:
129 : *
130 : * <informalexample><programlisting>
131 : * ##if CAIRO_VERSION >= CAIRO_VERSION_ENCODE(1, 0, 0)
132 : * printf ("Compiling with suitable cairo version: %s\n", %CAIRO_VERSION_STRING);
133 : * ##endif
134 : *
135 : * if (cairo_version() >= CAIRO_VERSION_ENCODE(1, 0, 0))
136 : * printf ("Running with suitable cairo version: %s\n", cairo_version_string ());
137 : * </programlisting></informalexample>
138 : * </para>
139 : * </refsect2>
140 : */
141 :
142 : /**
143 : * CAIRO_VERSION:
144 : *
145 : * The version of cairo available at compile-time, encoded using
146 : * CAIRO_VERSION_ENCODE().
147 : */
148 :
149 : /**
150 : * CAIRO_VERSION_MAJOR:
151 : *
152 : * The major component of the version of cairo available at compile-time.
153 : */
154 :
155 : /**
156 : * CAIRO_VERSION_MINOR:
157 : *
158 : * The minor component of the version of cairo available at compile-time.
159 : */
160 :
161 : /**
162 : * CAIRO_VERSION_MICRO:
163 : *
164 : * The micro component of the version of cairo available at compile-time.
165 : */
166 :
167 : /**
168 : * CAIRO_VERSION_STRING:
169 : *
170 : * A human-readable string literal containing the version of cairo available
171 : * at compile-time, in the form of "X.Y.Z".
172 : */
173 :
174 : /**
175 : * CAIRO_VERSION_ENCODE:
176 : * @major: the major component of the version number
177 : * @minor: the minor component of the version number
178 : * @micro: the micro component of the version number
179 : *
180 : * This macro encodes the given cairo version into an integer. The numbers
181 : * returned by %CAIRO_VERSION and cairo_version() are encoded using this macro.
182 : * Two encoded version numbers can be compared as integers. The encoding ensures
183 : * that later versions compare greater than earlier versions.
184 : *
185 : * @Returns: the encoded version.
186 : */
187 :
188 : /**
189 : * CAIRO_VERSION_STRINGIZE:
190 : * @major: the major component of the version number
191 : * @minor: the minor component of the version number
192 : * @micro: the micro component of the version number
193 : *
194 : * This macro encodes the given cairo version into an string. The numbers
195 : * returned by %CAIRO_VERSION_STRING and cairo_version_string() are encoded using this macro.
196 : * The parameters to this macro must expand to numerical literals.
197 : *
198 : * @Returns: a string literal containing the version.
199 : *
200 : * @Since: 1.8
201 : */
202 :
203 : /**
204 : * cairo_version:
205 : *
206 : * Returns the version of the cairo library encoded in a single
207 : * integer as per %CAIRO_VERSION_ENCODE. The encoding ensures that
208 : * later versions compare greater than earlier versions.
209 : *
210 : * A run-time comparison to check that cairo's version is greater than
211 : * or equal to version X.Y.Z could be performed as follows:
212 : *
213 : * <informalexample><programlisting>
214 : * if (cairo_version() >= CAIRO_VERSION_ENCODE(X,Y,Z)) {...}
215 : * </programlisting></informalexample>
216 : *
217 : * See also cairo_version_string() as well as the compile-time
218 : * equivalents %CAIRO_VERSION and %CAIRO_VERSION_STRING.
219 : *
220 : * Return value: the encoded version.
221 : **/
222 : int
223 0 : cairo_version (void)
224 : {
225 0 : return CAIRO_VERSION;
226 : }
227 :
228 : /**
229 : * cairo_version_string:
230 : *
231 : * Returns the version of the cairo library as a human-readable string
232 : * of the form "X.Y.Z".
233 : *
234 : * See also cairo_version() as well as the compile-time equivalents
235 : * %CAIRO_VERSION_STRING and %CAIRO_VERSION.
236 : *
237 : * Return value: a string containing the version.
238 : **/
239 : const char*
240 0 : cairo_version_string (void)
241 : {
242 0 : return CAIRO_VERSION_STRING;
243 : }
244 : slim_hidden_def (cairo_version_string);
|
