diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/if.rst | 378 | ||||
| -rw-r--r-- | Help/index.rst | 16 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-packages.7.rst | 414 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 16 | ||||
| -rw-r--r-- | Help/module/CMakeFindDependencyMacro.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0024.rst | 2 | ||||
| -rw-r--r-- | Help/policy/CMP0037.rst | 2 | ||||
| -rw-r--r-- | Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst | 8 | ||||
| -rw-r--r-- | Help/variable/CMAKE_VERBOSE_MAKEFILE.rst | 9 |
10 files changed, 618 insertions, 229 deletions
diff --git a/Help/command/if.rst b/Help/command/if.rst index 0279be7..49c356e 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -3,24 +3,24 @@ if Conditionally execute a group of commands. -:: - - if(expression) - # then section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - elseif(expression2) - # elseif section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - else(expression) - # else section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endif(expression) +.. code-block:: cmake + + if(expression) + # then section. + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + ... + elseif(expression2) + # elseif section. + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + ... + else(expression) + # else section. + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + ... + endif(expression) Evaluates the given expression. If the result is true, the commands in the THEN section are invoked. Otherwise, the commands in the else @@ -28,212 +28,174 @@ section are invoked. The elseif and else sections are optional. You may have multiple elseif clauses. Note that the expression in the else and endif clause is optional. Long expressions can be used and there is a traditional order of precedence. Parenthetical expressions -are evaluated first followed by unary operators such as EXISTS, -COMMAND, and DEFINED. Then any EQUAL, LESS, GREATER, STRLESS, -STRGREATER, STREQUAL, MATCHES will be evaluated. Then NOT operators -and finally AND, OR operators will be evaluated. Possible expressions -are: - -:: - - if(<constant>) - -True if the constant is 1, ON, YES, TRUE, Y, or a non-zero number. -False if the constant is 0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, '', -or ends in the suffix '-NOTFOUND'. Named boolean constants are -case-insensitive. If the argument is not one of these constants, it -is treated as a variable: - -:: - - if(<variable>) - -True if the variable is defined to a value that is not a false -constant. False otherwise. (Note macro arguments are not variables.) - -:: - - if(NOT <expression>) - -True if the expression is not true. - -:: - - if(<expr1> AND <expr2>) - -True if both expressions would be considered true individually. - -:: - - if(<expr1> OR <expr2>) - -True if either expression would be considered true individually. - -:: - - if(COMMAND command-name) - -True if the given name is a command, macro or function that can be -invoked. - -:: - - if(POLICY policy-id) - -True if the given name is an existing policy (of the form CMP<NNNN>). - -:: - - if(TARGET target-name) - -True if the given name is an existing target, built or imported. - -:: - - if(EXISTS file-name) - if(EXISTS directory-name) - -True if the named file or directory exists. Behavior is well-defined -only for full paths. - -:: - - if(file1 IS_NEWER_THAN file2) - -True if file1 is newer than file2 or if one of the two files doesn't -exist. Behavior is well-defined only for full paths. If the file -time stamps are exactly the same, an IS_NEWER_THAN comparison returns -true, so that any dependent build operations will occur in the event -of a tie. This includes the case of passing the same file name for -both file1 and file2. - -:: - - if(IS_DIRECTORY directory-name) - -True if the given name is a directory. Behavior is well-defined only -for full paths. - -:: - - if(IS_SYMLINK file-name) - -True if the given name is a symbolic link. Behavior is well-defined -only for full paths. - -:: - - if(IS_ABSOLUTE path) - -True if the given path is an absolute path. - -:: - - if(<variable|string> MATCHES regex) - -True if the given string or variable's value matches the given regular -expression. - -:: - - if(<variable|string> LESS <variable|string>) - if(<variable|string> GREATER <variable|string>) - if(<variable|string> EQUAL <variable|string>) - -True if the given string or variable's value is a valid number and the -inequality or equality is true. - -:: - - if(<variable|string> STRLESS <variable|string>) - if(<variable|string> STRGREATER <variable|string>) - if(<variable|string> STREQUAL <variable|string>) - -True if the given string or variable's value is lexicographically less -(or greater, or equal) than the string or variable on the right. - -:: - - if(<variable|string> VERSION_LESS <variable|string>) - if(<variable|string> VERSION_EQUAL <variable|string>) - if(<variable|string> VERSION_GREATER <variable|string>) - -Component-wise integer version number comparison (version format is -major[.minor[.patch[.tweak]]]). - -:: - - if(DEFINED <variable>) - -True if the given variable is defined. It does not matter if the -variable is true or false just if it has been set. (Note macro -arguments are not variables.) - -:: - - if((expression) AND (expression OR (expression))) - -The expressions inside the parenthesis are evaluated first and then -the remaining expression is evaluated as in the previous examples. -Where there are nested parenthesis the innermost are evaluated as part -of evaluating the expression that contains them. +are evaluated first followed by unary tests such as ``EXISTS``, +``COMMAND``, and ``DEFINED``. Then any binary tests such as +``EQUAL``, ``LESS``, ``GREATER``, ``STRLESS``, ``STRGREATER``, +``STREQUAL``, and ``MATCHES`` will be evaluated. Then boolean ``NOT`` +operators and finally boolean ``AND`` and then ``OR`` operators will +be evaluated. + +Possible expressions are: + +``if(<constant>)`` + True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, + or a non-zero number. False if the constant is ``0``, ``OFF``, + ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string, + or ends in the suffix ``-NOTFOUND``. Named boolean constants are + case-insensitive. If the argument is not one of these constants, it + is treated as a variable. + +``if(<variable>)`` + True if the variable is defined to a value that is not a false + constant. False otherwise. (Note macro arguments are not variables.) + +``if(NOT <expression>)`` + True if the expression is not true. + +``if(<expr1> AND <expr2>)`` + True if both expressions would be considered true individually. + +``if(<expr1> OR <expr2>)`` + True if either expression would be considered true individually. + +``if(COMMAND command-name)`` + True if the given name is a command, macro or function that can be + invoked. + +``if(POLICY policy-id)`` + True if the given name is an existing policy (of the form ``CMP<NNNN>``). + +``if(TARGET target-name)`` + True if the given name is an existing logical target name such as those + created by the :command:`add_executable`, :command:`add_library`, or + :command:`add_custom_target` commands. + +``if(EXISTS path-to-file-or-directory)`` + True if the named file or directory exists. Behavior is well-defined + only for full paths. + +``if(file1 IS_NEWER_THAN file2)`` + True if file1 is newer than file2 or if one of the two files doesn't + exist. Behavior is well-defined only for full paths. If the file + time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns + true, so that any dependent build operations will occur in the event + of a tie. This includes the case of passing the same file name for + both file1 and file2. + +``if(IS_DIRECTORY path-to-directory)`` + True if the given name is a directory. Behavior is well-defined only + for full paths. + +``if(IS_SYMLINK file-name)`` + True if the given name is a symbolic link. Behavior is well-defined + only for full paths. + +``if(IS_ABSOLUTE path)`` + True if the given path is an absolute path. + +``if(<variable|string> MATCHES regex)`` + True if the given string or variable's value matches the given regular + expression. + +``if(<variable|string> LESS <variable|string>)`` + True if the given string or variable's value is a valid number and less + than that on the right. + +``if(<variable|string> GREATER <variable|string>)`` + True if the given string or variable's value is a valid number and greater + than that on the right. + +``if(<variable|string> EQUAL <variable|string>)`` + True if the given string or variable's value is a valid number and equal + to that on the right. + +``if(<variable|string> STRLESS <variable|string>)`` + True if the given string or variable's value is lexicographically less + than the string or variable on the right. + +``if(<variable|string> STRGREATER <variable|string>)`` + True if the given string or variable's value is lexicographically greater + than the string or variable on the right. + +``if(<variable|string> STREQUAL <variable|string>)`` + True if the given string or variable's value is lexicographically equal + to the string or variable on the right. + +``if(<variable|string> VERSION_LESS <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + +``if(<variable|string> VERSION_EQUAL <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + +``if(<variable|string> VERSION_GREATER <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + +``if(DEFINED <variable>)`` + True if the given variable is defined. It does not matter if the + variable is true or false just if it has been set. (Note macro + arguments are not variables.) + +``if((expression) AND (expression OR (expression)))`` + The expressions inside the parenthesis are evaluated first and then + the remaining expression is evaluated as in the previous examples. + Where there are nested parenthesis the innermost are evaluated as part + of evaluating the expression that contains them. The if command was written very early in CMake's history, predating -the ${} variable evaluation syntax, and for convenience evaluates +the ``${}`` variable evaluation syntax, and for convenience evaluates variables named by its arguments as shown in the above signatures. -Note that normal variable evaluation with ${} applies before the if -command even receives the arguments. Therefore code like - -:: - - set(var1 OFF) - set(var2 "var1") - if(${var2}) - -appears to the if command as +Note that normal variable evaluation with ``${}`` applies before the if +command even receives the arguments. Therefore code like:: -:: + set(var1 OFF) + set(var2 "var1") + if(${var2}) - if(var1) +appears to the if command as:: -and is evaluated according to the if(<variable>) case documented -above. The result is OFF which is false. However, if we remove the -${} from the example then the command sees + if(var1) -:: +and is evaluated according to the ``if(<variable>)`` case documented +above. The result is ``OFF`` which is false. However, if we remove the +``${}`` from the example then the command sees:: - if(var2) + if(var2) -which is true because var2 is defined to "var1" which is not a false +which is true because ``var2`` is defined to "var1" which is not a false constant. Automatic evaluation applies in the other cases whenever the -above-documented signature accepts <variable|string>: +above-documented signature accepts ``<variable|string>``: -1) The left hand argument to MATCHES is first checked to see if it is -a defined variable, if so the variable's value is used, otherwise the -original value is used. +* The left hand argument to ``MATCHES`` is first checked to see if it is + a defined variable, if so the variable's value is used, otherwise the + original value is used. -2) If the left hand argument to MATCHES is missing it returns false -without error +* If the left hand argument to ``MATCHES`` is missing it returns false + without error -3) Both left and right hand arguments to LESS GREATER EQUAL are -independently tested to see if they are defined variables, if so their -defined values are used otherwise the original value is used. +* Both left and right hand arguments to ``LESS``, ``GREATER``, and + ``EQUAL`` are independently tested to see if they are defined + variables, if so their defined values are used otherwise the original + value is used. -4) Both left and right hand arguments to STRLESS STREQUAL STRGREATER -are independently tested to see if they are defined variables, if so -their defined values are used otherwise the original value is used. +* Both left and right hand arguments to ``STRLESS``, ``STREQUAL``, and + ``STRGREATER`` are independently tested to see if they are defined + variables, if so their defined values are used otherwise the original + value is used. -5) Both left and right hand argumemnts to VERSION_LESS VERSION_EQUAL -VERSION_GREATER are independently tested to see if they are defined -variables, if so their defined values are used otherwise the original -value is used. +* Both left and right hand argumemnts to ``VERSION_LESS``, + ``VERSION_EQUAL``, and ``VERSION_GREATER`` are independently tested + to see if they are defined variables, if so their defined values are + used otherwise the original value is used. -6) The right hand argument to NOT is tested to see if it is a boolean -constant, if so the value is used, otherwise it is assumed to be a -variable and it is dereferenced. +* The right hand argument to ``NOT`` is tested to see if it is a boolean + constant, if so the value is used, otherwise it is assumed to be a + variable and it is dereferenced. -7) The left and right hand arguments to AND OR are independently -tested to see if they are boolean constants, if so they are used as -such, otherwise they are assumed to be variables and are dereferenced. +* The left and right hand arguments to ``AND`` and ``OR`` are independently + tested to see if they are boolean constants, if so they are used as + such, otherwise they are assumed to be variables and are dereferenced. diff --git a/Help/index.rst b/Help/index.rst index 4ef5c3f..a7a1bd9 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -26,23 +26,17 @@ Reference Manuals :maxdepth: 1 /manual/cmake-commands.7 + /manual/cmake-developer.7 + /manual/cmake-generator-expressions.7 /manual/cmake-generators.7 - /manual/cmake-toolchains.7 + /manual/cmake-language.7 /manual/cmake-modules.7 + /manual/cmake-packages.7 /manual/cmake-policies.7 /manual/cmake-properties.7 + /manual/cmake-toolchains.7 /manual/cmake-variables.7 -Other Manuals -############# - -.. toctree:: - :maxdepth: 1 - - /manual/cmake-developer.7 - /manual/cmake-generator-expressions.7 - /manual/cmake-language.7 - .. only:: html Index and Search diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index f148a51..3f819d6 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -39,6 +39,7 @@ All Modules /module/CMakeDependentOption /module/CMakeDetermineVSServicePack /module/CMakeExpandImportedTargets + /module/CMakeFindDependencyMacro /module/CMakeFindFrameworks /module/CMakeFindPackageMode /module/CMakeForceCompiler diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst new file mode 100644 index 0000000..952da3c --- /dev/null +++ b/Help/manual/cmake-packages.7.rst @@ -0,0 +1,414 @@ +.. cmake-manual-description: CMake Packages Reference + +cmake-packages(7) +***************** + +.. only:: html or latex + + .. contents:: + +Introduction +============ + +Packages provide dependency information to CMake based buildsystems. Packages +are found with the :command:`find_package` command. The result of +using ``find_package`` is either a set of :prop_tgt:`IMPORTED` targets, or +a set of variables corresponding to build-relevant information. + +Using Packages +============== + +CMake provides direct support for two forms of packages, +`Config-file Packages`_ and `Find-module Packages`_. +Indirect support for ``pkg-config`` packages is also provided via +the :module:`FindPkgConfig` module. In all cases, the basic form +of :command:`find_package` calls is the same: + +.. code-block:: cmake + + find_package(Qt4 4.7.0 REQUIRED) # CMake provides a Qt4 find-module + find_package(Qt5Core 5.1.0 REQUIRED) # Qt provides a Qt5 package config file. + find_package(LibXml2 REQUIRED) # Use pkg-config via the LibXml2 find-module + +In cases where it is known that a package configuration file is provided by +upstream, and only that should be used, the ``CONFIG`` keyword may be passed +to :command:`find_package`: + +.. code-block:: cmake + + find_package(Qt5Core 5.1.0 CONFIG REQUIRED) + find_package(Qt5Gui 5.1.0 CONFIG) + +Similarly, the ``MODULE`` keyword says to use only a find-module: + +.. code-block:: cmake + + find_package(Qt4 4.7.0 MODULE REQUIRED) + +Specifying the type of package explicitly improves the error message shown to +the user if it is not found. + +Both types of packages also support specifying components of a package, +either after the ``REQUIRED`` keyword: + +.. code-block:: cmake + + find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql) + +or as a separate ``COMPONENTS`` list: + +.. code-block:: cmake + + find_package(Qt5 5.1.0 COMPONENTS Widgets Xml Sql) + +or as a separate ``OPTIONAL_COMPONENTS`` list: + +.. code-block:: cmake + + find_package(Qt5 5.1.0 COMPONENTS Widgets + OPTIONAL_COMPONENTS Xml Sql + ) + +Handling of ``COMPONENTS`` and ``OPTIONAL_COMPONENTS`` is defined by the +package. + +Config-file Packages +-------------------- + +A config-file package is a set of files provided by upstreams for downstreams +to use. CMake searches in a number of locations for package configuration files, as +described in the :command:`find_package` documentation. The most simple way for +a CMake user to tell :manual:`cmake(1)` to search in a non-standard prefix for +a package is to set the ``CMAKE_PREFIX_PATH`` cache variable. + +Config-file packages are provided by upstream vendors as part of development +packages, that is, they belong with the header files and any other files +provided to assist downsteams in using the package. + +A set of variables which provide package status information are also set +automatically when using a config-file package. The ``<Package>_FOUND`` +variable is set to true or false, depending on whether the package was +found. The ``<Package>_DIR`` cache variable is set to the location of the +package configuration file. + +Find-module Packages +-------------------- + +A find module is a file with a set of rules for finding the required pieces of +a dependency, primarily header files and libraries. Typically, a find module +is needed when the upstream is not built with CMake, or is not CMake-aware +enough to otherwise provide a package configuration file. Unlike a package configuration +file, it is not shipped with upstream, but is used by downstream to find the +files by guessing locations of files with platform-specific hints. + +Unlike the case of an upstream-provided package configuration file, no single point +of reference identifies the package as being found, so the ``<Package>_FOUND`` +variable is not automatically set by the :command:`find_package` command. It +can still be expected to be set by convention however and should be set by +the author of the Find-module. Similarly there is no ``<Package>_DIR`` variable, +but each of the artifacts such as library locations and header file locations +provide a separate cache variable. + +See the :manual:`cmake-developer(7)` manual for more information about creating +Find-module files. + +Package Layout +============== + +A config-file package consists of a `Package Configuration File`_ and +optionally a `Package Version File`_ provided with the project distribution. + +Package Configuration File +-------------------------- + +Consider a project ``Foo`` that installs the following files:: + + <prefix>/include/foo-1.2/foo.h + <prefix>/lib/foo-1.2/libfoo.a + +It may also provide a CMake package configuration file:: + + <prefix>/lib/cmake/foo-1.2/FooConfig.cmake + +with content defining :prop_tgt:`IMPORTED` targets, or defining variables, such +as:: + + # ... + # (compute PREFIX relative to file location) + # ... + set(Foo_INCLUDE_DIRS ${PREFIX}/include/foo-1.2) + set(Foo_LIBRARIES ${PREFIX}/lib/foo-1.2/libfoo.a) + +If another project wishes to use ``Foo`` it need only to locate the ``FooConfig.cmake`` +file and load it to get all the information it needs about package content +locations. Since the package configuration file is provided by the package +installation it already knows all the file locations. + +The :command:`find_package` command may be used to search for the package +configuration file. This command constructs a set of installation prefixes +and searches under each prefix in several locations. Given the name ``Foo``, +it looks for a file called ``FooConfig.cmake`` or ``foo-config.cmake``. +The full set of locations is specified in the :command:`find_package` command +documentation. One place it looks is:: + + <prefix>/lib/cmake/Foo*/ + +where ``Foo*`` is a case-insensitive globbing expression. In our example the +globbing expression will match ``<prefix>/lib/cmake/foo-1.2`` and the package +configuration file will be found. + +Once found, a package configuration file is immediately loaded. It, together +with a package version file, contains all the information the project needs to +use the package. + +Package Version File +-------------------- + +When the :command:`find_package` command finds a candidate package configuration +file it looks next to it for a version file. The version file is loaded to test +whether the package version is an acceptable match for the version requested. +If the version file claims compatibility the configuration file is accepted. +Otherwise it is ignored. + +The name of the package version file must match that of the package configuration +file but has either ``-version`` or ``Version`` appended to the name before +the ``.cmake`` extension. For example, the files:: + + <prefix>/lib/cmake/foo-1.3/foo-config.cmake + <prefix>/lib/cmake/foo-1.3/foo-config-version.cmake + +and:: + + <prefix>/lib/cmake/bar-4.2/BarConfig.cmake + <prefix>/lib/cmake/bar-4.2/BarConfigVersion.cmake + +are each pairs of package configuration files and corresponding package version +files. + +When the :command:`find_package` command loads a version file it first sets the +following variables: + +``PACKAGE_FIND_NAME`` + The <package> name + +``PACKAGE_FIND_VERSION`` + Full requested version string + +``PACKAGE_FIND_VERSION_MAJOR`` + Major version if requested, else 0 + +``PACKAGE_FIND_VERSION_MINOR`` + Minor version if requested, else 0 + +``PACKAGE_FIND_VERSION_PATCH`` + Patch version if requested, else 0 + +``PACKAGE_FIND_VERSION_TWEAK`` + Tweak version if requested, else 0 + +``PACKAGE_FIND_VERSION_COUNT`` + Number of version components, 0 to 4 + +The version file must use these variables to check whether it is compatible or +an exact match for the requested version and set the following variables with +results: + +``PACKAGE_VERSION`` + Full provided version string + +``PACKAGE_VERSION_EXACT`` + True if version is exact match + +``PACKAGE_VERSION_COMPATIBLE`` + True if version is compatible + +``PACKAGE_VERSION_UNSUITABLE`` + True if unsuitable as any version + +Version files are loaded in a nested scope so they are free to set any variables +they wish as part of their computation. The find_package command wipes out the +scope when the version file has completed and it has checked the output +variables. When the version file claims to be an acceptable match for the +requested version the find_package command sets the following variables for +use by the project: + +``<package>_VERSION`` + Full provided version string + +``<package>_VERSION_MAJOR`` + Major version if provided, else 0 + +``<package>_VERSION_MINOR`` + Minor version if provided, else 0 + +``<package>_VERSION_PATCH`` + Patch version if provided, else 0 + +``<package>_VERSION_TWEAK`` + Tweak version if provided, else 0 + +``<package>_VERSION_COUNT`` + Number of version components, 0 to 4 + +The variables report the version of the package that was actually found. +The ``<package>`` part of their name matches the argument given to the +:command:`find_package` command. + +Creating Packages +================= + +Usually, the upstream depends on CMake itself and can use some CMake facilities +for creating the package files. Consider an upstream which provides a single +shared library: + +.. code-block:: cmake + + project(UpstreamLib) + + set(CMAKE_INCLUDE_CURRENT_DIR ON) + + set(Upstream_VERSION 3.4.1) + + include(GenerateExportHeader) + + add_library(ClimbingStats SHARED climbingstats.cpp) + generate_export_header(ClimbingStats) + + install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets + LIBRARY DESTINATION lib + ARCHIVE DESTINATION lib + RUNTIME DESTINATION bin + INCLUDES DESTINATION include + ) + install( + FILES + climbingstats.h + "${CMAKE_CURRENT_BINARY_DIR}/climbingstats_export.h" + DESTINATION + include + COMPONENT + Devel + ) + + include(CMakePackageConfigHelpers) + write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStatsConfigVersion.cmake" + VERSION ${Upstream_VERSION} + COMPATIBILITY AnyNewerVersion + ) + + set(ConfigPackageLocation lib/cmake/ClimbingStats) + install(EXPORT ClimbingStatsTargets + FILE + ClimbingStatsTargets.cmake + NAMESPACE + Upstream:: + DESTINATION + ${ConfigPackageLocation} + ) + install( + FILES + cmake/ClimbingStatsConfig.cmake + "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStatsConfigVersion.cmake" + DESTINATION + ${ConfigPackageLocation} + COMPONENT + Devel + ) + +The :module:`CMakePackageConfigHelpers` module provides a macro for creating +a simple ``ConfigVersion.cmake`` file. This file sets the version of the +package. It is read by CMake when :command:`find_package` is called to +determine the compatibility with the requested version, and to set some +version-specific variables ``<Package>_VERSION``, ``<Package>_VERSION_MAJOR``, +``<Package>_VERSION_MINOR`` etc. The :command:`install(EXPORT)` command is +used to export the targets in the ``ClimbingStatsTargets`` export-set, defined +previously by the :command:`install(TARGETS)` command. This command generates +the ``ClimbingStatsTargets.cmake`` file to contain :prop_tgt:`IMPORTED` +targets, suitable for use by downsteams and arranges to install it to +``lib/cmake/ClimbingStats``. The generated ``ClimbingStatsConfigVersion.cmake`` +and a ``cmake/ClimbingStatsConfig.cmake`` are installed to the same location, +completing the package. + +A ``NAMESPACE`` with double-colons is specified when exporting the targets +for installation. This convention of double-colons gives CMake a hint that +the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams +with the :command:`target_link_libraries` command. This way, CMake can +issue a diagnostic if the package providing it has not yet been found. + +In this case, when using :command:`install(TARGETS)` the ``INCLUDES DESTINATION`` +was specified. This causes the ``IMPORTED`` targets to have their +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated with the ``include`` +directory in the :variable:`CMAKE_INSTALL_PREFIX`. When the ``IMPORTED`` +target is used by downsteam, it automatically consumes the entries from +that property. + +In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as: + +.. code-block:: cmake + + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake") + +As this allows downstreams to use the ``IMPORTED`` targets. If any macros +should be provided by the ``ClimbingStats`` package, they should +be in a separate file which is installed to the same location as the +``ClimbingStatsConfig.cmake`` file, and included from there. + +This can also be extended to cover dependencies: + +.. code-block:: cmake + + # ... + add_library(ClimbingStats SHARED climbingstats.cpp) + generate_export_header(ClimbingStats) + + find_package(Stats 2.6.4 REQUIRED) + target_link_libraries(ClimbingStats PUBLIC Stats::Types) + +As the ``Stats::Types`` target is a ``PUBLIC`` dependency of ``ClimbingStats``, +downsteams must also find the ``Stats`` package and link to the ``Stats::Types`` +library. The ``Stats`` package should be found in the ``ClimbingStatsConfig.cmake`` +file to ensure this. The ``find_dependency`` macro from the +:module:`CMakeFindDependencyMacro` helps with this by propagating +whether the package is ``REQUIRED``, or ``QUIET`` etc. All ``REQUIRED`` +dependencies of a package should be found in the ``Config.cmake`` file: + +.. code-block:: cmake + + include(CMakePackageConfigHelpers) + find_dependency(Stats 2.6.4) + + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake") + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake") + +The ``find_dependency`` macro also sets ``ClimbingStats_FOUND`` to ``False`` if +the dependency is not found, along with a diagnostic that the ``ClimbingStats`` +package can not be used without the ``Stats`` package. + +If ``COMPONENTS`` are specified when the downstream uses :command:`find_package`, +they are listed in the ``<Package>_FIND_COMPONENTS`` variable. If a particular +component is non-optional, then the ``<Package>_FIND_REQUIRED_<comp>`` will +be true. This can be tested with logic in the package configuration file: + +.. code-block:: cmake + + include(CMakePackageConfigHelpers) + find_dependency(Stats 2.6.4) + + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake") + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake") + + set(_supported_components Plot Table) + + foreach(_comp ${ClimbingStats_FIND_COMPONENTS}) + if (NOT ";${_supported_components};" MATCHES _comp) + set(ClimbingStats_FOUND False) + set(ClimbingStats_NOTFOUND_MESSAGE "Specified unsupported component: ${_comp}") + endif() + include("${CMAKE_CURRENT_LIST_DIR}ClimbingStats${_comp}Targets.cmake") + endforeach() + +Here, the ``ClimbingStats_NOTFOUND_MESSAGE`` is set to a diagnosis that the package +could not be found because an invalid component was specified. This message +variable can be set for any case where the ``_FOUND`` variable is set to ``False``, +and will be displayed to the user. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 1e57495..d467c36 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -21,7 +21,21 @@ for a policy, also avoiding the warning. The :command:`cmake_minimum_required` command does more than report an error if a too-old version of CMake is used to build a project. It also sets all policies introduced in that CMake version or earlier to -NEW behavior. +NEW behavior. To manage policies without increasing the minimum required +CMake version, the :command:`if(POLICY)` command may be used:: + + if(POLICY CMP0990) + cmake_policy(SET CMP0990 NEW) + endif() + +This has the effect of using the NEW behavior with newer CMake releases which +users may be using and not issuing a compatibility warning. + +The setting of a policy is confined in some cases to not propagate to the +parent scope. For example, if the files read by the :command:`include` command +or the :command:`find_package` command contain a use of :command:`cmake_policy`, +that policy setting will not affect the caller by default. Both commands accept +an optional ``NO_POLICY_SCOPE`` keyword to control this behavior. The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or diff --git a/Help/module/CMakeFindDependencyMacro.rst b/Help/module/CMakeFindDependencyMacro.rst new file mode 100644 index 0000000..5b5b550 --- /dev/null +++ b/Help/module/CMakeFindDependencyMacro.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeFindDependencyMacro.cmake diff --git a/Help/policy/CMP0024.rst b/Help/policy/CMP0024.rst index 4c8c714..abfcc75 100644 --- a/Help/policy/CMP0024.rst +++ b/Help/policy/CMP0024.rst @@ -11,7 +11,7 @@ until later at generate-time, such as the link language and complete list of link libraries. Future refactoring will change the effect of the export() command to be executed at generate-time. Use ALIAS targets instead in cases where the goal is to refer to targets by -another name +another name. The OLD behavior for this policy is to allow including the result of an export() command. The NEW behavior for this policy is to not to diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst index 059b2e6..f4d2f4e 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -11,7 +11,7 @@ diagnostics expect target names to match a restricted pattern. Target names may contain upper and lower case letters, numbers, the underscore character (_), dot(.), plus(+) and minus(-). As a special case, ALIAS -targets and INTERFACE library targets may contain two consequtive colons. +targets and IMPORTED targets may contain two consequtive colons. Target names reserved by one or more CMake generators are not allowed. Among others these include "all", "help" and "test". diff --git a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst index 6b17f6e..11aed0c 100644 --- a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst +++ b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst @@ -5,7 +5,9 @@ Enables tracing output for target properties. This variable can be populated with a list of properties to generate debug output for when evaluating target properties. Currently it can -only be used when evaluating the INCLUDE_DIRECTORIES, -COMPILE_DEFINITIONS, COMPILE_OPTIONS and AUTOUIC_OPTIONS target properties. -In that case, it outputs a backtrace for each entry in the target property. +only be used when evaluating the :prop_tgt:`INCLUDE_DIRECTORIES`, +:prop_tgt:`COMPILE_DEFINITIONS`, :prop_tgt:`COMPILE_OPTIONS`, :prop_tgt:`AUTOUIC_OPTIONS`, +:prop_tgt:`POSITION_INDEPENDENT_CODE` target properties and any other property +listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other ``COMPATIBLE_INTERFACE_`` +properties. It outputs an origin for each entry in the target property. Default is unset. diff --git a/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst b/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst index 451ce8c..2420a25 100644 --- a/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst +++ b/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst @@ -1,8 +1,9 @@ CMAKE_VERBOSE_MAKEFILE ---------------------- -Create verbose makefiles if on. +Enable verbose output from Makefile builds. -This variable defaults to false. You can set this variable to true to -make CMake produce verbose makefiles that show each command line as it -is used. +This variable is a cache entry initialized (to FALSE) by +the :command:`project` command. Users may enable the option +in their local build tree to get more verbose output from +Makefile builds and show each command line as it is launched. |