From fe9fd66a8e2434b908cd326482e55c0246514b17 Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 30 Sep 2025 13:18:08 -0400 Subject: [PATCH 1/5] Help: Improve CPack/WiX documentation markup --- Help/cpack_gen/wix.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index 0c28ec6349..fce5c38540 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -492,7 +492,8 @@ Windows using WiX. .. versionadded:: 4.2 - If this variable is set to true one `.cab` file per component is created. - The default is to create a single `.cab` file for all files in the installer. + If this variable is set to true one ``.cab`` file per component is created. + The default is to create a single ``.cab`` file for all files in the installer. - WiX creates `.cab` files in parallel so multiple `.cab` files may be desirable for faster packaging. + WiX creates ``.cab`` files in parallel so multiple ``.cab`` files may be + desirable for faster packaging. From f98b4eecf60e6c2f0176cac9eed78feac277acfd Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 30 Sep 2025 13:28:24 -0400 Subject: [PATCH 2/5] Help: Document generators supporting CMAKE_INTERMEDIATE_DIR_STRATEGY Move this information from the release note to the actual docs. --- Help/release/dev/short-object-names.rst | 9 +-------- Help/variable/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst | 6 ++++++ 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/Help/release/dev/short-object-names.rst b/Help/release/dev/short-object-names.rst index d6c9139438..3dcff84ad1 100644 --- a/Help/release/dev/short-object-names.rst +++ b/Help/release/dev/short-object-names.rst @@ -4,14 +4,7 @@ short-object-names * There is now the :variable:`CMAKE_INTERMEDIATE_DIR_STRATEGY` variable (and associated environment variable :envvar:`CMAKE_INTERMEDIATE_DIR_STRATEGY`) that may be used to change the strategy used to name intermediate - directories used for object files (and other associated target metadata). It - is supported for the following generators: - - - :ref:`Ninja Generators` - - :ref:`Makefile Generators` - - :ref:`Visual Studio Generators` - - Note that the strategy implementation may differ between generators. + directories used for object files (and other associated target metadata). * There is now the :variable:`CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY` variable (and associated environment variable diff --git a/Help/variable/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst b/Help/variable/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst index a0b3a68ae2..1d26ffdba4 100644 --- a/Help/variable/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst +++ b/Help/variable/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst @@ -24,6 +24,12 @@ used. .. note:: This only works as a cache variable, not a locally-scoped variable. +This is supported by the following generators: + +- :ref:`Ninja Generators` +- :ref:`Makefile Generators` +- :ref:`Visual Studio Generators` + .. note:: Not all generators support all strategies and paths may differ between generators. From 09aded59f74a8d87bff78749c9c536775cb8d000 Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 30 Sep 2025 14:03:20 -0400 Subject: [PATCH 3/5] Help: Revise CMP0201 documentation using typical wording conventions --- Help/manual/cmake-policies.7.rst | 2 +- Help/policy/CMP0201.rst | 36 +++++++++++++------------------- Source/cmPolicies.h | 5 ++--- 3 files changed, 18 insertions(+), 25 deletions(-) diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index db2596ca9d..6473aa7b9b 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -100,7 +100,7 @@ Policies Introduced by CMake 4.2 CMP0203: _WINDLL is defined for shared libraries targeting the MSVC ABI. CMP0202: PDB file names always include their target's per-config POSTFIX. - CMP0201: The Python::NumPy target does not depend on the Python::Module target. + CMP0201: Python::NumPy does not depend on Python::Development.Module. CMP0200: Location and configuration selection for imported targets is more consistent. CMP0199: $ only matches the configuration of the consumed target. CMP0198: CMAKE_PARENT_LIST_FILE is not defined in CMakeLists.txt. diff --git a/Help/policy/CMP0201.rst b/Help/policy/CMP0201.rst index f098cdeb73..d2c5f2169c 100644 --- a/Help/policy/CMP0201.rst +++ b/Help/policy/CMP0201.rst @@ -3,32 +3,26 @@ CMP0201 .. versionadded:: 4.2 -The modules :module:`FindPython3`, :module:`FindPython2` and -:module:`FindPython` change the handling of the ``NumPy`` -component and, respectively, the definition of the ``Python3::NumPy``, -``Python2::NumPy`` and ``Python::NumPy`` targets. +``Python::NumPy`` does not depend on ``Python::Development.Module``. -For CMake 4.2 and above, the specification of the ``NumPy`` component does not -imply anymore the component ``Development.Module`` and the ``Python3::NumPy``, -``Python2::NumPy`` and ``Python::NumPy`` targets provided, respectively, by the -modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` -do not depend on the ``Python3::Development.Module``, -``Python2::Development.Module`` and ``Python::Development.Module`` targets. -For CMake 4.1 and below, the specification of the ``NumPy`` component imply the -component ``Development.Module`` and the ``Python3::NumPy``, ``Python2::NumPy`` -and ``Python::NumPy`` targets provided, respectively, by the modules -:module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` depend on -the ``Python3::Development.Module``, ``Python2::Development.Module`` and -``Python::Development.Module`` targets. - -The ``OLD`` behavior for this policy creates a dependency of the ``NumPy`` -target over the ``Development.Module`` target. The ``NEW`` behavior does not -create a dependency of the ``NumPy`` target over the ``Development.Module`` -target. +:module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython` provide +``Python{3,2,}::NumPy`` and ``Python{3,2,}::Development.Module`` targets when +the corresponding components are requested. +In CMake 4.1 and below, requesting the ``NumPy`` component implies the +``Development.Module`` component, and the provided ``Python{3,2,}::NumPy`` +targets depend on the provided ``Python{3,2,}::Development.Module`` targets. +This dependency is not necessary. +In CMake 4.2 and above, requesting the ``NumPy`` component does not imply the +``Development.Module`` component, and the provided ``Python{3,2,}::NumPy`` +targets do not depend on the provided ``Python{3,2,}::Development.Module`` +targets. This policy provides compatibility with projects that expect the legacy behavior. +The ``OLD`` behavior for this policy makes ``NumPy`` depend on +``Development.Module``. The ``NEW`` behavior for this policy does not. + .. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.2 .. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn .. include:: include/STANDARD_ADVICE.rst diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h index dc4c48acf7..425066120c 100644 --- a/Source/cmPolicies.h +++ b/Source/cmPolicies.h @@ -602,9 +602,8 @@ class cmMakefile; "consistent.", \ 4, 2, 0, WARN) \ SELECT(POLICY, CMP0201, \ - "The Python::NumPy target does not depend on the Python::Module " \ - "target.", \ - 4, 2, 0, WARN) \ + "Python::NumPy does not depend on Python::Development.Module.", 4, \ + 2, 0, WARN) \ SELECT(POLICY, CMP0202, \ "PDB file names always include their target's per-config POSTFIX.", \ 4, 2, 0, WARN) \ From 7aa81ae324d91c04715ba8892666b26be917348a Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 30 Sep 2025 14:25:49 -0400 Subject: [PATCH 4/5] Help: Simplify release notes for find module version variables Avoid repeating almost identical information for every module. Document the pattern of the change and refer the reader to individual modules for details. --- Help/release/dev/find-modules.rst | 134 +----------------------------- 1 file changed, 4 insertions(+), 130 deletions(-) diff --git a/Help/release/dev/find-modules.rst b/Help/release/dev/find-modules.rst index 42d81e219b..153c5c53bd 100644 --- a/Help/release/dev/find-modules.rst +++ b/Help/release/dev/find-modules.rst @@ -5,136 +5,10 @@ Find Modules are now deprecated in favor of ``_FOUND`` result variables, where appropriate. See documentation of each find module for details. -* The :module:`FindALSA` module now provides a ``ALSA_VERSION`` result - variable. The ``ALSA_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindArmadillo` module now provides an ``Armadillo_VERSION``, - and ``Armadillo_VERSION_NAME`` result variables. The - ``ARMADILLO_VERSION_STRING``, ``ARMADILLO_VERSION_MAJOR``, - ``ARMADILLO_VERSION_MINOR``, ``ARMADILLO_VERSION_PATCH``, and - ``ARMADILLO_VERSION_NAME`` result variables are deprecated. - -* The :module:`FindBZip2` module now provides a ``BZip2_VERSION`` result - variable. The ``BZIP2_VERSION`` result variable is deprecated. - -* The :module:`FindCups` module now provides a ``Cups_VERSION`` result - variable. The ``CUPS_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindDoxygen` module now provides a ``Doxygen_VERSION`` result - variable. The ``DOXYGEN_VERSION`` result variable is deprecated. - -* The :module:`FindEXPAT` module now provides a ``EXPAT_VERSION`` result - variable. The ``EXPAT_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindFreetype` module now provides a ``Freetype_VERSION`` result - variable. The ``FREETYPE_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindGettext` module now provides a ``Gettext_VERSION`` result - variable. The ``GETTEXT_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindGit` module now provides a ``Git_VERSION`` result - variable. The ``GIT_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindGnuplot` module now provides a ``Gnuplot_VERSION`` result - variable. The ``GNUPLOT_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindGnuTLS` module now provides a ``GnuTLS_VERSION`` result - variable. The ``GNUTLS_VERSION`` result variable is deprecated. - -* The :module:`FindHg` module now provides a ``Hg_VERSION`` result - variable. The ``HG_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindHSPELL` module now provides a ``HSPELL_VERSION`` result - variable. The ``HSPELL_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindIcotool` module now provides a ``Icotool_VERSION`` result - variable. The ``ICOTOOL_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindImageMagick` module now provides an ``ImageMagick_VERSION`` - result variable. The ``ImageMagick_VERSION_STRING`` result variable is - deprecated. - -* The :module:`FindJasper` module now provides a ``Jasper_VERSION`` result - variable. The ``JASPER_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindLibLZMA` module now provides a ``LibLZMA_VERSION`` result - variable. The ``LIBLZMA_VERSION`` result variable is deprecated. - -* The :module:`FindLibXml2` module now provides a ``LibXml2_VERSION`` result - variable. The ``LIBXML2_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindLibXslt` module now provides a ``LibXslt_VERSION`` result - variable. The ``LIBXSLT_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindLTTngUST` module now provides a ``LTTngUST_VERSION`` result - variable. The ``LTTNGUST_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindLua` module now provides ``Lua_VERSION``, - ``Lua_VERSION_MAJOR``, ``Lua_VERSION_MINOR``, and ``Lua_VERSION_PATCH`` - result variables. The ``LUA_VERSION_STRING``, ``LUA_VERSION_MAJOR``, - ``LUA_VERSION_MINOR``, and ``LUA_VERSION_PATCH`` result variables are - deprecated. The :module:`FindLua51` module now similarly provides a - ``Lua_VERSION`` instead of the now deprecated ``LUA_VERSION_STRING`` result - variable. - -* The :module:`FindOpenCL` module now provides an ``OpenCL_VERSION`` result - variable. The ``OpenCL_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindOpenSceneGraph` module now provides an - ``OpenSceneGraph_VERSION`` result variable. The ``OPENSCENEGRAPH_VERSION`` - result variable is deprecated. - -* The :module:`FindOpenSSL` module now provides an ``OpenSSL_VERSION`` result - variable. The ``OPENSSL_VERSION`` result variable is deprecated. - -* The :module:`FindPerl` module now provides a ``Perl_VERSION`` result - variable. The ``PERL_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindPerlLibs` module now provides a ``PerlLibs_VERSION`` - result variable. - -* The :module:`FindPkgConfig` module now provides a ``PkgConfig_VERSION`` - result variable. The ``PKG_CONFIG_VERSION_STRING`` result variable is - deprecated. - -* The :module:`FindPkgConfig` module's result variable ``PKG_CONFIG_FOUND`` - is deprecated in favor of ``PkgConfig_FOUND``, which is available since - CMake 3.3 and has the same value. - -* The :module:`FindPNG` module now provides a ``PNG_VERSION`` result - variable. The ``PNG_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindPostgreSQL` module now provides a ``PostgreSQL_VERSION`` - result variable. The ``PostgreSQL_VERSION_STRING`` result variable is - deprecated. - -* The :module:`FindQt3` module now provides a ``Qt3_VERSION`` result - variable. The ``QT_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindSDL_gfx`, :module:`FindSDL_image`, :module:`FindSDL_mixer`, - :module:`FindSDL_net`, :module:`FindSDL_sound`, and :module:`FindSDL_ttf` - modules now provide their respective ``_VERSION`` result - variables. Previous ``_VERSION_STRING`` result variables - are deprecated. - -* The :module:`FindSquish` module now provides a ``Squish_VERSION`` result - variable. The ``SQUISH_VERSION``, ``SQUISH_VERSION_MAJOR``, - ``SQUISH_VERSION_MINOR``, and ``SQUISH_VERSION_PATCH`` result variables - are deprecated. - -* The :module:`FindSubversion` module now provides a ``Subversion_VERSION`` - result variable. The ``Subversion_VERSION_SVN`` result variable is - deprecated. - -* The :module:`FindTclsh` module now provides a ``Tclsh_VERSION`` result - variable. The ``TCLSH_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindTIFF` module now provides a ``TIFF_VERSION`` result - variable. The ``TIFF_VERSION_STRING`` result variable is deprecated. - -* The :module:`FindwxWidgets` module now provides a ``wxWidgets_VERSION`` - result variable. The ``wxWidgets_VERSION_STRING`` result variable is - deprecated. +* Nearly all find modules now provide a ``_VERSION`` result + variable matching the casing of its module name. Existing variants such as + ``_VERSION_STRING`` and uppercased ``_VERSION`` + are deprecated. See documentation of each find module for details. * The :module:`FindwxWidgets` module's result variable ``wxWidgets_USE_FILE`` is now deprecated in favor of including the From 6babe38916cf763f9920d1aa57d5d63e3804fcde Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 30 Sep 2025 15:35:25 -0400 Subject: [PATCH 5/5] Help: Fix cmake_language(TRACE) command anchor --- Help/command/cmake_language.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 61b2907678..e3a30fa117 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -536,8 +536,6 @@ Terminating Scripts above 125 specially. Therefore, it is advisable to only specify an ```` in the range 0 to 125. -.. _trace: - Trace Control ^^^^^^^^^^^^^ @@ -546,6 +544,9 @@ Trace Control .. signature:: cmake_language(TRACE ON [EXPAND]) cmake_language(TRACE OFF) + :target: + TRACE + TRACE-OFF The TRACE subcommand controls runtime tracing of executed CMake commands and macros within the current process. When enabled, trace output is written