diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/find_package.rst | 40 | ||||
| -rw-r--r-- | Help/command/try_compile.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 3 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 10 | ||||
| -rw-r--r-- | Help/policy/CMP0136.rst | 50 | ||||
| -rw-r--r-- | Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst | 10 | ||||
| -rw-r--r-- | Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt | 20 | ||||
| -rw-r--r-- | Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst | 34 | ||||
| -rw-r--r-- | Help/release/dev/FetchContent_find_package_integration.rst | 17 | ||||
| -rw-r--r-- | Help/release/dev/ctest-output-truncation.rst | 11 | ||||
| -rw-r--r-- | Help/release/dev/watcom-runtime-library.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/werror-property.rst | 8 | ||||
| -rw-r--r-- | Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst | 9 | ||||
| -rw-r--r-- | Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst | 27 | ||||
| -rw-r--r-- | Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst | 36 |
17 files changed, 275 insertions, 11 deletions
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 0d8a166..8ce6529 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -17,7 +17,7 @@ and load its package-specific details. Search Modes ^^^^^^^^^^^^ -The command has two very distinct ways of conducting the search: +The command has a few modes by which it searches for packages: **Module mode** In this mode, CMake searches for a file called ``Find<PackageName>.cmake``, @@ -60,7 +60,17 @@ The command has two very distinct ways of conducting the search: Config mode is supported by both the :ref:`basic <Basic Signature>` and :ref:`full <Full Signature>` command signatures. -The command arguments determine which of the above modes is used. When the +**FetchContent redirection mode** + .. versionadded:: 3.24 + A call to ``find_package()`` can be redirected internally to a package + provided by the :module:`FetchContent` module. To the caller, the behavior + will appear similar to Config mode, except that the search logic is + by-passed and the component information is not used. See + :command:`FetchContent_Declare` and :command:`FetchContent_MakeAvailable` + for further details. + +When not redirected to a package provided by :module:`FetchContent`, the +command arguments determine whether Module or Config mode is used. When the `basic signature`_ is used, the command searches in Module mode first. If the package is not found, the search falls back to Config mode. A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable @@ -70,7 +80,7 @@ forced to use only Module mode with a ``MODULE`` keyword. If the `full signature`_ is used, the command only searches in Config mode. Where possible, user code should generally look for packages using the -`basic signature`_, since that allows the package to be found with either mode. +`basic signature`_, since that allows the package to be found with any mode. Project maintainers wishing to provide a config package should understand the bigger picture, as explained in :ref:`Full Signature` and all subsequent sections on this page. @@ -203,9 +213,12 @@ proceeds at once with Config mode search. Config mode search attempts to locate a configuration file provided by the package to be found. A cache entry called ``<PackageName>_DIR`` is created to -hold the directory containing the file. By default the command -searches for a package with the name ``<PackageName>``. If the ``NAMES`` option -is given the names following it are used instead of ``<PackageName>``. +hold the directory containing the file. By default, the command searches for +a package with the name ``<PackageName>``. If the ``NAMES`` option is given, +the names following it are used instead of ``<PackageName>``. The names are +also considered when determining whether to redirect the call to a package +provided by :module:`FetchContent`. + The command searches for a file called ``<PackageName>Config.cmake`` or ``<lowercasePackageName>-config.cmake`` for each name specified. A replacement set of possible configuration file names may be given @@ -242,6 +255,14 @@ Config Mode Search Procedure whether the :ref:`full <full signature>` or :ref:`basic <basic signature>` signature was given. +.. versionadded:: 3.24 + All calls to ``find_package()`` (even in Module mode) first look for a config + package file in the :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` directory. + The :module:`FetchContent` module, or even the project itself, may write files + to that location to redirect ``find_package()`` calls to content already + provided by the project. If no config package file is found in that location, + the search proceeds with the logic described below. + CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a configuration file. The tables below show the directories searched. @@ -420,7 +441,8 @@ to resolve symbolic links and store the real path to the file. Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED: * Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable - to ``TRUE`` disables the package. + to ``TRUE`` disables the package. This also disables redirection to a + package provided by :module:`FetchContent`. * Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable to ``TRUE`` makes the package REQUIRED. @@ -443,8 +465,8 @@ version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the ``EXACT`` option is given, only a version of the package claiming an exact match of the requested version may be found. CMake does not establish any convention for the meaning of version numbers. Package version -numbers are checked by "version" files provided by the packages -themselves. For a candidate package configuration file +numbers are checked by "version" files provided by the packages themselves +or by :module:`FetchContent`. For a candidate package configuration file ``<config-file>.cmake`` the corresponding version file is located next to it and named either ``<config-file>-version.cmake`` or ``<config-file>Version.cmake``. If no such version file is available diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 08f8d5b..4b2a631 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -150,6 +150,7 @@ Other Behavior Settings * :variable:`CMAKE_LINK_SEARCH_END_STATIC` * :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` * :variable:`CMAKE_POSITION_INDEPENDENT_CODE` + * :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` If :policy:`CMP0056` is set to ``NEW``, then :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index b3091fa..259cebb 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -58,6 +58,7 @@ Policies Introduced by CMake 3.24 .. toctree:: :maxdepth: 1 + CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136> CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135> CMP0134: Fallback to \"HOST\" Windows registry view when \"TARGET\" view is not usable. </policy/CMP0134> CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133> diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 8c2f8c4..20b62c5 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -171,6 +171,7 @@ Properties on Targets /prop_tgt/COMPILE_PDB_NAME_CONFIG /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG + /prop_tgt/COMPILE_WARNING_AS_ERROR /prop_tgt/CONFIG_OUTPUT_NAME /prop_tgt/CONFIG_POSTFIX /prop_tgt/CROSSCOMPILING_EMULATOR @@ -423,6 +424,7 @@ Properties on Targets /prop_tgt/VS_WINRT_COMPONENT /prop_tgt/VS_WINRT_EXTENSIONS /prop_tgt/VS_WINRT_REFERENCES + /prop_tgt/WATCOM_RUNTIME_LIBRARY /prop_tgt/WIN32_EXECUTABLE /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS /prop_tgt/XCODE_ATTRIBUTE_an-attribute diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 70dfc35..80160b6 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -59,6 +59,7 @@ Variables that Provide Information /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES /variable/CMAKE_FIND_DEBUG_MODE /variable/CMAKE_FIND_PACKAGE_NAME + /variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR @@ -400,6 +401,7 @@ Variables that Control the Build /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_COMPILE_WARNING_AS_ERROR /variable/CMAKE_CONFIG_POSTFIX /variable/CMAKE_CROSS_CONFIGS /variable/CMAKE_CTEST_ARGUMENTS @@ -520,6 +522,7 @@ Variables that Control the Build /variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES /variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES /variable/CMAKE_VS_WINRT_BY_DEFAULT + /variable/CMAKE_WATCOM_RUNTIME_LIBRARY /variable/CMAKE_WIN32_EXECUTABLE /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 82e27b8..06f0d4e 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -357,14 +357,20 @@ See `Build and Test Mode`_. Specify the directory in which to look for tests. ``--test-output-size-passed <size>`` + .. versionadded:: 3.4 + Limit the output for passed tests to ``<size>`` bytes. ``--test-output-size-failed <size>`` + .. versionadded:: 3.4 + Limit the output for failed tests to ``<size>`` bytes. ``--test-output-truncation <mode>`` - Truncate 'tail' (default), 'middle' or 'head' of test output once maximum - output size is reached. + .. versionadded:: 3.24 + + Truncate ``tail`` (default), ``middle`` or ``head`` of test output once + maximum output size is reached. ``--overwrite`` Overwrite CTest configuration option. diff --git a/Help/policy/CMP0136.rst b/Help/policy/CMP0136.rst new file mode 100644 index 0000000..5414278 --- /dev/null +++ b/Help/policy/CMP0136.rst @@ -0,0 +1,50 @@ +CMP0136 +------- + +.. versionadded:: 3.24 + +Watcom runtime library flags are selected by an abstraction. + +Compilers targeting the Watcom ABI have flags to select the Watcom runtime +library. + +In CMake 3.23 and below, Watcom runtime library selection flags are added to +the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake +automatically. This allows users to edit their cache entries to adjust the +flags. However, the presence of such default flags is problematic for +projects that want to choose a different runtime library programmatically. +In particular, it requires string editing of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the +CMake builtin defaults so they can be replaced. + +CMake 3.24 and above prefer to leave the Watcom runtime library selection flags +out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead +offer a first-class abstraction. The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` +variable and :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property may be set to +select the Watcom runtime library. If they are not set then CMake uses the +default value ``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other +platforms, which is equivalent to the original flags. + +This policy provides compatibility with projects that have not been updated +to be aware of the abstraction. The policy setting takes effect as of the +first :command:`project` or :command:`enable_language` command that enables +a language whose compiler targets the Watcom ABI. + +.. note:: + + Once the policy has taken effect at the top of a project, that choice + must be used throughout the tree. In projects that have nested projects + in subdirectories, be sure to convert everything together. + +The ``OLD`` behavior for this policy is to place Watcom runtime library +flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache +entries and ignore the :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` abstraction. +The ``NEW`` behavior for this policy is to *not* place Watcom runtime +library flags in the default cache entries and use the abstraction instead. + +This policy was introduced in CMake version 3.24. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst b/Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst new file mode 100644 index 0000000..86a0f7f --- /dev/null +++ b/Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst @@ -0,0 +1,10 @@ +COMPILE_WARNING_AS_ERROR +------------------------ + +.. versionadded:: 3.24 + +Specify whether to treat warnings on compile as errors. +If enabled, adds a flag to treat warnings on compile as errors. + +This property is initialized by the value of the variable +:variable:`CMAKE_COMPILE_WARNING_AS_ERROR` if it is set when a target is created. diff --git a/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt new file mode 100644 index 0000000..cdf99d0 --- /dev/null +++ b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt @@ -0,0 +1,20 @@ +``SingleThreaded`` + Compile without additional flags to use a single-threaded + statically-linked runtime library. +``SingleThreadedDLL`` + Compile with ``-br`` or equivalent flag(s) to use a single-threaded + dynamically-linked runtime library. This is not available for Linux + targets. +``MultiThreaded`` + Compile with ``-bm`` or equivalent flag(s) to use a multi-threaded + statically-linked runtime library. +``MultiThreadedDLL`` + Compile with ``-bm -br`` or equivalent flag(s) to use a multi-threaded + dynamically-linked runtime library. This is not available for Linux + targets. + +The value is ignored on non-Watcom compilers but an unsupported value will +be rejected as an error when using a compiler targeting the Watcom ABI. + +The value may also be the empty string (``""``) in which case no runtime +library selection flag will be added explicitly by CMake. diff --git a/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..3752862 --- /dev/null +++ b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst @@ -0,0 +1,34 @@ +WATCOM_RUNTIME_LIBRARY +---------------------- + +.. versionadded:: 3.24 + +Select the Watcom runtime library for use by compilers targeting the Watcom ABI. + +The allowed values are: + +.. include:: WATCOM_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. + +For example, the code: + +.. code-block:: cmake + + add_executable(foo foo.c) + set_property(TARGET foo PROPERTY + WATCOM_RUNTIME_LIBRARY "MultiThreaded") + +selects for the target ``foo`` a multi-threaded statically-linked runtime +library. + +If this property is not set then CMake uses the default value +``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other +platforms to select a Watcom runtime library. + +.. note:: + + This property has effect only when policy :policy:`CMP0136` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the Watcom ABI. diff --git a/Help/release/dev/FetchContent_find_package_integration.rst b/Help/release/dev/FetchContent_find_package_integration.rst new file mode 100644 index 0000000..4ca7afc --- /dev/null +++ b/Help/release/dev/FetchContent_find_package_integration.rst @@ -0,0 +1,17 @@ +FetchContent_find_package_integration +------------------------------------- + +* Integration has been added between the :module:`FetchContent` module and the + :command:`find_package` command, enabling the following new capabilities: + + * :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency + by calling :command:`find_package` first. A new + :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether + this is done by default for all dependencies, is opt-in per dependency, + or is disabled entirely. + + * :command:`find_package` can be re-routed to call + :command:`FetchContent_MakeAvailable` instead. A new read-only + :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a + directory where config package files can be located to facilitate these + re-routed calls. diff --git a/Help/release/dev/ctest-output-truncation.rst b/Help/release/dev/ctest-output-truncation.rst new file mode 100644 index 0000000..85fb37c --- /dev/null +++ b/Help/release/dev/ctest-output-truncation.rst @@ -0,0 +1,11 @@ +ctest-output-truncation +----------------------- + +* :manual:`ctest(1)` gained a ``--test-output-truncation`` option (and + corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable) to + specify the truncation mode once the maximum test output size has been + reached. Possible values are ``tail`` (default), ``middle`` or ``head``. +* :manual:`cmake-presets(7)` files now support schema version ``5``. +* :manual:`cmake-presets(7)` files gained support for specifying a + ``testOutputTruncation`` field in test presets, which specifies the truncation + mode once the maximum test output size has been reached. diff --git a/Help/release/dev/watcom-runtime-library.rst b/Help/release/dev/watcom-runtime-library.rst new file mode 100644 index 0000000..3a07b32 --- /dev/null +++ b/Help/release/dev/watcom-runtime-library.rst @@ -0,0 +1,7 @@ +watcom-runtime-library +---------------------- + +* The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and + :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to + select the runtime library used by compilers targeting the Watcom ABI. + See policy :policy:`CMP0136`. diff --git a/Help/release/dev/werror-property.rst b/Help/release/dev/werror-property.rst new file mode 100644 index 0000000..c337df7 --- /dev/null +++ b/Help/release/dev/werror-property.rst @@ -0,0 +1,8 @@ +werror-property +--------------- + +* Added the Target Property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and the + Variable :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` which initializes the + Target Property. If :prop_tgt:`COMPILE_WARNING_AS_ERROR` is true, it expands + to a different flag depending on the compiler such that any warnings at + compile will be treated as errors. diff --git a/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst b/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst new file mode 100644 index 0000000..56dc6a6 --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst @@ -0,0 +1,9 @@ +CMAKE_COMPILE_WARNING_AS_ERROR +------------------------------ + +.. versionadded:: 3.24 + +Specify whether to treat warnings on compile as errors. + +This variable is used to initialize the +:prop_tgt:`COMPILE_WARNING_AS_ERROR` property on all the targets. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst new file mode 100644 index 0000000..fa414e4 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst @@ -0,0 +1,27 @@ +CMAKE_FIND_PACKAGE_REDIRECTS_DIR +-------------------------------- + +.. versionadded:: 3.24 + +This read-only variable specifies a directory that the :command:`find_package` +command will check first before searching anywhere else for a module or config +package file. A config package file in this directory will always be found in +preference to any other Find module file or config package file. + +The primary purpose of this variable is to facilitate integration between +:command:`find_package` and :command:`FetchContent_MakeAvailable`. The latter +command may create files in the ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` directory +when it populates a dependency. This allows subsequent calls to +:command:`find_package` for the same dependency to re-use the populated +contents instead of trying to satisfy the dependency from somewhere external +to the build. Projects may also want to write files into this directory in +some situations (see :ref:`FetchContent-find_package-integration` for examples). + +The directory that ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` points to will always +be erased and recreated empty at the start of every CMake run. Any files +written into this directory during the CMake run will be lost the next time +CMake configures the project. + +``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` is only set in CMake project mode. +It is not set when CMake is run in script mode +(i.e. :manual:`cmake -P ... <cmake(1)>`). diff --git a/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..feb2a60 --- /dev/null +++ b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst @@ -0,0 +1,36 @@ +CMAKE_WATCOM_RUNTIME_LIBRARY +---------------------------- + +.. versionadded:: 3.24 + +Select the Watcom runtime library for use by compilers targeting the Watcom ABI. +This variable is used to initialize the :prop_tgt:`WATCOM_RUNTIME_LIBRARY` +property on all targets as they are created. It is also propagated by +calls to the :command:`try_compile` command into the test project. + +The allowed values are: + +.. include:: ../prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. + +For example, the code: + +.. code-block:: cmake + + set(CMAKE_WATCOM_RUNTIME_LIBRARY "MultiThreaded") + +selects for all following targets a multi-threaded statically-linked runtime +library. + +If this variable is not set then the :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target +property will not be set automatically. If that property is not set then +CMake uses the default value ``MultiThreadedDLL`` on Windows and +``SingleThreaded`` on other platforms to select a Watcom runtime library. + +.. note:: + + This variable has effect only when policy :policy:`CMP0136` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the Watcom ABI. |