contrib/subversion/subversion/include/svn_version.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_version.h
  24  * @brief Version information.
  25  */
  26
  27 #ifndef SVN_VERSION_H
  28 #define SVN_VERSION_H
  29
  30 /* Hack to prevent the resource compiler from including
  31    apr and other headers. */
  32 #ifndef SVN_WIN32_RESOURCE_COMPILATION
  33 #include <apr_general.h>
  34 #include <apr_tables.h>
  35
  36 #include "svn_types.h"
  37 #endif
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif /* __cplusplus */
  42
  43 \f
  44 /* Symbols that define the version number. */
  45
  46 /* Version numbers: <major>.<minor>.<micro>
  47  *
  48  * The version numbers in this file follow the rules established by:
  49  *
  50  *   http://apr.apache.org/versioning.html
  51  */
  52
  53 /** Major version number.
  54  *
  55  * Modify when incompatible changes are made to published interfaces.
  56  */
  57 #define SVN_VER_MAJOR      1
  58
  59 /** Minor version number.
  60  *
  61  * Modify when new functionality is added or new interfaces are
  62  * defined, but all changes are backward compatible.
  63  */
  64 #define SVN_VER_MINOR      9
  65
  66 /**
  67  * Patch number.
  68  *
  69  * Modify for every released patch.
  70  *
  71  * @since New in 1.1.
  72  */
  73 #define SVN_VER_PATCH      4
  74
  75
  76 /** @deprecated Provided for backward compatibility with the 1.0 API. */
  77 #define SVN_VER_MICRO      SVN_VER_PATCH
  78
  79 /** @deprecated Provided for backward compatibility with the 1.0 API. */
  80 #define SVN_VER_LIBRARY    SVN_VER_MAJOR
  81
  82
  83 /** Version tag: a string describing the version.
  84  *
  85  * This tag remains " (under development)" in the repository so that we can
  86  * always see from "svn --version" that the software has been built
  87  * from the repository rather than a "blessed" distribution.
  88  *
  89  * When rolling a tarball, we automatically replace this text with " (r1234)"
  90  * (where 1234 is the last revision on the branch prior to the release)
  91  * for final releases; in prereleases, it becomes " (Alpha 1)",
  92  * " (Beta 1)", etc., as appropriate.
  93  *
  94  * Always change this at the same time as SVN_VER_NUMTAG.
  95  */
  96 #define SVN_VER_TAG        " (r1740329)"
  97
  98
  99 /** Number tag: a string describing the version.
 100  *
 101  * This tag is used to generate a version number string to identify
 102  * the client and server in HTTP requests, for example. It must not
 103  * contain any spaces. This value remains "-dev" in the repository.
 104  *
 105  * When rolling a tarball, we automatically replace this text with ""
 106  * for final releases; in prereleases, it becomes "-alpha1, "-beta1",
 107  * etc., as appropriate.
 108  *
 109  * Always change this at the same time as SVN_VER_TAG.
 110  */
 111 #define SVN_VER_NUMTAG     ""
 112
 113
 114 /** Revision number: The repository revision number of this release.
 115  *
 116  * This constant is used to generate the build number part of the Windows
 117  * file version. Its value remains 0 in the repository except in release
 118  * tags where it is the revision from which the tag was created.
 119  */
 120 #define SVN_VER_REVISION   1740329
 121
 122 \f
 123 /* Version strings composed from the above definitions. */
 124
 125 /** Version number */
 126 #define SVN_VER_NUM        APR_STRINGIFY(SVN_VER_MAJOR) \
 127                            "." APR_STRINGIFY(SVN_VER_MINOR) \
 128                            "." APR_STRINGIFY(SVN_VER_PATCH)
 129
 130 /** Version number with tag (contains no whitespace) */
 131 #define SVN_VER_NUMBER     SVN_VER_NUM SVN_VER_NUMTAG
 132
 133 /** Complete version string */
 134 #define SVN_VERSION        SVN_VER_NUMBER SVN_VER_TAG
 135
 136
 137 \f
 138 /* Version queries and compatibility checks */
 139
 140 /**
 141  * Version information. Each library contains a function called
 142  * svn_<i>libname</i>_version() that returns a pointer to a statically
 143  * allocated object of this type.
 144  *
 145  * @since New in 1.1.
 146  */
 147 struct svn_version_t
 148 {
 149   int major;                    /**< Major version number */
 150   int minor;                    /**< Minor version number */
 151   int patch;                    /**< Patch number */
 152
 153   /**
 154    * The version tag (#SVN_VER_NUMTAG). Must always point to a
 155    * statically allocated string.
 156    */
 157   const char *tag;
 158 };
 159
 160 /**
 161  * Define a static svn_version_t object.
 162  *
 163  * @since New in 1.1.
 164  */
 165 #define SVN_VERSION_DEFINE(name) \
 166   static const svn_version_t name = \
 167     { \
 168       SVN_VER_MAJOR, \
 169       SVN_VER_MINOR, \
 170       SVN_VER_PATCH, \
 171       SVN_VER_NUMTAG \
 172     } \
 173
 174 /**
 175  * Generate the implementation of a version query function.
 176  *
 177  * @since New in 1.1.
 178  * @since Since 1.9, embeds a string into the compiled object
 179  *        file that can be queried with the 'what' utility.
 180  */
 181 #define SVN_VERSION_BODY            \
 182   static struct versioninfo_t       \
 183     {                               \
 184       const char *const str;        \
 185       const svn_version_t num;      \
 186     } const versioninfo =           \
 187     {                               \
 188       "@(#)" SVN_VERSION,           \
 189       {                             \
 190         SVN_VER_MAJOR,              \
 191         SVN_VER_MINOR,              \
 192         SVN_VER_PATCH,              \
 193         SVN_VER_NUMTAG              \
 194       }                             \
 195     };                              \
 196   return &versioninfo.num
 197
 198 /**
 199  * Check library version compatibility. Return #TRUE if the client's
 200  * version, given in @a my_version, is compatible with the library
 201  * version, provided in @a lib_version.
 202  *
 203  * This function checks for version compatibility as per our
 204  * guarantees, but requires an exact match when linking to an
 205  * unreleased library. A development client is always compatible with
 206  * a previous released library.
 207  *
 208  * @note Implements the #svn_ver_check_list2.@a comparator interface.
 209  *
 210  * @since New in 1.1.
 211  */
 212 svn_boolean_t
 213 svn_ver_compatible(const svn_version_t *my_version,
 214                    const svn_version_t *lib_version);
 215
 216 /**
 217  * Check if @a my_version and @a lib_version encode the same version number.
 218  *
 219  * @note Implements the #svn_ver_check_list2.@a comparator interface.
 220  *
 221  * @since New in 1.2.
 222  */
 223 svn_boolean_t
 224 svn_ver_equal(const svn_version_t *my_version,
 225               const svn_version_t *lib_version);
 226
 227
 228 /**
 229  * An entry in the compatibility checklist.
 230  * @see svn_ver_check_list()
 231  *
 232  * @since New in 1.1.
 233  */
 234 typedef struct svn_version_checklist_t
 235 {
 236   const char *label;            /**< Entry label */
 237
 238   /** Version query function for this entry */
 239   const svn_version_t *(*version_query)(void);
 240 } svn_version_checklist_t;
 241
 242
 243 /**
 244  * Perform a series of version compatibility checks. Checks if @a
 245  * my_version is compatible with each entry in @a checklist. @a
 246  * checklist must end with an entry whose label is @c NULL.
 247  *
 248  * @a my_version is considered to be compatible with a version in @a checklist
 249  * if @a comparator returns #TRUE when called with @a my_version as the first
 250  * parammeter and the @a checklist version as the second parameter.
 251  *
 252  * @see svn_ver_compatible(), svn_ver_equal()
 253  *
 254  * @note Subversion's own code invariably uses svn_ver_equal() as @a comparator,
 255  * since the cmdline tools sometimes use non-public APIs (such as utility
 256  * functions that haven't been promoted to svn_cmdline.h).  Third-party code
 257  * SHOULD use svn_ver_compatible() as @a comparator.
 258  *
 259  * @since New in 1.9.
 260  */
 261 svn_error_t *
 262 svn_ver_check_list2(const svn_version_t *my_version,
 263                     const svn_version_checklist_t *checklist,
 264                     svn_boolean_t (*comparator)(const svn_version_t *,
 265                                                 const svn_version_t *));
 266
 267 /** Similar to svn_ver_check_list2(), with @a comparator set to
 268  * #svn_ver_compatible.
 269  *
 270  * @deprecated Provided for backward compatibility with 1.8 API.
 271  */
 272 SVN_DEPRECATED
 273 svn_error_t *
 274 svn_ver_check_list(const svn_version_t *my_version,
 275                    const svn_version_checklist_t *checklist);
 276
 277
 278 /**
 279  * Type of function returning library version.
 280  *
 281  * @since New in 1.6.
 282  */
 283 typedef const svn_version_t *(*svn_version_func_t)(void);
 284
 285
 286 /* libsvn_subr doesn't have an svn_subr header, so put the prototype here. */
 287 /**
 288  * Get libsvn_subr version information.
 289  *
 290  * @since New in 1.1.
 291  */
 292 const svn_version_t *
 293 svn_subr_version(void);
 294
 295
 296 /**
 297  * Extended version information, including info about the running system.
 298  *
 299  * @since New in 1.8.
 300  */
 301 typedef struct svn_version_extended_t svn_version_extended_t;
 302
 303 /**
 304  * Return version information for the running program.  If @a verbose
 305  * is #TRUE, collect extra information that may be expensive to
 306  * retrieve (for example, the OS release name, list of shared
 307  * libraries, etc.).  Use @a pool for all allocations.
 308  *
 309  * @note This function may allocate significant auxiliary resources
 310  * (memory and file descriptors) in @a pool.  It is recommended to
 311  * copy the returned data to suitable longer-lived memory and clear
 312  * @a pool after calling this function.
 313  *
 314  * @since New in 1.8.
 315  */
 316 const svn_version_extended_t *
 317 svn_version_extended(svn_boolean_t verbose,
 318                      apr_pool_t *pool);
 319
 320
 321 /**
 322  * Accessor for svn_version_extended_t.
 323  *
 324  * @return The date when the libsvn_subr library was compiled, in the
 325  * format defined by the C standard macro @c __DATE__.
 326  *
 327  * @since New in 1.8.
 328  */
 329 const char *
 330 svn_version_ext_build_date(const svn_version_extended_t *ext_info);
 331
 332 /**
 333  * Accessor for svn_version_extended_t.
 334  *
 335  * @return The time when the libsvn_subr library was compiled, in the
 336  * format defined by the C standard macro @c __TIME__.
 337  *
 338  * @since New in 1.8.
 339  */
 340 const char *
 341 svn_version_ext_build_time(const svn_version_extended_t *ext_info);
 342
 343 /**
 344  * Accessor for svn_version_extended_t.
 345  *
 346  * @return The canonical host triplet (arch-vendor-osname) of the
 347  * system where libsvn_subr was compiled.
 348  *
 349  * @note On Unix-like systems (includng Mac OS X), this string is the
 350  * same as the output of the config.guess script.
 351  *
 352  * @since New in 1.8.
 353  */
 354 const char *
 355 svn_version_ext_build_host(const svn_version_extended_t *ext_info);
 356
 357 /**
 358  * Accessor for svn_version_extended_t.
 359  *
 360  * @return The localized copyright notice.
 361  *
 362  * @since New in 1.8.
 363  */
 364 const char *
 365 svn_version_ext_copyright(const svn_version_extended_t *ext_info);
 366
 367 /**
 368  * Accessor for svn_version_extended_t.
 369  *
 370  * @return The canonical host triplet (arch-vendor-osname) of the
 371  * system where the current process is running.
 372  *
 373  * @note This string may not be the same as the output of config.guess
 374  * on the same system.
 375  *
 376  * @since New in 1.8.
 377  */
 378 const char *
 379 svn_version_ext_runtime_host(const svn_version_extended_t *ext_info);
 380
 381 /**
 382  * Accessor for svn_version_extended_t.
 383  *
 384  * @return The "commercial" release name of the running operating
 385  * system, if available.  Not to be confused with, e.g., the output of
 386  * "uname -v" or "uname -r".  The returned value may be @c NULL.
 387  *
 388  * @since New in 1.8.
 389  */
 390 const char *
 391 svn_version_ext_runtime_osname(const svn_version_extended_t *ext_info);
 392
 393 /**
 394  * Dependent library information.
 395  * Describes the name and versions of known dependencies
 396  * used by libsvn_subr.
 397  *
 398  * @since New in 1.8.
 399  */
 400 typedef struct svn_version_ext_linked_lib_t
 401 {
 402   const char *name;             /**< Library name */
 403   const char *compiled_version; /**< Compile-time version string */
 404   const char *runtime_version;  /**< Run-time version string (optional) */
 405 } svn_version_ext_linked_lib_t;
 406
 407 /**
 408  * Accessor for svn_version_extended_t.
 409  *
 410  * @return Array of svn_version_ext_linked_lib_t describing dependent
 411  * libraries.  The returned value may be @c NULL.
 412  *
 413  * @since New in 1.8.
 414  */
 415 const apr_array_header_t *
 416 svn_version_ext_linked_libs(const svn_version_extended_t *ext_info);
 417
 418
 419 /**
 420  * Loaded shared library information.
 421  * Describes the name and, where available, version of the shared libraries
 422  * loaded by the running program.
 423  *
 424  * @since New in 1.8.
 425  */
 426 typedef struct svn_version_ext_loaded_lib_t
 427 {
 428   const char *name;             /**< Library name */
 429   const char *version;          /**< Library version (optional) */
 430 } svn_version_ext_loaded_lib_t;
 431
 432
 433 /**
 434  * Accessor for svn_version_extended_t.
 435  *
 436  * @return Array of svn_version_ext_loaded_lib_t describing loaded
 437  * shared libraries.  The returned value may be @c NULL.
 438  *
 439  * @note On Mac OS X, the loaded frameworks, private frameworks and
 440  * system libraries will not be listed.
 441  *
 442  * @since New in 1.8.
 443  */
 444 const apr_array_header_t *
 445 svn_version_ext_loaded_libs(const svn_version_extended_t *ext_info);
 446
 447
 448 #ifdef __cplusplus
 449 }
 450 #endif /* __cplusplus */
 451
 452 #endif /* SVN_VERSION_H */