swfdec/swfdec_version.c

   1 /* Swfdec
   2  * Copyright (C) 2008 Benjamin Otte <otte@gnome.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17  * Boston, MA  02110-1301  USA
  18  */
  19
  20 #ifdef HAVE_CONFIG_H
  21 #include "config.h"
  22 #endif
  23
  24 #include "swfdec_version.h"
  25
  26
  27 /**
  28  * SECTION:Version
  29  * @title: Version Information
  30  * @short_description: Compile-time and run-time version checks
  31  *
  32  * Swfdec has a three-part version number scheme. In this scheme, we use
  33  * even vs. odd numbers to distinguish fixed points in the software vs.
  34  * in-progress development, (such as from git instead of a tar file, or as a
  35  * "snapshot" tar file as opposed to a "release" tar file).
  36  *
  37  * <informalexample><programlisting>
  38  *  _____ Major. Always 1, until we invent a new scheme.
  39  * /  ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (git)
  40  * | /  _ Micro. Even/Odd = Tar-file/git
  41  * | | /
  42  * 1.0.0
  43  * </programlisting></informalexample>
  44  *
  45  * Here are a few examples of versions that one might see.
  46  * <informalexample><programlisting>
  47  * Releases
  48  * --------
  49  *  1.0.0 - A major release
  50  *  1.0.2 - A subsequent maintenance release
  51  *  1.2.0 - Another major release
  52  *
  53  * Snapshots
  54  * ---------
  55  *  1.1.2 - A snapshot (working toward the 1.2.0 release)
  56  *
  57  * In-progress development (eg. from git)
  58  * --------------------------------------
  59  *  1.0.1 - Development on a maintenance branch (toward 1.0.2 release)
  60  *  1.1.1 - Development on head (toward 1.1.2 snapshot and 1.2.0 release)
  61  *  </programlisting></informalexample>
  62  *
  63  * <refsect2><title>Examining the version</title><para>
  64  * Swfdec provides the ability to examine the version at either
  65  * compile-time or run-time and in both a human-readable form as well as an
  66  * encoded form suitable for direct comparison. Swfdec also provides the macro
  67  * SWFDEC_VERSION_ENCODE() to perform the encoding.
  68  *
  69  * <informalexample><programlisting>
  70  * Compile-time
  71  * ------------
  72  *  SWFDEC_VERSION_STRING       Human-readable
  73  *  SWFDEC_VERSION              Encoded, suitable for comparison
  74  *
  75  * Run-time
  76  * --------
  77  *  swfdec_version_string()     Human-readable
  78  *  swfdec_version()            Encoded, suitable for comparison
  79  * </programlisting></informalexample>
  80  *
  81  * For example, checking that the Swfdec version is greater than or equal
  82  * to 1.0.0 could be achieved at compile-time or run-time as follows:
  83  * <informalexample><programlisting>
  84  * #if CAIRO_VERSION >= CAIRO_VERSION_ENCODE(1, 0, 0)
  85  * printf ("Compiling with suitable cairo version: %s\n", %CAIRO_VERSION_STRING);
  86  * #endif
  87  *
  88  * if (cairo_version() >= CAIRO_VERSION_ENCODE(1, 0, 0))
  89  *   printf ("Running with suitable cairo version: %s\n", cairo_version_string ());
  90  * </programlisting></informalexample>
  91  * </para></refsect2>
  92  */
  93 /**
  94  * SWFDEC_VERSION:
  95  *
  96  * The version of Swfdec available at compile-time, encoded using
  97  * SWFDEC_VERSION_ENCODE().
  98  */
  99 /**
 100  * SWFDEC_VERSION_MAJOR:
 101  *
 102  * The major component of the version of Swfdec available at compile-time.
 103  */
 104 /**
 105  * SWFDEC_VERSION_MINOR:
 106  *
 107  * The minor component of the version of Swfdec available at compile-time.
 108  */
 109 /**
 110  * SWFDEC_VERSION_MICRO:
 111  *
 112  * The micro component of the version of Swfdec available at compile-time.
 113  */
 114 /**
 115  * SWFDEC_VERSION_STRING:
 116  *
 117  * A human-readable string literal containing the version of Swfdec available
 118  * at compile-time, in the form of "X.Y.Z".
 119  */
 120 /**
 121  * SWFDEC_VERSION_ENCODE:
 122  * @major: the major component of the version number
 123  * @minor: the minor component of the version number
 124  * @micro: the micro component of the version number
 125  *
 126  * This macro encodes the given Swfdec version into an integer. The numbers
 127  * returned by @SWFDEC_VERSION and swfdec_version() are encoded using this
 128  * macro. Two encoded version numbers can be compared as integers. The
 129  * encoding ensures that later versions compare greater than earlier versions.
 130  */
 131
 132 #define SWFDEC_VERSION SWFDEC_VERSION_ENCODE (SWFDEC_VERSION_MAJOR, SWFDEC_VERSION_MINOR, SWFDEC_VERSION_MICRO)
 133
 134 /**
 135  * swfdec_version:
 136  *
 137  * Returns the version of the Swfdec library encoded in a single
 138  * integer as per %SWFDEC_VERSION_ENCODE. The encoding ensures that
 139  * later versions compare greater than earlier versions.
 140  *
 141  * A run-time comparison to check that Swfdec's version is greater than
 142  * or equal to version X.Y.Z could be performed as follows:
 143  *
 144  * <informalexample><programlisting>
 145  * if (swfdec_version() >= CAIRO_VERSION_ENCODE(X,Y,Z)) {...}
 146  * </programlisting></informalexample>
 147  *
 148  * See also swfdec_version_string() as well as the compile-time
 149  * equivalents %SWFDEC_VERSION and %SWFDEC_VERSION_STRING.
 150  *
 151  * Return value: the encoded version.
 152  **/
 153 guint
 154 swfdec_version (void)
 155 {
 156   return SWFDEC_VERSION;
 157 }
 158
 159 /**
 160  * swfdec_version_string:
 161  *
 162  * Returns the version of the Swfdec library as a human-readable string
 163  * of the form "X.Y.Z".
 164  *
 165  * See also swfdec_version() as well as the compile-time equivalents
 166  * %SWFDEC_VERSION_STRING and %SWFDEC_VERSION.
 167  *
 168  * Return value: a string containing the version.
 169  **/
 170 const char *
 171 swfdec_version_string (void)
 172 {
 173   return SWFDEC_VERSION_STRING;
 174 }