include/babeltrace2/version.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_VERSION_H
   8 #define BABELTRACE2_VERSION_H
   9
  10 #ifndef __BT_IN_BABELTRACE_H
  11 # error "Please include <babeltrace2/babeltrace.h> instead."
  12 #endif
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 /*!
  19 @defgroup api-version Library version
  20
  21 @brief
  22     Library version getters.
  23
  24 This module contains functions to get information about the library's
  25 version:
  26
  27 <dl>
  28   <dt>Major version</dt>
  29   <dd>bt_version_get_major()</dd>
  30
  31   <dt>Minor version</dt>
  32   <dd>bt_version_get_minor()</dd>
  33
  34   <dt>Patch version</dt>
  35   <dd>bt_version_get_patch()</dd>
  36
  37   <dt>\bt_dt_opt Development stage</dt>
  38   <dd>bt_version_get_development_stage()</dd>
  39
  40   <dt>\bt_dt_opt Version control system revision's description</dt>
  41   <dd>bt_version_get_vcs_revision_description()</dd>
  42
  43   <dt>\bt_dt_opt Release name</dt>
  44   <dd>bt_version_get_name()</dd>
  45
  46   <dt>\bt_dt_opt Release name's description</dt>
  47   <dd>bt_version_get_name_description()</dd>
  48
  49   <dt>\bt_dt_opt Extra name</dt>
  50   <dd>bt_version_get_extra_name()</dd>
  51
  52   <dt>\bt_dt_opt Extra description</dt>
  53   <dd>bt_version_get_extra_description()</dd>
  54
  55   <dt>\bt_dt_opt Extra patch names</dt>
  56   <dd>bt_version_get_extra_patch_names()</dd>
  57 </dl>
  58 */
  59
  60 /*! @{ */
  61
  62 /*!
  63 @brief
  64     Returns the major version of libbabeltrace2.
  65
  66 @returns
  67     Major version of the library.
  68 */
  69 extern unsigned int bt_version_get_major(void);
  70
  71 /*!
  72 @brief
  73     Returns the minor version of libbabeltrace2.
  74
  75 @returns
  76     Minor version of the library.
  77 */
  78 extern unsigned int bt_version_get_minor(void);
  79
  80 /*!
  81 @brief
  82     Returns the patch version of libbabeltrace2.
  83
  84 @returns
  85     Patch version of the library.
  86 */
  87 extern unsigned int bt_version_get_patch(void);
  88
  89 /*!
  90 @brief
  91     Returns the development stage of libbabeltrace2's version.
  92
  93 The development stage \em can contain a version suffix such as
  94 <code>-pre5</code> or <code>-rc1</code>.
  95
  96 @returns
  97     Development stage of the library's version, or \c NULL if none.
  98 */
  99 extern const char *bt_version_get_development_stage(void);
 100
 101 /*!
 102 @brief
 103     Returns the version control system (VCS) revision's description of
 104     libbabeltrace2's version.
 105
 106 The VCS revision description is only available for a non-release build
 107 of the library.
 108
 109 @returns
 110     Version control system revision's description of the library's
 111     version, or \c NULL if none.
 112 */
 113 extern const char *bt_version_get_vcs_revision_description(void);
 114
 115 /*!
 116 @brief
 117     Returns libbabeltrace2's release name.
 118
 119 If the release name is not available, which can be the case for a
 120 development build, this function returns \c NULL.
 121
 122 @returns
 123     Library's release name, or \c NULL if not available.
 124
 125 @sa bt_version_get_name_description() &mdash;
 126     Returns the description of libbabeltrace2's release name.
 127 */
 128 extern const char *bt_version_get_name(void);
 129
 130 /*!
 131 @brief
 132     Returns libbabeltrace2's release name's description.
 133
 134 If the release name's description is not available, which can be the
 135 case for a development build, this function returns \c NULL.
 136
 137 @returns
 138     Library's release name's description, or \c NULL if not available.
 139
 140 @sa bt_version_get_name() &mdash;
 141     Returns libbabeltrace2's release name.
 142 */
 143 extern const char *bt_version_get_name_description(void);
 144
 145 /*!
 146 @brief
 147     Returns the extra name of libbabeltrace2's version.
 148
 149 The extra name of the library's version can be set at build time for a
 150 custom build.
 151
 152 @returns
 153     Library's version extra name, or \c NULL if not available.
 154 */
 155 extern const char *bt_version_get_extra_name(void);
 156
 157 /*!
 158 @brief
 159     Returns the extra description of libbabeltrace2's version.
 160
 161 The extra description of the library's version can be set at build time
 162 for a custom build.
 163
 164 @returns
 165     @parblock
 166     Library's version extra description, or \c NULL if not available.
 167
 168     Can contain newlines.
 169     @endparblock
 170 */
 171 extern const char *bt_version_get_extra_description(void);
 172
 173 /*!
 174 @brief
 175     Returns the extra patch names of libbabeltrace2's version.
 176
 177 The extra patch names of the library's version can be set at build time
 178 for a custom build.
 179
 180 @returns
 181     @parblock
 182     Library's version extra patch names, or \c NULL if not available.
 183
 184     Each line of the returned string contains the name of a patch
 185     applied to Babeltrace's source tree for a custom build.
 186     @endparblock
 187 */
 188 extern const char *bt_version_get_extra_patch_names(void);
 189
 190 /*! @} */
 191
 192 #ifdef __cplusplus
 193 }
 194 #endif
 195
 196 #endif /* BABELTRACE2_VERSION_H */