Introduce new Gmmlib tagging scheme (#87)

Author: johnmach

README.rst

@@ -21,24 +21,36 @@ https://opensource.org/licenses/MIT
 
 Building
 ========
-
-1) Get gmmlib repo
-
-       |- gmmlib
+1) Get gmmlib repository
 
 2) Change it to root directory
 
-   $ cd gmmlib
+   ``$ cd gmmlib``
+
+3) Make a build directory
+   
+   ``$ mkdir build && cd build``
 
-3) $ mkdir build && cd build
+4) Run the cmake command to prepare build files
 
-4) cmake [-DCMAKE_BUILD_TYPE= Release | Debug | ReleaseInternal] [-DARCH= 64 | 32]  ..
+   ``$ cmake [-DCMAKE_BUILD_TYPE= Release | Debug | ReleaseInternal] [-DARCH= 64 | 32]  ..``
 
-5) $ make -j8 ( Also performs compile time ULT)
+5) Build the project
 
+   ``$ make -j"$(nproc)" (Also performs compile time ULT)``
 
 Install
-^^^^^^^
+=======
+``$ sudo make install``
+
+This will install the following files (e.g. on Ubuntu):
+
+| -- Install configuration: "Release"
+| -- Installing: /usr/local/lib/libigdgmm.so.12.1.0
+| -- Installing: /usr/local/lib/libigdgmm.so.12
+| 
+
+
 Not a stand alone software component.
 GmmLib is built as dynamic library for Intel media driver and Compute runtime for OpenCL
 
@@ -70,9 +82,32 @@ XE_HPC (PVC: Ponte Vecchio)
 
 XE_HPG (DG2, ACM: Alchemist)
 
+Release Tags
+============
+
+Gmmlib Release tag versioning schema follows:
+
+| Tag ``intel-gmmlib-<x>.<y>.<z>`` will be stable release series with the same API and ABI version with only bug fixes where,
+| x = GMMLIB_API_MAJOR_VERSION + 10,
+| y = GMMLIB_API_MINOR_VERSION,
+| z = RELEASE NUMBER which is incremented as 0,1,2,...n for changes including new flag, bug fixes, etc.
+| 
+| Example:
+|   For GMM library ``libigdgmm.so.12.0.0``,
+|   Tag = ``intel-gmmlib-22.0.0`` where,
+|        22 = GMMLIB_API_MAJOR_VERSION + 10 = 12 + 10
+|        0 = GMMLIB_API_MINOR_VERSION
+|        0 = RELEASE NUMBER
+|
+On potential ABI break changes,
+
+| Tag ``intel-gmmlib-<x>.<y>.<z>`` becomes ``intel-gmmlib-<x + 1>.0.0``
+| i.e ``intel-gmmlib-22.5.3`` becomes ``intel-gmmlib-23.0.0``
+
 Known Issues and Limitations
-----------------------------
-- Current Gmmlib support only limited to Linux
+============================
+Current Gmmlib support only limited to Linux
 
 (*) Other names and brands may be claimed as property of others.
 ---------------------------------------------------------------
+

Source/GmmLib/CMakeLists.txt

@@ -43,6 +43,26 @@ if(NOT DEFINED GMMLIB_API_PATCH_VERSION)
     set(GMMLIB_API_PATCH_VERSION ${PATCH_VERSION})
 endif()
 
+# The Gmmlib dll is generated as libigdgmm.so.<x>.<y>.<z> where,
+# <x> = GMMLIB_API_MAJOR_VERSION
+# <y> = GMMLIB_API_MINOR_VERSION
+# <z> = GMMLIB_API_PATCH_VERSION
+#
+# Example: libigdgmm.so.12.0.0
+# 12 = GMMLIB_API_MAJOR_VERSION
+# 0  = GMMLIB_API_MINOR_VERSION
+# 0  = GMMLIB_API_PATCH_VERSION
+#
+# Library version update
+# - increment major for any ABI change
+# - increment minor for any interface change (e.g. new/modified function)
+#
+# Example:
+# On potential ABI break changes
+#
+# libigdgmm.so.<GMMLIB_API_MAJOR_VERSION>.y.z becomes libigdgmm.so.<GMMLIB_API_MAJOR_VERSION + 1>.0.0
+# i.e libigdgmm.so.12.5.0 becomes libigdgmm.so.13.0.0
+
 message(STATUS "API version: ${GMMLIB_API_MAJOR_VERSION}.${GMMLIB_API_MINOR_VERSION}.${GMMLIB_API_PATCH_VERSION}")
 message(STATUS "Package version: ${MAJOR_VERSION}.${MINOR_VERSION}.${PATCH_VERSION}")