[Cmake-commits] CMake branch, next, updated. v2.8.12.1-6208-ge530fdd
Stephen Kelly
steveire at gmail.com
Fri Dec 13 10:11:19 EST 2013
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, next has been updated
via e530fdd0e740973840cb6564ccfc1c67222c2282 (commit)
via 63497a9eff210d6a6f978ab004a04fceaeb82084 (commit)
from e700bedcb0dc9dc3810084660ed24ce7d5785419 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=e530fdd0e740973840cb6564ccfc1c67222c2282
commit e530fdd0e740973840cb6564ccfc1c67222c2282
Merge: e700bed 63497a9
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Fri Dec 13 10:11:10 2013 -0500
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Fri Dec 13 10:11:10 2013 -0500
Merge topic 'cmake-packages-manual' into next
63497a9 Minor cleanups.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=63497a9eff210d6a6f978ab004a04fceaeb82084
commit 63497a9eff210d6a6f978ab004a04fceaeb82084
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Tue Dec 3 13:55:03 2013 +0100
Commit: Stephen Kelly <steveire at gmail.com>
CommitDate: Fri Dec 13 16:09:46 2013 +0100
Minor cleanups.
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
index 65a6d03..bff7e8e 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -15,23 +15,32 @@ 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.
-CMake provides direct support for two forms of packages, config-file based
-packages and find-module based packages. Indirect support for pkg-config
+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 ``find_package`` is the same::
+cases, the basic form of ``find_package`` 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 config-file.
find_package(LibXml2 REQUIRED) # Use pkg-config via the LibXml2 find-module
In cases where it is known that a Config file is provided by upstream, and only
-that should be used, the ``CONFIG`` keyword may be passed to ``find_package``::
+that should be used, the ``CONFIG`` keyword may be passed to ``find_package``:
+
+.. code-block:: cmake
find_package(Qt5Core 5.1.0 CONFIG REQUIRED)
find_package(Qt5Gui 5.1.0 CONFIG)
Similarly, the ``MODULE`` keyword requests that only a find-module be searched
-for::
+for:
+
+.. code-block:: cmake
find_package(Qt4 4.7.0 MODULE REQUIRED)
@@ -39,15 +48,21 @@ 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::
+after the REQUIRED keyword:
+
+.. code-block:: cmake
find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql)
-or as a separate COMPONENTS list::
+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::
+or as a separate OPTIONAL_COMPONENTS list:
+
+.. code-block:: cmake
find_package(Qt5 5.1.0 COMPONENTS Widgets
OPTIONAL_COMPONENTS Xml Sql
@@ -56,14 +71,14 @@ or as a separate OPTIONAL_COMPONENTS list::
Handling of ``COMPONENTS`` and ``OPTIONAL_COMPONENTS`` is defined by the
package.
-Config-file packages
-====================
+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 config file packages, 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`` environment variable.
+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
@@ -71,13 +86,132 @@ 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 dependency was
+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.
+package configuration file.
+
+Package Version Files
+---------------------
+
+When the ``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 version file must match that of the configuration file but has
+either "-version" or "Version" appended to the name before the ".cmake"
+extension. For example, the files::
+
+ <prefix>/lib/foo-1.3/foo-config.cmake
+ <prefix>/lib/foo-1.3/foo-config-version.cmake
+
+and::
+
+ <prefix>/lib/bar-4.2/BarConfig.cmake
+ <prefix>/lib/bar-4.2/BarConfigVersion.cmake
+
+are each pairs of package configuration files and corresponding version files.
+
+When the ``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
+``find_package`` command.
+
+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 config-file package. 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 config-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.
+
+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::
+shared library:
+
+.. code-block:: cmake
project(UpstreamLib)
@@ -159,7 +293,9 @@ 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::
+In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as:
+
+.. code-block:: cmake
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
@@ -168,7 +304,9 @@ 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::
+This can also be extended to cover dependencies:
+
+.. code-block:: cmake
# ...
add_library(ClimbingStats SHARED climbingstats.cpp)
@@ -181,9 +319,11 @@ 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:`CMakePackageConfigHelpers` helps with this by propagating
+: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::
+dependencies of a package should be found in the ``Config.cmake`` file:
+
+.. code-block:: cmake
include(CMakePackageConfigHelpers)
find_dependency(Stats 2.6.4)
@@ -198,7 +338,9 @@ 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 Config file::
+be true. This can be tested with logic in the Config file:
+
+.. code-block:: cmake
include(CMakePackageConfigHelpers)
find_dependency(Stats 2.6.4)
@@ -220,118 +362,3 @@ Here, the ``ClimbingStats_NOTFOUND_MESSAGE`` is set to a diagnosis that the pack
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.
-
-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 config-file package. Unlike a config-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 config-file, no single point of
-reference identifies the package as being found, so the ``<Package>_FOUND``
-variable is not automatically set. 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.
-
-A find module may look something like::
-
- find_path(Pike_INCLUDE_DIR pike.h
- /usr/include/pike
- /usr/local/include/pike
- )
-
- find_library(PikeCore_LIBRARY
- NAMES pike-core pike-core7.4
- )
- find_library(PikeStream_LIBRARY
- NAMES pike-stream pike-stream7.4
- )
-
- mark_as_advanced(
- PikeCore_LIBRARY
- PikeStream_LIBRARY
- Pike_INCLUDE_DIR
- )
- set(PikeCore_LIBRARIES ${PikeCore_LIBRARY})
- set(PikeStream_LIBRARIES ${PikeStream_LIBRARY} ${PikeCore_LIBRARIES})
- set(Pike_LIBRARIES ${PikeCore_LIBRARIES} ${PikeStream_LIBRARIES})
- set(Pike_INCLUDE_DIRS ${Pike_INCLUDE_DIR})
-
- include(FindPackageHandleStandardArgs)
- find_package_handle_standard_args(Pike
- FOUND_VAR Pike_FOUND
- REQUIRED_VARS Pike_LIBRARIES Pike_INCLUDE_DIRS
- )
-
-In this case, the :command:`find_path` command is used to try to find
-the ``pike.h`` file and store the result in ``Pike_INCLUDE_DIR``. Similarly
-the :command:`find_library` command is used to try to find the ``pike-core``
-library with two possible names. The result is stored as ``PikeCore_LIBRARY``,
-and all cache variables are marked as advanced to hide them from the user.
-
-After the files are found, normal variables are set. These variables are for
-use in the CMakeLists.txt. For example::
-
- find_package(Pike)
- if (Pike_FOUND)
- target_include_directories(user PRIVATE ${Pike_INCLUDE_DIRS})
- target_link_libraries(user PRIVATE ${Pike_LIBRARIES})
- endif()
-
-The non-plural variables are for cache-use only, and they should list all
-dependencies of the found libraries or headers too.
-
-The author of a find-module may alternatively choose to create an
-:prop_tgt:`IMPORTED` target for the found libraries::
-
- find_path(Pike_INCLUDE_DIR pike.h
- /usr/include/pike
- /usr/local/include/pike
- )
-
- find_library(PikeCore_LIBRARY
- NAMES pike-core pike-core7.4
- )
- find_library(PikeStream_LIBRARY
- NAMES pike-stream pike-stream7.4
- )
-
- mark_as_advanced(
- PikeCore_LIBRARY
- PikeStream_LIBRARY
- Pike_INCLUDE_DIR
- )
-
- include(FindPackageHandleStandardArgs)
- find_package_handle_standard_args(Pike
- FOUND_VAR Pike_FOUND
- REQUIRED_VARS Pike_LIBRARIES Pike_INCLUDE_DIRS
- )
-
- add_library(Pike::Core SHARED IMPORTED)
- set_property(TARGET Pike::Core
- PROPERTY IMPORTED_LOCATION ${PikeCore_LIBRARY}
- )
- set_property(TARGET Pike::Core
- PROPERTY INTERFACE_INCLUDE_DIRECTORIES
- ${Pike_INCLUDE_DIR}
- )
- add_library(Pike::Stream SHARED IMPORTED)
- set_property(TARGET Pike::Stream
- PROPERTY IMPORTED_LOCATION ${PikeStream_LIBRARY}
- )
- set_property(TARGET Pike::Stream
- PROPERTY INTERFACE_LINK_LIBRARIES
- Pike::Core
- )
-
-This way, downstreams can simply use :command:`target_link_libraries` and take
-advantage of the usage-requirement specifications encoded in the ``IMPORTED``
-targets::
-
- find_package(Pike REQUIRED)
- target_link_libraries(user PRIVATE Pike::Core)
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/Modules/CMakeFindDependencyMacro.cmake b/Modules/CMakeFindDependencyMacro.cmake
index b075801..596c6fc 100644
--- a/Modules/CMakeFindDependencyMacro.cmake
+++ b/Modules/CMakeFindDependencyMacro.cmake
@@ -1,3 +1,18 @@
+#.rst:
+# CMakeFindDependencyMacro
+# -------------------------
+#
+# ::
+#
+# find_dependency(<dep> [<version>])
+#
+#
+# ``find_dependency()`` wraps a :command:`find_package` call for a package
+# dependency. It is designed to be used in a <package>Config.cmake file, and it
+# forwards the correct parameters for EXACT, QUIET and REQUIRED which were
+# passed to the original :command:`find_package` call. It also sets an
+# informative diagnostic message if the dependency could not be found.
+#
#=============================================================================
# Copyright 2013 Stephen Kelly <steveire at gmail.com>
@@ -32,7 +47,7 @@ macro(find_dependency dep)
find_package(${dep} ${version} ${exact_arg} ${quiet_arg} ${required_arg})
if (NOT ${dep}_FOUND)
- set(${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE \"${CMAKE_FIND_PACKAGE_NAME} could not be found because dependency ${dep} could not be found.\")
+ set(${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE "${CMAKE_FIND_PACKAGE_NAME} could not be found because dependency ${dep} could not be found.")
set(${CMAKE_FIND_PACKAGE_NAME}_FOUND False)
return()
endif()
-----------------------------------------------------------------------
Summary of changes:
Help/manual/cmake-modules.7.rst | 1 +
Help/manual/cmake-packages.7.rst | 295 ++++++++++++++++--------------
Help/module/CMakeFindDependencyMacro.rst | 1 +
Modules/CMakeFindDependencyMacro.cmake | 17 ++-
4 files changed, 179 insertions(+), 135 deletions(-)
create mode 100644 Help/module/CMakeFindDependencyMacro.rst
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list