diff options
Diffstat (limited to 'doc/manual/versions.rst')
| -rw-r--r-- | doc/manual/versions.rst | 44 |
1 files changed, 26 insertions, 18 deletions
diff --git a/doc/manual/versions.rst b/doc/manual/versions.rst index 9b0e1d8fc..14a7dfec5 100644 --- a/doc/manual/versions.rst +++ b/doc/manual/versions.rst @@ -2,19 +2,16 @@ Versioning ======================================== -As of Botan 2.0.0, Botan uses semantic versioning. So in a future -release, if even a small feature is added, the minor number will -increase and the next release will be 2.1.0. If an incompatible API -change is required, the major version will be increased. +All versions are of the tuple (major,minor,patch). -The library has functions for checking compile-time and runtime -versions. +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. -All versions are of the tuple (major,minor,patch). Even minor versions -indicate stable releases while odd minor versions indicate a -development release. +The library has functions for checking compile-time and runtime versions. -The compile time version information is defined in `botan/build.h` +The build-time version information is defined in `botan/build.h` .. c:macro:: BOTAN_VERSION_MAJOR @@ -41,16 +38,16 @@ The compile time version information is defined in `botan/build.h` 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 'unspecified'. + 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 - cooresponding 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 Monotone workspace. + cooresponding 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` @@ -77,16 +74,27 @@ version checks, are included in `botan/version.h` 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 discrepency. 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 - versions before 1.10 and another for 1.10 or later:: + version 2.1.0 and later, and another code path for older releases:: - #if BOTAN_VERSION_CODE >= BOTAN_VERSION_CODE_FOR(1,10,0) - // 1.10 code path + #if BOTAN_VERSION_CODE >= BOTAN_VERSION_CODE_FOR(2,1,0) + // 2.1+ code path #else - // pre-1.10 code path + // code path for older versions #endif |