LCOV - code coverage report
Current view: directory - gfx/cairo/cairo/src - cairo-version.c (source / functions) Found Hit Coverage
Test: app.info Lines: 4 0 0.0 %
Date: 2012-06-02 Functions: 3 0 0.0 %

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

Generated by: LCOV version 1.7