source/libs/cairo/cairo-src/src/cairo-version.c

   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-version.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><screen>
  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  * </screen></informalexample>
  64  *
  65  * Here are a few examples of versions that one might see.
  66  * <informalexample><screen>
  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  * &nbsp;
  73  * Snapshots
  74  * ---------
  75  * 1.1.2 - A snapshot (working toward the 1.2.0 release)
  76  * &nbsp;
  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  * </screen></informalexample>
  82  *
  83  * <refsect2>
  84  * <title>Compatibility</title>
  85  *
  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  *
 106  * </refsect2>
 107  * <refsect2>
 108  * <title>Examining the version</title>
 109  *
 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><screen>
 116  * Compile-time
 117  * ------------
 118  * CAIRO_VERSION_STRING    Human-readable
 119  * CAIRO_VERSION           Encoded, suitable for comparison
 120  * &nbsp;
 121  * Run-time
 122  * --------
 123  * cairo_version_string()  Human-readable
 124  * cairo_version()         Encoded, suitable for comparison
 125  * </screen></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  *
 139  * </refsect2>
 140  *
 141  **/
 142
 143 /**
 144  * CAIRO_VERSION:
 145  *
 146  * The version of cairo available at compile-time, encoded using
 147  * CAIRO_VERSION_ENCODE().
 148  *
 149  * Since: 1.0
 150  **/
 151
 152 /**
 153  * CAIRO_VERSION_MAJOR:
 154  *
 155  * The major component of the version of cairo available at compile-time.
 156  *
 157  * Since: 1.0
 158  **/
 159
 160 /**
 161  * CAIRO_VERSION_MINOR:
 162  *
 163  * The minor component of the version of cairo available at compile-time.
 164  *
 165  * Since: 1.0
 166  **/
 167
 168 /**
 169  * CAIRO_VERSION_MICRO:
 170  *
 171  * The micro component of the version of cairo available at compile-time.
 172  *
 173  * Since: 1.0
 174  **/
 175
 176 /**
 177  * CAIRO_VERSION_STRING:
 178  *
 179  * A human-readable string literal containing the version of cairo available
 180  * at compile-time, in the form of "X.Y.Z".
 181  *
 182  * Since: 1.8
 183  **/
 184
 185 /**
 186  * CAIRO_VERSION_ENCODE:
 187  * @major: the major component of the version number
 188  * @minor: the minor component of the version number
 189  * @micro: the micro component of the version number
 190  *
 191  * This macro encodes the given cairo version into an integer.  The numbers
 192  * returned by %CAIRO_VERSION and cairo_version() are encoded using this macro.
 193  * Two encoded version numbers can be compared as integers.  The encoding ensures
 194  * that later versions compare greater than earlier versions.
 195  *
 196  * Returns: the encoded version.
 197  *
 198  * Since: 1.0
 199  **/
 200
 201 /**
 202  * CAIRO_VERSION_STRINGIZE:
 203  * @major: the major component of the version number
 204  * @minor: the minor component of the version number
 205  * @micro: the micro component of the version number
 206  *
 207  * This macro encodes the given cairo version into an string.  The numbers
 208  * returned by %CAIRO_VERSION_STRING and cairo_version_string() are encoded using this macro.
 209  * The parameters to this macro must expand to numerical literals.
 210  *
 211  * Returns: a string literal containing the version.
 212  *
 213  * Since: 1.8
 214  **/
 215
 216 /**
 217  * cairo_version:
 218  *
 219  * Returns the version of the cairo library encoded in a single
 220  * integer as per %CAIRO_VERSION_ENCODE. The encoding ensures that
 221  * later versions compare greater than earlier versions.
 222  *
 223  * A run-time comparison to check that cairo's version is greater than
 224  * or equal to version X.Y.Z could be performed as follows:
 225  *
 226  * <informalexample><programlisting>
 227  * if (cairo_version() >= CAIRO_VERSION_ENCODE(X,Y,Z)) {...}
 228  * </programlisting></informalexample>
 229  *
 230  * See also cairo_version_string() as well as the compile-time
 231  * equivalents %CAIRO_VERSION and %CAIRO_VERSION_STRING.
 232  *
 233  * Return value: the encoded version.
 234  *
 235  * Since: 1.0
 236  **/
 237 int
 238 cairo_version (void)
 239 {
 240     return CAIRO_VERSION;
 241 }
 242
 243 /**
 244  * cairo_version_string:
 245  *
 246  * Returns the version of the cairo library as a human-readable string
 247  * of the form "X.Y.Z".
 248  *
 249  * See also cairo_version() as well as the compile-time equivalents
 250  * %CAIRO_VERSION_STRING and %CAIRO_VERSION.
 251  *
 252  * Return value: a string containing the version.
 253  *
 254  * Since: 1.0
 255  **/
 256 const char*
 257 cairo_version_string (void)
 258 {
 259     return CAIRO_VERSION_STRING;
 260 }
 261 slim_hidden_def (cairo_version_string);