From e211e8850127f73308e6f04114012c5dc1b054bc Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Fri, 8 Aug 2025 22:57:09 +0200 Subject: [PATCH] FindwxWidgets: Update documentation - Module documentation synced with other similar find modules. - Added intro code block showing how to use this module. - Added common sections to describe variables, imported targets moved to the top. - Added examples section and highlighting the imported target usage. --- Modules/FindwxWidgets.cmake | 312 +++++++++++++++++++++++++----------- Modules/UsewxWidgets.cmake | 56 +++++-- 2 files changed, 255 insertions(+), 113 deletions(-) diff --git a/Modules/FindwxWidgets.cmake b/Modules/FindwxWidgets.cmake index fa2ad7b896..ddcbdf6ba8 100644 --- a/Modules/FindwxWidgets.cmake +++ b/Modules/FindwxWidgets.cmake @@ -5,133 +5,251 @@ FindwxWidgets ------------- -Find a wxWidgets (a.k.a., wxWindows) installation. +Finds a wxWidgets installation and provides usage requirements for usage in +projects: -This module finds if wxWidgets is installed and selects a default -configuration to use. wxWidgets is a modular library. To specify the -modules that you will use, you need to name them as components to the -package: +.. code-block:: cmake -find_package(wxWidgets COMPONENTS core base ... OPTIONAL_COMPONENTS net ...) + find_package(wxWidgets [] [COMPONENTS ...] [...]) + +wxWidgets (formerly known as wxWindows) is a widget toolkit and tools +library for creating graphical user interfaces (GUIs) for cross-platform +applications. .. versionadded:: 3.4 - Support for :command:`find_package` version argument; ``webview`` component. + Support for :command:`find_package` version argument. .. versionadded:: 3.14 ``OPTIONAL_COMPONENTS`` support. -There are two search branches: a windows style and a unix style. For -windows, the following variables are searched for and set to defaults -in case of multiple choices. Change them if the defaults are not -desired (i.e., these are the only variables you should change to -select a configuration): +Components +^^^^^^^^^^ -:: - - wxWidgets_ROOT_DIR - Base wxWidgets directory - (e.g., C:/wxWidgets-3.2.0). - wxWidgets_LIB_DIR - Path to wxWidgets libraries - (e.g., C:/wxWidgets-3.2.0/lib/vc_x64_lib). - wxWidgets_CONFIGURATION - Configuration to use - (e.g., msw, mswd, mswu, mswunivud, etc.) - wxWidgets_EXCLUDE_COMMON_LIBRARIES - - Set to TRUE to exclude linking of - commonly required libs (e.g., png tiff - jpeg zlib regex expat scintilla lexilla). - - - -For unix style it uses the wx-config utility. You can select between -debug/release, unicode/ansi, universal/non-universal, and -static/shared in the QtDialog or ccmake interfaces by turning ON/OFF -the following variables: - -:: - - wxWidgets_USE_DEBUG - wxWidgets_USE_UNICODE - wxWidgets_USE_UNIVERSAL - wxWidgets_USE_STATIC - -There is also a wxWidgets_CONFIG_OPTIONS variable for all other -options that need to be passed to the wx-config utility. For example, -to use the base toolkit found in the /usr/local path, set the variable -(before calling the FIND_PACKAGE command) as such: +wxWidgets is a modular library. This module supports components to specify +the modules to use. Components can be specified with the +:command:`find_package` command: .. code-block:: cmake - set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr) + find_package( + wxWidgets + [COMPONENTS ...] + [OPTIONAL_COMPONENTS ...] + ) +Supported components include: +``base`` + Finds the library that provides mandatory classes that any wxWidgets code + depends on. This component is always required for applications + implementing wxWidgets. -The following are set after the configuration is done for both windows -and unix style: +``core`` + Finds the library that provides basic GUI classes such as GDI classes or + controls. -:: +``gl`` + Finds the OpenGL support. - wxWidgets_FOUND - Set to TRUE if wxWidgets was found. - wxWidgets_INCLUDE_DIRS - Include directories for WIN32 - i.e., where to find "wx/wx.h" and - "wx/setup.h"; possibly empty for unices. - wxWidgets_LIBRARIES - Path to the wxWidgets libraries. - wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for - rpath on UNIX. Typically an empty string - in WIN32 environment. - wxWidgets_DEFINITIONS - Contains defines required to compile/link - against WX, e.g. WXUSINGDLL - wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link - against WX debug builds, e.g. __WXDEBUG__ - wxWidgets_CXX_FLAGS - Include dirs and compiler flags for - unices, empty on WIN32. Essentially - "`wx-config --cxxflags`". - wxWidgets_USE_FILE - Convenience include file. +``mono`` + Finds the wxWidgets monolithic library. -.. versionadded:: 3.11 - The following environment variables can be used as hints: ``WX_CONFIG``, - ``WXRC_CMD``. +``aui`` + Finds the Advanced User Interface docking library. +``net`` + Finds the library that provides network access. -Sample usage: +``webview`` + .. versionadded:: 3.4 -.. code-block:: cmake + Finds the library that provides rendering of web documents + (HTML/CSS/JavaScript). - # Note that for MinGW users the order of libs is important! - find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net) - if(wxWidgets_FOUND) - include(${wxWidgets_USE_FILE}) - # and for each of your dependent executable/library targets: - target_link_libraries( ${wxWidgets_LIBRARIES}) - endif() +For a full list of supported wxWidgets components, refer to the upstream +documentation. - - -If wxWidgets is required (i.e., not an optional part): - -.. code-block:: cmake - - find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net) - include(${wxWidgets_USE_FILE}) - # and for each of your dependent executable/library targets: - target_link_libraries( ${wxWidgets_LIBRARIES}) +If no components are specified, this module by default searches for ``core`` +and ``base`` components. Imported Targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.27 - -This module defines the following :prop_tgt:`IMPORTED` targets: +This module provides the following :ref:`Imported Targets`: ``wxWidgets::wxWidgets`` - An interface library providing usage requirements for the found components. -#]=======================================================================] + .. versionadded:: 3.27 -# -# FIXME: check this and provide a correct sample usage... -# Remember to connect back to the upper text. -# Sample usage with monolithic wx build: -# -# find_package(wxWidgets COMPONENTS mono) -# ... + An interface imported target encapsulating the wxWidgets usage requirements + for the found components, available if wxWidgets is found. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``wxWidgets_FOUND`` + Boolean indicating whether (the requested version of) wxWidgets and all + its requested components are found. + +``wxWidgets_VERSION_STRING`` + .. versionadded:: 3.4 + + The version of the wxWidgets found. + +``wxWidgets_INCLUDE_DIRS`` + Include directories for WIN32, i.e., where to find ```` and + ````; possibly empty for Unix-like systems. + +``wxWidgets_LIBRARIES`` + Path to the wxWidgets libraries. + +``wxWidgets_LIBRARY_DIRS`` + Compile time link dirs, useful for setting ``rpath`` on Unix-like systems. + Typically an empty string in WIN32 environment. + +``wxWidgets_DEFINITIONS`` + Contains compile definitions required to compile/link against WX, e.g. + ``WXUSINGDLL``. + +``wxWidgets_DEFINITIONS_DEBUG`` + Contains compile definitions required to compile/link against WX debug builds, + e.g. ``__WXDEBUG__``. + +``wxWidgets_CXX_FLAGS`` + Include directories and compiler flags for Unix-like systems, empty on + Windows. Essentially the output of ``wx-config --cxxflags``. + +``wxWidgets_USE_FILE`` + Name of the CMake module for using wxWidgets in current directory. For + usage details refer to the :module:`UsewxWidgets` module. + +Hints +^^^^^ + +This module accepts the following variables before calling +``find_package(wxWidgets)``: + +``WX_CONFIG`` + .. versionadded:: 3.11 + + Environment variable to manually specify the name of the wxWidgets library + configuration provider executable that will be searched besides the default + name ``wx-config``. + +``WXRC_CMD`` + .. versionadded:: 3.11 + + Environment variable to manually specify the name of the wxWidgets resource + file compiler executable that will be searched besides the default name + ``wxrc``. + +There are two search branches: a Windows style and a Unix style. For +Windows, the following variables are searched for and set to defaults +in case of multiple choices. Change them if the defaults are not +desired (i.e., these are the only variables that should be changed to +select a configuration): + +``wxWidgets_ROOT_DIR`` + Base wxWidgets directory (e.g., ``C:/wxWidgets-3.2.0``). + +``wxWidgets_LIB_DIR`` + Path to wxWidgets libraries (e.g., ``C:/wxWidgets-3.2.0/lib/vc_x64_lib``). + +``wxWidgets_CONFIGURATION`` + Configuration to use (e.g., msw, mswd, mswu, mswunivud, etc.) + +``wxWidgets_EXCLUDE_COMMON_LIBRARIES`` + Set to TRUE to exclude linking of commonly required libs (e.g., png, tiff, + jpeg, zlib, regex, expat, scintilla, lexilla, etc.). + +For Unix style this module uses the ``wx-config`` utility. Selecting +between debug/release, unicode/ansi, universal/non-universal, and +static/shared is possible in the QtDialog or ccmake interfaces by turning +ON/OFF the following variables: + +``wxWidgets_USE_DEBUG`` + If enabled, the wxWidgets debug build will be searched. + +``wxWidgets_USE_UNICODE`` + If enabled, the wxWidgets unicode build will be searched. + +``wxWidgets_USE_UNIVERSAL`` + If enabled, the wxWidgets universal build will be searched. + +``wxWidgets_USE_STATIC`` + If enabled, static wxWidgets libraries will be linked. + +``wxWidgets_CONFIG_OPTIONS`` + This variable can be used for all other options that need to be passed to + the wx-config utility. For example, to use the base toolkit found on the + system at ``/usr`` install prefix, set the variable (before calling the + :command:`find_package` command) as such: + + .. code-block:: cmake + + set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr) + +Examples +^^^^^^^^ + +Example: Finding wxWidgets +"""""""""""""""""""""""""" + +Finding wxWidgets and making it required (if wxWidgets is not found, +processing stops with an error message): + +.. code-block:: cmake + + find_package(wxWidgets REQUIRED) + +Example: Using Imported Target +"""""""""""""""""""""""""""""" + +Finding wxWidgets and using imported target in a project: + +.. code-block:: cmake + + find_package(wxWidgets) + target_link_libraries(example PRIVATE wxWidgets::wxWidgets) + +Example: Using Components +""""""""""""""""""""""""" + +Finding wxWidgets and specifying components: + +.. code-block:: cmake + + find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net) + target_link_libraries(example PRIVATE wxWidgets::wxWidgets) + +Example: Monolithic wxWidgets Build +""""""""""""""""""""""""""""""""""" + +Sample usage with monolithic wxWidgets build: + +.. code-block:: cmake + + find_package(wxWidgets COMPONENTS mono) + target_link_libraries(example PRIVATE wxWidgets::wxWidgets) + +Example: Using Variables +"""""""""""""""""""""""" + +Finding and using wxWidgets in CMake versions prior to 3.27, when the +imported target wasn't yet available: + +.. code-block:: cmake + + # Note that for MinGW users the order of libs is important. + find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net) + + if(wxWidgets_FOUND) + include(${wxWidgets_USE_FILE}) + # and for each of the project dependent executable/library targets: + target_link_libraries(example ${wxWidgets_LIBRARIES}) + endif() +#]=======================================================================] # NOTES # diff --git a/Modules/UsewxWidgets.cmake b/Modules/UsewxWidgets.cmake index 37510253c5..4dc34e368b 100644 --- a/Modules/UsewxWidgets.cmake +++ b/Modules/UsewxWidgets.cmake @@ -5,42 +5,66 @@ UsewxWidgets ------------ +This module serves as a convenience wrapper for using the wxWidgets +library (formerly known as wxWindows) and propagates its usage requirements, +such as library directories, include directories, and compiler flags, into +the current directory scope for use by targets. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(UsewxWidgets) + This module calls :command:`include_directories` and -:command:`link_directories`, sets compile definitions for the current directory -and appends some compile flags to use wxWidgets library after calling the -:module:`find_package(wxWidgets) `. +:command:`link_directories`, sets compile definitions for the current +directory and appends some compile flags to use wxWidgets library after +calling the :module:`find_package(wxWidgets) `. Examples ^^^^^^^^ -Include ``UsewxWidgets`` module in project's ``CMakeLists.txt``: +Include this module in a project after finding wxWidgets to configure its +usage requirements: .. code-block:: cmake + :caption: ``CMakeLists.txt`` # Note that for MinGW users the order of libraries is important. find_package(wxWidgets REQUIRED net gl core base) - # Above also sets the wxWidgets_USE_FILE variable that points to this module. - include(${wxWidgets_USE_FILE}) + add_library(example example.cxx) - # Link wxWidgets libraries for each dependent executable/library target. - target_link_libraries( ${wxWidgets_LIBRARIES}) + if(wxWidgets_FOUND) + # Above also sets the wxWidgets_USE_FILE variable that points to this module. + include(${wxWidgets_USE_FILE}) + + # Link wxWidgets libraries for each dependent executable/library target. + target_link_libraries(example PRIVATE ${wxWidgets_LIBRARIES}) + endif() As of CMake 3.27, a better approach is to link only the -:module:`wxWidgets::wxWidgets ` ``IMPORTED`` target to specific -targets that require it, rather than including this module. Imported targets -provide better control of the package usage properties, such as include -directories and compile flags, by applying them only to the targets they are -linked to, avoiding unnecessary propagation to all targets in the current -directory. +:module:`wxWidgets::wxWidgets ` imported target to specific +targets that require it, rather than including this module. Imported +targets provide better control of the package usage properties, such as +include directories and compile flags, by applying them only to the targets +they are linked to, avoiding unnecessary propagation to all targets in the +current directory. .. code-block:: cmake + :caption: ``CMakeLists.txt`` - # CMakeLists.txt find_package(wxWidgets) + add_library(example example.cxx) + # Link the imported target for each dependent executable/library target. - target_link_libraries( wxWidgets::wxWidgets) + target_link_libraries(example PRIVATE wxWidgets::wxWidgets) + +See Also +^^^^^^^^ + +* The :module:`FindwxWidgets` module to find wxWidgets. #]=======================================================================] # Author: Jan Woetzel