1 files changed, 100 insertions, 0 deletions
diff --git a/comm/third_party/botan/doc/api_ref/versions.rst b/comm/third_party/botan/doc/api_ref/versions.rst
new file mode 100644
index 0000000000..511141b75f
--- /dev/null
+++ b/comm/third_party/botan/doc/api_ref/versions.rst
@@ -0,0 +1,100 @@
+
+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
+