Merge topic 'doc-SOVERSION-first-component-VERSION'

fcab4bee21 Help: Document conventional VERSION/SOVERSION relationship

Acked-by: Kitware Robot <[email protected]>
Merge-request: !9177

Help/prop_tgt/SOVERSION.rst

@@ -1,15 +1,17 @@
 SOVERSION
 ---------
 
-What version number is this target.
+ABI version number of a shared library target.
 
 For shared libraries :prop_tgt:`VERSION` and ``SOVERSION`` can be used to
-specify the build version and API version respectively.  When building or
+specify the build version and ABI version respectively.  When building or
 installing appropriate symlinks are created if the platform supports
 symlinks and the linker supports so-names.  If only one of both is
 specified the missing is assumed to have the same version number.
 ``SOVERSION`` is ignored if :prop_tgt:`NO_SONAME` property is set.
 
+.. include:: VERSION_SOVERSION_EXAMPLE.txt
+
 Windows Versions
 ^^^^^^^^^^^^^^^^
 

Help/prop_tgt/VERSION.rst

@@ -1,10 +1,10 @@
 VERSION
 -------
 
-What version number is this target.
+Version number of a shared library target.
 
 For shared libraries ``VERSION`` and :prop_tgt:`SOVERSION` can be used
-to specify the build version and API version respectively.  When building or
+to specify the build version and ABI version respectively.  When building or
 installing appropriate symlinks are created if the platform supports
 symlinks and the linker supports so-names.  If only one of both is
 specified the missing is assumed to have the same version number.  For
@@ -12,6 +12,8 @@ executables ``VERSION`` can be used to specify the build version.  When
 building or installing appropriate symlinks are created if the
 platform supports symlinks.
 
+.. include:: VERSION_SOVERSION_EXAMPLE.txt
+
 Windows Versions
 ^^^^^^^^^^^^^^^^
 

Help/prop_tgt/VERSION_SOVERSION_EXAMPLE.txt

@@ -0,0 +1,9 @@
+A common convention is to specify both ``VERSION`` and ``SOVERSION``
+such that ``SOVERSION`` matches the first component of ``VERSION``:
+
+.. code-block:: cmake
+
+  set_target_properties(mylib PROPERTIES VERSION 1.2.3 SOVERSION 1)
+
+The idea is that breaking changes to the ABI increment both the
+``SOVERSION`` and the major ``VERSION`` number.