103 lines
3.3 KiB
ReStructuredText
103 lines
3.3 KiB
ReStructuredText
|
|
.. _versioning:
|
|
|
|
Versioning
|
|
========================================
|
|
|
|
All versions are of the tuple (major,minor,patch).
|
|
|
|
As of Botan 2.0.0, Botan uses semantic versioning. The minor number increases if
|
|
any feature addition is made. The patch version is used to indicate a release
|
|
where only bug fixes were applied. If an incompatible API change is required,
|
|
the major version will be increased.
|
|
|
|
The library has functions for checking compile-time and runtime versions.
|
|
|
|
The build-time version information is defined in `botan/build.h`
|
|
|
|
.. c:macro:: BOTAN_VERSION_MAJOR
|
|
|
|
The major version of the release.
|
|
|
|
.. c:macro:: BOTAN_VERSION_MINOR
|
|
|
|
The minor version of the release.
|
|
|
|
.. c:macro:: BOTAN_VERSION_PATCH
|
|
|
|
The patch version of the release.
|
|
|
|
.. c:macro:: BOTAN_VERSION_DATESTAMP
|
|
|
|
Expands to an integer of the form YYYYMMDD if this is an official
|
|
release, or 0 otherwise. For instance, 1.10.1, which was released
|
|
on July 11, 2011, has a `BOTAN_VERSION_DATESTAMP` of 20110711.
|
|
|
|
.. c:macro:: BOTAN_DISTRIBUTION_INFO
|
|
|
|
.. versionadded:: 1.9.3
|
|
|
|
A macro expanding to a string that is set at build time using the
|
|
``--distribution-info`` option. It allows a packager of the library
|
|
to specify any distribution-specific patches. If no value is given
|
|
at build time, the value is the string "unspecified".
|
|
|
|
.. c:macro:: BOTAN_VERSION_VC_REVISION
|
|
|
|
.. versionadded:: 1.10.1
|
|
|
|
A macro expanding to a string that is set to a revision identifier
|
|
corresponding to the source, or "unknown" if this could not be
|
|
determined. It is set for all official releases, and for builds that
|
|
originated from within a git checkout.
|
|
|
|
The runtime version information, and some helpers for compile time
|
|
version checks, are included in `botan/version.h`
|
|
|
|
.. cpp:function:: std::string version_string()
|
|
|
|
Returns a single-line string containing relevant information about
|
|
this build and version of the library in an unspecified format.
|
|
|
|
.. cpp:function:: uint32_t version_major()
|
|
|
|
Returns the major part of the version.
|
|
|
|
.. cpp:function:: uint32_t version_minor()
|
|
|
|
Returns the minor part of the version.
|
|
|
|
.. cpp:function:: uint32_t version_patch()
|
|
|
|
Returns the patch part of the version.
|
|
|
|
.. cpp:function:: uint32_t version_datestamp()
|
|
|
|
Return the datestamp of the release (or 0 if the current version is
|
|
not an official release).
|
|
|
|
.. cpp:function:: std::string runtime_version_check(uint32_t major, uint32_t minor, uint32_t patch)
|
|
|
|
Call this function with the compile-time version being built against, eg::
|
|
|
|
Botan::runtime_version_check(BOTAN_VERSION_MAJOR, BOTAN_VERSION_MINOR, BOTAN_VERSION_PATCH)
|
|
|
|
It will return an empty string if the versions match, or otherwise
|
|
an error message indicating the discrepancy. This only is useful in
|
|
dynamic libraries, where it is possible to compile and run against
|
|
different versions.
|
|
|
|
.. c:macro:: BOTAN_VERSION_CODE_FOR(maj,min,patch)
|
|
|
|
Return a value that can be used to compare versions. The current
|
|
(compile-time) version is available as the macro
|
|
`BOTAN_VERSION_CODE`. For instance, to choose one code path for
|
|
version 2.1.0 and later, and another code path for older releases::
|
|
|
|
#if BOTAN_VERSION_CODE >= BOTAN_VERSION_CODE_FOR(2,1,0)
|
|
// 2.1+ code path
|
|
#else
|
|
// code path for older versions
|
|
#endif
|
|
|