include/rtems/version.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSAPIClassicVersion
0007  *
0008  * @brief This header file provides the Version API.
0009  */
0010
0011 /*
0012  *  Copyright (C) 2017.
0013  *  Chris Johns <chrisj@rtems.org>
0014  *
0015  * Redistribution and use in source and binary forms, with or without
0016  * modification, are permitted provided that the following conditions
0017  * are met:
0018  * 1. Redistributions of source code must retain the above copyright
0019  *    notice, this list of conditions and the following disclaimer.
0020  * 2. Redistributions in binary form must reproduce the above copyright
0021  *    notice, this list of conditions and the following disclaimer in the
0022  *    documentation and/or other materials provided with the distribution.
0023  *
0024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0025  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0026  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0027  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0028  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0029  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0030  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0031  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0032  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0033  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0034  * POSSIBILITY OF SUCH DAMAGE.
0035  */
0036
0037 #ifndef _RTEMS_VERSION_H
0038 #define _RTEMS_VERSION_H
0039
0040 #include <stdbool.h>
0041
0042 #ifdef __cplusplus
0043 extern "C" {
0044 #endif
0045
0046 /**
0047  * @defgroup RTEMSAPIClassicVersion Version
0048  *
0049  * @ingroup RTEMSAPIClassic
0050  *
0051  * @brief The Version API provides functions to return the version or parts of
0052  * the version of RTEMS you are using.
0053  *
0054  * A branch in the version control system will always fall back to a
0055  * NOT-RELEASED version number with a minor number of 0. Only the release
0056  * archives have a VERSION file with a final release number. That means for
0057  * example that the 5 development branch will still show a version 5.0.0 even
0058  * after the 5.1 release.
0059  *
0060  * The reason for that are the following:
0061  *
0062  * 1. All pre-release tests are performed with a specific git hash. A committed
0063  * VERSION file would need to be changed and committed afterwards for releasing
0064  * with the required release version causing the released version to have a
0065  * different git hash and the test results couldn't be linked to the released
0066  * version.
0067  *
0068  * 2. Users deploying RTEMS would need to commit a local change to a committed
0069  * VERSION file and that would clash with the project changes. Deployment can
0070  * use the project repos directly.
0071  *
0072  * 3. The VERSION file management and generation is the responsibility of the
0073  * release manager and the release process.
0074  *
0075  * @{
0076  */
0077
0078 /**
0079  * @brief Returns the version string.
0080  *
0081  * @retval text The version as a string.
0082  */
0083 const char *rtems_version( void );
0084
0085 /**
0086  * @brief Returns the version's major number.
0087  *
0088  * @retval int The version's major number.
0089  */
0090 int rtems_version_major( void );
0091
0092 /**
0093  * @brief Returns the version's minor number.
0094  *
0095  * @retval int The version's minor number.
0096  */
0097 int rtems_version_minor( void );
0098
0099 /**
0100  * @brief Returns the version's revision number.
0101  *
0102  * @retval int The version's revision number.
0103  */
0104 int rtems_version_revision( void );
0105
0106 /**
0107  * @deprecated
0108  *
0109  * @brief Returns the version control key for the current version of code that
0110  * has been built.
0111  *
0112  * The key is specific to the version control system being used and allows the
0113  * built version to be identified.
0114  *
0115  * Use rtems_version_control_key_is_valid() to check if the version control key
0116  * is valid.
0117  *
0118  * @return The version control key.
0119  */
0120 const char *rtems_version_control_key( void );
0121
0122 /**
0123  * @deprecated
0124  *
0125  * @brief Returns true, if the version control key is valid, otherwise false.
0126  *
0127  * @retval true The version control key is valid.
0128  * @retval false Otherwise.
0129  */
0130 static inline bool rtems_version_control_key_is_valid( const char *key )
0131 {
0132   return key[ 0 ] != '\0';
0133 }
0134
0135 /**
0136  * @brief Returns the revision label for the current version of code
0137  * that has been built.
0138  *
0139  * The release label is a string of characters. Only the RTEMS project
0140  * released sources can have an empty release label.
0141  *
0142  * Use rtems_version_release_label_is_valid() to check if the release label
0143  * is valid.
0144  *
0145  * @return The release label.
0146  */
0147 const char *rtems_version_release_label( void );
0148
0149 /**
0150  * @brief Returns true, if the release label is valid, otherwise false.
0151  *
0152  * @retval true The release label is valid.
0153  * @retval false Otherwise.
0154  */
0155 bool rtems_version_release_label_is_valid( void );
0156
0157 /**
0158  * @brief Returns the board support package name.
0159  *
0160  * @return The board support package name.
0161  */
0162 const char *rtems_board_support_package( void );
0163
0164 /** @} */
0165
0166 #ifdef __cplusplus
0167 }
0168 #endif
0169
0170 #endif
0171 /* end of include file */