Merge topic 'docs_macho_prop_tgt' into release-3.17

01b47293ea Help: Fix inaccuracies and omissions in MACHO_* property docs

Acked-by: Kitware Robot <[email protected]>
Acked-by: Isuru Fernando <[email protected]>
Merge-request: !4542

Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst

@@ -4,11 +4,22 @@ MACHO_COMPATIBILITY_VERSION
 What compatibility version number is this target for Mach-O binaries.
 
 For shared libraries on Mach-O systems (e.g. macOS, iOS)
-the ``MACHO_COMPATIBILITY_VERSION`` property correspond to
-``compatibility version`` and :prop_tgt:`MACHO_CURRENT_VERSION` to
-``current version``.
-See the :prop_tgt:`FRAMEWORK` target property for an example.
-
-Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
-command.  If ``MACHO_COMPATIBILITY_VERSION`` is not set, the value of
-the :prop_tgt:`SOVERSION` property will be used.
+the ``MACHO_COMPATIBILITY_VERSION`` property corresponds to the
+*compatibility version* and :prop_tgt:`MACHO_CURRENT_VERSION` corresponds to
+the *current version*.  These are both embedded in the shared library binary
+and can be checked with the ``otool -L <binary>`` command.
+
+It should be noted that the :prop_tgt:`MACHO_CURRENT_VERSION` and
+``MACHO_COMPATIBILITY_VERSION`` properties do not affect the file
+names or version-related symlinks that CMake generates for the library.
+The :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties still
+control the file and symlink names.  The ``install_name`` is also still
+controlled by :prop_tgt:`SOVERSION`.
+
+When :prop_tgt:`MACHO_CURRENT_VERSION` and ``MACHO_COMPATIBILITY_VERSION``
+are not given, :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` are used for
+the version details to be embedded in the binaries respectively.
+The :prop_tgt:`MACHO_CURRENT_VERSION` and ``MACHO_COMPATIBILITY_VERSION``
+properties only need to be given if the project needs to decouple the file
+and symlink naming from the version details embedded in the binaries
+(e.g. to match libtool conventions).

Help/prop_tgt/MACHO_CURRENT_VERSION.rst

@@ -4,10 +4,22 @@ MACHO_CURRENT_VERSION
 What current version number is this target for Mach-O binaries.
 
 For shared libraries on Mach-O systems (e.g. macOS, iOS)
-the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` property correspond to
-``compatibility version`` and ``MACHO_CURRENT_VERSION`` to ``current version``.
-See the :prop_tgt:`FRAMEWORK` target property for an example.
+the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` property corresponds to the
+*compatibility version* and ``MACHO_CURRENT_VERSION`` corresponds to the
+*current version*.  These are both embedded in the shared library binary
+and can be checked with the ``otool -L <binary>`` command.
 
-Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
-command.  If ``MACHO_CURRENT_VERSION`` is not set, the value of
-the :prop_tgt:`VERSION` property will be used.
+It should be noted that the ``MACHO_CURRENT_VERSION`` and
+:prop_tgt:`MACHO_COMPATIBILITY_VERSION` properties do not affect the file
+names or version-related symlinks that CMake generates for the library.
+The :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties still
+control the file and symlink names.  The ``install_name`` is also still
+controlled by :prop_tgt:`SOVERSION`.
+
+When ``MACHO_CURRENT_VERSION`` and :prop_tgt:`MACHO_COMPATIBILITY_VERSION`
+are not given, :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` are used for
+the version details to be embedded in the binaries respectively.
+The ``MACHO_CURRENT_VERSION`` and :prop_tgt:`MACHO_COMPATIBILITY_VERSION`
+properties only need to be given if the project needs to decouple the file
+and symlink naming from the version details embedded in the binaries
+(e.g. to match libtool conventions).

Help/prop_tgt/SOVERSION.rst

@@ -21,9 +21,17 @@ Mach-O Versions
 ^^^^^^^^^^^^^^^
 
 For shared libraries and executables on Mach-O systems (e.g. macOS, iOS),
-the ``SOVERSION`` property is a fallback to
-:prop_tgt:`MACHO_COMPATIBILITY_VERSION` property which corresponds to
-*compatiblity version* and :prop_tgt:`VERSION` is a fallback to
-:prop_tgt:`MACHO_CURRENT_VERSION` which corresponds to *current version*.
-See the :prop_tgt:`FRAMEWORK` target property for an example.  Versions
-of Mach-O binaries may be checked with the ``otool -L <binary>`` command.
+the ``SOVERSION`` property corresponds to the *compatibility version* and
+:prop_tgt:`VERSION` corresponds to the *current version* (unless Mach-O
+specific overrides are provided, as discussed below).
+See the :prop_tgt:`FRAMEWORK` target property for an example.
+
+For shared libraries, the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and
+:prop_tgt:`MACHO_CURRENT_VERSION` properties can be used to
+override the *compatibility version* and *current version* respectively.
+Note that ``SOVERSION`` will still be used to form the ``install_name``
+and both ``SOVERSION`` and :prop_tgt:`VERSION` may also affect the file
+and symlink names.
+
+Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
+command.

Help/prop_tgt/VERSION.rst

@@ -23,9 +23,17 @@ Mach-O Versions
 ^^^^^^^^^^^^^^^
 
 For shared libraries and executables on Mach-O systems (e.g. macOS, iOS),
-the ``VERSION`` property is a fallback to :prop_tgt:`MACHO_CURRENT_VERSION`
-property which corresponds to *current version* and :prop_tgt:`SOVERSION`
-is a fallback to :prop_tgt:`MACHO_COMPATIBILITY_VERSION` which corresponds
-to *compatiblity version*.  See the :prop_tgt:`FRAMEWORK` target
-property for an example.  Versions of Mach-O binaries may be checked with the
-``otool -L <binary>`` command.
+the :prop_tgt:`SOVERSION` property corresponds to the *compatibility version*
+and ``VERSION`` corresponds to the *current version* (unless Mach-O specific
+overrides are provided, as discussed below).
+See the :prop_tgt:`FRAMEWORK` target property for an example.
+
+For shared libraries, the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and
+:prop_tgt:`MACHO_CURRENT_VERSION` properties can be used to
+override the *compatibility version* and *current version* respectively.
+Note that :prop_tgt:`SOVERSION` will still be used to form the
+``install_name`` and both :prop_tgt:`SOVERSION` and ``VERSION`` may also
+affect the file and symlink names.
+
+Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
+command.