Merge topic 'patch-FindGTK'

e4554c0f16 FindGTK*: Update documentation

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

Modules/FindGTK.cmake

@@ -5,14 +5,64 @@
 FindGTK
 -------
 
-Find GTK, glib and GTKGLArea
+Finds GTK, glib and GTKGLArea.
 
-::
+GTK is a multi-platform toolkit for creating graphical user interfaces.
 
-  GTK_INCLUDE_DIR   - Directories to include to use GTK
-  GTK_LIBRARIES     - Files to link against to use GTK
-  GTK_FOUND         - GTK was found
-  GTK_GL_FOUND      - GTK's GL features were found
+.. note::
+
+  This module works only on Unix-like systems and was intended for early GTK
+  branch of 1.x, which is no longer maintained.  Use the latest supported GTK
+  version and :module:`FindPkgConfig` module to find GTK in CMake instead of
+  this module.  For example:
+
+  .. code-block:: cmake
+
+    find_package(PkgConfig REQUIRED)
+    pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14)
+    target_link_libraries(example PRIVATE PkgConfig::GTK)
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``GTK_FOUND``
+  Boolean indicating whether GTK is found.
+``GTK_GL_FOUND``
+  Boolean indicating whether GTK's GL features are found.
+``GTK_INCLUDE_DIR``
+  Include directories containing headers needed to use GTK.
+``GTK_LIBRARIES``
+  Libraries needed to link against for using GTK.
+
+Examples
+^^^^^^^^
+
+Finding GTK 1.x and creating an interface :ref:`imported target
+<Imported Targets>` that encapsulates its usage requirements for linking to a
+project target:
+
+.. code-block:: cmake
+
+  find_package(GTK)
+
+  if(GTK_FOUND)
+    add_library(GTK::GTK INTERFACE IMPORTED)
+    set_target_properties(
+      GTK::GTK
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${GTK_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${GTK_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(example PRIVATE GTK::GTK)
+
+See Also
+^^^^^^^^
+
+* The :module:`FindGTK2` module to find GTK version 2.
 #]=======================================================================]
 
 # don't even bother under WIN32

Modules/FindGTK2.cmake

@@ -5,89 +5,151 @@
 FindGTK2
 --------
 
-Find the GTK2 widget libraries and several of its other optional components
-like ``gtkmm``, ``glade``, and ``glademm``.
+Finds the GTK widget libraries and several of its other optional components.
 
-Specify one or more of the following components as you call this find
-module.  See example below.
+GTK is a multi-platform toolkit for creating graphical user interfaces.
 
-* ``gtk``
-* ``gtkmm``
-* ``glade``
-* ``glademm``
+.. note::
+
+  This module is specifically for GTK version 2.x, which is obsolete and no
+  longer maintained.  Use the latest supported GTK version and
+  :module:`FindPkgConfig` module to find GTK in CMake instead of this module.
+  For example:
+
+  .. code-block:: cmake
+
+    find_package(PkgConfig REQUIRED)
+    pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14)
+    target_link_libraries(example PRIVATE PkgConfig::GTK)
+
+Components
+^^^^^^^^^^
+
+This module supports optional components, which can be specified with the
+:command:`find_package` command:
+
+.. code-block:: cmake
+
+  find_package(GTK2 [COMPONENTS <components>...])
+
+Supported components include:
+
+.. hlist::
+
+  * ``atk``
+  * ``atkmm``
+  * ``cairo``
+  * ``cairomm``
+  * ``gdk_pixbuf``
+  * ``gdk``
+  * ``gdkmm``
+  * ``gio``
+  * ``giomm``
+  * ``glade``
+  * ``glademm``
+  * ``glib``
+  * ``glibmm``
+  * ``gmodule``
+  * ``gobject``
+  * ``gthread``
+  * ``gtk``
+  * ``gtkmm``
+  * ``pango``
+  * ``pangocairo``
+  * ``pangoft2``
+  * ``pangomm``
+  * ``pangoxft``
+  * ``sigc``
+
+* .. versionadded:: 3.16.7
+    ``harfbuzz``
+
+If no components are specified, module by default searches for the ``gtk``
+component.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-This module defines the following :prop_tgt:`IMPORTED` targets (subject to
+This module provides the following :ref:`Imported Targets` (subject to
 component selection):
 
-``GTK2::atk``, ``GTK2::atkmm``, ``GTK2::cairo``, ``GTK2::cairomm``,
-``GTK2::gdk_pixbuf``, ``GTK2::gdk``, ``GTK2::gdkmm``, ``GTK2::gio``,
-``GTK2::giomm``, ``GTK2::glade``, ``GTK2::glademm``, ``GTK2::glib``,
-``GTK2::glibmm``, ``GTK2::gmodule``, ``GTK2::gobject``, ``GTK2::gthread``,
-``GTK2::gtk``, ``GTK2::gtkmm``, ``GTK2::harfbuzz``, ``GTK2::pango``,
-``GTK2::pangocairo``, ``GTK2::pangoft2``, ``GTK2::pangomm``,
-``GTK2::pangoxft``, ``GTK2::sigc``.
+``GTK2::<component>``
+  Target encapsulating the specified GTK component usage requirements,
+  available if GTK and this component are found.  The ``<component>`` should
+  be written in the same case, as listed above.  For example, use
+  ``GTK2::gtk`` for the ``gtk`` component, or ``GTK2::gdk_pixbuf`` for the
+  ``gdk_pixbuf`` component, etc.
+
+``GTK2::sigc++``
+  .. versionadded:: 3.5
 
-.. versionadded:: 3.16.7
-  Added the ``GTK2::harfbuzz`` target.
+  Target encapsulating the usage requirements to enable c++11 on its dependents
+  when using sigc++ 2.5.1 or higher.  This target is automatically applied to
+  dependent targets as needed.
 
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-The following variables will be defined for your use
+This module defines the following variables:
 
 ``GTK2_FOUND``
-  Were all of your specified components found?
-``GTK2_INCLUDE_DIRS``
-  All include directories
-``GTK2_LIBRARIES``
-  All libraries
-``GTK2_TARGETS``
-  .. versionadded:: 3.5
-    All imported targets
-``GTK2_DEFINITIONS``
-  Additional compiler flags
+  Boolean indicating whether GTK and all specified components are found.
 ``GTK2_VERSION``
-  The version of GTK2 found (x.y.z)
+  The version of GTK found (x.y.z).
 ``GTK2_MAJOR_VERSION``
-  The major version of GTK2
+  The major version of GTK found.
 ``GTK2_MINOR_VERSION``
-  The minor version of GTK2
+  The minor version of GTK found.
 ``GTK2_PATCH_VERSION``
-  The patch version of GTK2
+  The patch version of GTK found.
+``GTK2_INCLUDE_DIRS``
+  Include directories containing headers needed to use GTK.
+``GTK2_LIBRARIES``
+  Libraries needed to link against to use GTK.
+``GTK2_TARGETS``
+  .. versionadded:: 3.5
 
-.. versionadded:: 3.5
-  When ``GTK2_USE_IMPORTED_TARGETS`` is set to ``TRUE``, ``GTK2_LIBRARIES``
-  will list imported targets instead of library paths.
+  A list of all defined imported targets.
+``GTK2_DEFINITIONS``
+  Additional compiler flags needed to use GTK.
 
 Input Variables
 ^^^^^^^^^^^^^^^
 
-Optional variables you can define prior to calling this module:
+This module accepts the following optional variables before calling the
+``find_package(GTK2)``:
 
 ``GTK2_DEBUG``
-  Enables verbose debugging of the module
+  Boolean variable that enables verbose debugging output of this module.
+
 ``GTK2_ADDITIONAL_SUFFIXES``
-  Allows defining additional directories to search for include files
+  A list of additional path suffixes to search for include files.
+
+``GTK2_USE_IMPORTED_TARGETS``
+  .. versionadded:: 3.5
 
-Example Usage
-^^^^^^^^^^^^^
+  When this variable is set to boolean true, ``GTK2_LIBRARIES`` variable will
+  contain a list imported targets instead of library paths.
 
-Call :command:`find_package` once.  Here are some examples to pick from:
+Examples
+^^^^^^^^
+
+Examples: Finding GTK version 2
+"""""""""""""""""""""""""""""""
+
+Call :command:`find_package` once.  Here are some examples to pick from.
 
 Require GTK 2.6 or later:
 
 .. code-block:: cmake
 
-  find_package(GTK2 2.6 REQUIRED gtk)
+  find_package(GTK2 2.6 REQUIRED COMPONENTS gtk)
 
-Require GTK 2.10 or later and Glade:
+Require GTK 2.10 or later and its Glade component:
 
 .. code-block:: cmake
 
-  find_package(GTK2 2.10 REQUIRED gtk glade)
+  find_package(GTK2 2.10 REQUIRED COMPONENTS gtk glade)
 
 Search for GTK/GTKMM 2.8 or later:
 
@@ -95,15 +157,32 @@ Search for GTK/GTKMM 2.8 or later:
 
   find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
 
-Use the results:
+Finding GTK 2 and linking it to a project target:
 
 .. code-block:: cmake
 
-  if(GTK2_FOUND)
-    include_directories(${GTK2_INCLUDE_DIRS})
-    add_executable(mygui mygui.cc)
-    target_link_libraries(mygui ${GTK2_LIBRARIES})
-  endif()
+  find_package(GTK2)
+  add_executable(mygui mygui.cc)
+  target_link_libraries(mygui PRIVATE GTK2::gtk)
+
+Examples: Finding GTK version 3 or later
+""""""""""""""""""""""""""""""""""""""""
+
+Finding GTK 3 with :module:`FindPkgConfig` instead of this module:
+
+.. code-block:: cmake
+
+  find_package(PkgConfig REQUIRED)
+  pkg_check_modules(GTK3 REQUIRED IMPORTED_TARGET gtk+-3.0>=3.14)
+  target_link_libraries(example PRIVATE PkgConfig::GTK3)
+
+Or similarly to find GTK 4:
+
+.. code-block:: cmake
+
+  find_package(PkgConfig REQUIRED)
+  pkg_check_modules(GTK4 REQUIRED IMPORTED_TARGET gtk4>=4.14)
+  target_link_libraries(example PRIVATE PkgConfig::GTK4)
 #]=======================================================================]
 
 # Version 1.6 (CMake 3.0)