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