diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/file.rst | 4 | ||||
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 70 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-packages.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/module/FindXerces.rst | 1 | ||||
| -rw-r--r-- | Help/module/FindXercesC.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0056.rst | 32 | ||||
| -rw-r--r-- | Help/release/3.1.0.rst | 2 | ||||
| -rw-r--r-- | Help/release/dev/try_compile-link-flags.rst | 6 | ||||
| -rw-r--r-- | Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst | 2 |
11 files changed, 101 insertions, 22 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index 600464e..b0d4792 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -247,7 +247,9 @@ the ``<format>`` and ``UTC`` options. :: - file(GENERATE <options>...) + file(GENERATE OUTPUT output-file + <INPUT input-file|CONTENT content> + [CONDITION expression]) Generate an output file for each build configuration supported by the current :manual:`CMake Generator <cmake-generators(7)>`. Evaluate diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 672c9b7..3b9b921 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -720,7 +720,9 @@ by the :command:`find_package` command when invoked for ``<package>``. The primary task of a find module is to determine whether a package exists on the system, set the ``<package>_FOUND`` variable to reflect this and provide any variables, macros and imported targets required to -use the package. +use the package. A find module is useful in cases where an upstream +library does not provide a +:ref:`config file package <Config File Packages>`. The traditional approach is to use variables for everything, including libraries and executables: see the `Standard Variable Names`_ section @@ -728,13 +730,9 @@ below. This is what most of the existing find modules provided by CMake do. The more modern approach is to behave as much like -``<package>Config.cmake`` files as possible, by providing imported -targets. As well as matching how ``*Config.cmake`` files work, the -libraries, include directories and compile definitions are all set just -by using the target in a :command:`target_link_libraries` call. The -disadvantage is that ``*Config.cmake`` files of projects that use -imported targets from find modules may require more work to make sure -those imported targets that are in the link interface are available. +:ref:`config file packages <Config File Packages>` files as possible, by +providing :ref:`imported target <Imported targets>`. This has the advantage +of propagating :ref:`Target Usage Requirements` to consumers. In either case (or even when providing both variables and imported targets), find modules should provide backwards compatibility with old @@ -878,7 +876,10 @@ To prevent users being overwhelmed with settings to configure, try to keep as many options as possible out of the cache, leaving at least one option which can be used to disable use of the module, or locate a not-found library (e.g. ``Xxx_ROOT_DIR``). For the same reason, mark -most cache options as advanced. +most cache options as advanced. For packages which provide both debug +and release binaries, it is common to create cache variables with a +``_LIBRARY_<CONFIG>`` suffix, such as ``Foo_LIBRARY_RELEASE`` and +``Foo_LIBRARY_DEBUG``. While these are the standard variable names, you should provide backwards compatibility for any old names that were actually in use. @@ -945,16 +946,6 @@ licence notice block # (To distribute this file outside of CMake, substitute the full # License text for the above reference.) -If the module is new to CMake, you may want to provide a warning for -projects that do not require a high enough CMake version. - -.. code-block:: cmake - - if(CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 3.0.0) - message(AUTHOR_WARNING - "Your project should require at least CMake 3.0.0 to use FindFoo.cmake") - endif() - Now the actual libraries and so on have to be found. The code here will obviously vary from module to module (dealing with that, after all, is the point of find modules), but there tends to be a common pattern for libraries. @@ -1061,6 +1052,47 @@ not any of its dependencies. Instead, those dependencies should also be targets, and CMake should be told that they are dependencies of this target. CMake will then combine all the necessary information automatically. +The type of the :prop_tgt:`IMPORTED` target created in the +:command:`add_library` command can always be specified as ``UNKNOWN`` +type. This simplifies the code in cases where static or shared variants may +be found, and CMake will determine the type by inspecting the files. + +If the library is available with multiple configurations, the +:prop_tgt:`IMPORTED_CONFIGURATIONS` target property should also be +populated: + +.. code-block:: cmake + + if(Foo_FOUND) + if (NOT TARGET Foo::Foo) + add_library(Foo::Foo UNKNOWN IMPORTED) + endif() + if (Foo_LIBRARY_RELEASE) + set_property(TARGET Foo::Foo APPEND PROPERTY + IMPORTED_CONFIGURATIONS RELEASE + ) + set_target_properties(Foo::Foo PROPERTIES + IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}" + ) + endif() + if (Foo_LIBRARY_DEBUG) + set_property(TARGET Foo::Foo APPEND PROPERTY + IMPORTED_CONFIGURATIONS DEBUG + ) + set_target_properties(Foo::Foo PROPERTIES + IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}" + ) + endif() + set_target_properties(Foo::Foo PROPERTIES + INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}" + INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}" + ) + endif() + +The ``RELEASE`` variant should be listed first in the property +so that that variant is chosen if the user uses a configuration which is +not an exact match for any listed ``IMPORTED_CONFIGURATIONS``. + We should also provide some information about the package, such as where to download it. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 083ed7a..8337118 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -209,7 +209,7 @@ All Modules /module/FindWish /module/FindwxWidgets /module/FindwxWindows - /module/FindXerces + /module/FindXercesC /module/FindX11 /module/FindXMLRPC /module/FindZLIB diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 0d18fd7..fba1d61 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -76,6 +76,8 @@ By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``, the ``PackageName`` package will not be searched, and will always be ``NOTFOUND``. +.. _`Config File Packages`: + Config-file Packages -------------------- diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 742fd63..96f39e6 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -113,3 +113,4 @@ All Policies /policy/CMP0053 /policy/CMP0054 /policy/CMP0055 + /policy/CMP0056 diff --git a/Help/module/FindXerces.rst b/Help/module/FindXerces.rst deleted file mode 100644 index 166d8dd..0000000 --- a/Help/module/FindXerces.rst +++ /dev/null @@ -1 +0,0 @@ -.. cmake-module:: ../../Modules/FindXerces.cmake diff --git a/Help/module/FindXercesC.rst b/Help/module/FindXercesC.rst new file mode 100644 index 0000000..4818071 --- /dev/null +++ b/Help/module/FindXercesC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindXercesC.cmake diff --git a/Help/policy/CMP0056.rst b/Help/policy/CMP0056.rst new file mode 100644 index 0000000..3c75ff4 --- /dev/null +++ b/Help/policy/CMP0056.rst @@ -0,0 +1,32 @@ +CMP0056 +------- + +Honor link flags in :command:`try_compile` source-file signature. + +The :command:`try_compile` command source-file signature generates a +``CMakeLists.txt`` file to build the source file into an executable. +In order to compile the source the same way as it might be compiled +by the calling project, the generated project sets the value of the +:variable:`CMAKE_<LANG>_FLAGS` variable to that in the calling project. +The value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable may be +needed in some cases too, but CMake 3.1 and lower did not set it in +the generated project. CMake 3.2 and above prefer to set it so that +linker flags are honored as well as compiler flags. This policy +provides compatibility with the pre-3.2 behavior. + +The OLD behavior for this policy is to not set the value of the +:variable:`CMAKE_EXE_LINKER_FLAGS` variable in the generated test +project. The NEW behavior for this policy is to set the value of +the :variable:`CMAKE_EXE_LINKER_FLAGS` variable in the test project +to the same as it is in the calling project. + +If the project code does not set the policy explicitly, users may +set it on the command line by defining the +:variable:`CMAKE_POLICY_DEFAULT_CMP0056 <CMAKE_POLICY_DEFAULT_CMP<NNNN>>` +variable in the cache. + +This policy was introduced in CMake version 3.2. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses OLD behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. diff --git a/Help/release/3.1.0.rst b/Help/release/3.1.0.rst index 96717c6..a5b3e8e 100644 --- a/Help/release/3.1.0.rst +++ b/Help/release/3.1.0.rst @@ -245,6 +245,8 @@ Modules * The :module:`FindPkgConfig` module learned to use the ``PKG_CONFIG`` environment variable value as the ``pkg-config`` executable, if set. +* The :module:`FindXercesC` module was introduced. + * The :module:`FindZLIB` module now provides imported targets. * The :module:`GenerateExportHeader` module ``generate_export_header`` diff --git a/Help/release/dev/try_compile-link-flags.rst b/Help/release/dev/try_compile-link-flags.rst new file mode 100644 index 0000000..d995e0b --- /dev/null +++ b/Help/release/dev/try_compile-link-flags.rst @@ -0,0 +1,6 @@ +try_compile-link-flags +---------------------- + +* The :command:`try_compile` command source file signature now honors + link flags (e.g. :variable:`CMAKE_EXE_LINKER_FLAGS`) in the generated + test project. See policy :policy:`CMP0056`. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index b563aea..a83c807 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -9,6 +9,8 @@ warn by default: policy :policy:`CMP0025`. * ``CMAKE_POLICY_WARNING_CMP0047`` controls the warning for policy :policy:`CMP0047`. +* ``CMAKE_POLICY_WARNING_CMP0056`` controls the warning for + policy :policy:`CMP0056`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to |