[Cmake-commits] CMake branch, next, updated. v3.1.0-rc2-1109-gda1ba8e
Stephen Kelly
steveire at gmail.com
Thu Dec 4 17:58:16 EST 2014
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 da1ba8eb418d6f08b2d21892ee83a82626da4663 (commit)
via e4d4289fad046ad1cab28f6abb144f609c112157 (commit)
via 656167c3e0eb06ee69b2e6ffbba82bf0f385618e (commit)
via f0d0d761b2150e41397af8cfce2b846107cf8921 (commit)
via 31452416ba1be692b55ed09f8cf39fa2914ad349 (commit)
via b96b025b2a337d7b09157f8b24cf9ca77a825863 (commit)
via 169f116632321e99701986f48a19e836d2b9e710 (commit)
from cdcb21844397efd56862fd4fad67f4b4d8045f6b (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=da1ba8eb418d6f08b2d21892ee83a82626da4663
commit da1ba8eb418d6f08b2d21892ee83a82626da4663
Merge: cdcb218 e4d4289
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Dec 4 17:58:14 2014 -0500
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Thu Dec 4 17:58:14 2014 -0500
Merge topic 'Find-Modules-documentation' into next
e4d4289f Help: Document that IMPORTED targets in Find modules may be UNKNOWN.
656167c3 Help: Document IMPORTED_CONFIGURATIONS target property for Find modules.
f0d0d761 Help: Remove recommendation about checking minimum CMake version.
31452416 Help: Add useful links to IMPORTED targets and usage requirements.
b96b025b Help: Remove disadvantage creating IMPORTED targets in Find modules.
169f1166 Help: Link to cmake-packages(7) from the Module creation documentation.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=e4d4289fad046ad1cab28f6abb144f609c112157
commit e4d4289fad046ad1cab28f6abb144f609c112157
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Dec 4 23:56:52 2014 +0100
Commit: Stephen Kelly <steveire at gmail.com>
CommitDate: Thu Dec 4 23:57:12 2014 +0100
Help: Document that IMPORTED targets in Find modules may be UNKNOWN.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index 85a3c2d..8c61dfd 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -1052,6 +1052,11 @@ 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:
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=656167c3e0eb06ee69b2e6ffbba82bf0f385618e
commit 656167c3e0eb06ee69b2e6ffbba82bf0f385618e
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Dec 4 23:56:21 2014 +0100
Commit: Stephen Kelly <steveire at gmail.com>
CommitDate: Thu Dec 4 23:56:40 2014 +0100
Help: Document IMPORTED_CONFIGURATIONS target property for Find modules.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index 94fc019..85a3c2d 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -876,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.
@@ -1049,6 +1052,42 @@ 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.
+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 "${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 "${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.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=f0d0d761b2150e41397af8cfce2b846107cf8921
commit f0d0d761b2150e41397af8cfce2b846107cf8921
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Dec 4 23:55:15 2014 +0100
Commit: Stephen Kelly <steveire at gmail.com>
CommitDate: Thu Dec 4 23:55:15 2014 +0100
Help: Remove recommendation about checking minimum CMake version.
If this file is being executed, the user has the CMake version
providing it.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index d928097..94fc019 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -943,16 +943,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.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=31452416ba1be692b55ed09f8cf39fa2914ad349
commit 31452416ba1be692b55ed09f8cf39fa2914ad349
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Dec 4 23:30:20 2014 +0100
Commit: Stephen Kelly <steveire at gmail.com>
CommitDate: Thu Dec 4 23:33:50 2014 +0100
Help: Add useful links to IMPORTED targets and usage requirements.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index f054d83..d928097 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -730,10 +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.
+: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
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=b96b025b2a337d7b09157f8b24cf9ca77a825863
commit b96b025b2a337d7b09157f8b24cf9ca77a825863
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Dec 4 23:25:56 2014 +0100
Commit: Stephen Kelly <steveire at gmail.com>
CommitDate: Thu Dec 4 23:32:52 2014 +0100
Help: Remove disadvantage creating IMPORTED targets in Find modules.
An IMPORTED target in either type of package can equally depend on
an IMPORTED target in a Find module, which must be found as a
dependency, which is presumably the problem being implied. This is
not a distinction of creating an IMPORTED target in a Find module.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index c7bafc0..f054d83 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -733,10 +733,7 @@ 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.
+by using the target in a :command:`target_link_libraries` call.
In either case (or even when providing both variables and imported
targets), find modules should provide backwards compatibility with old
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=169f116632321e99701986f48a19e836d2b9e710
commit 169f116632321e99701986f48a19e836d2b9e710
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Dec 4 23:19:45 2014 +0100
Commit: Stephen Kelly <steveire at gmail.com>
CommitDate: Thu Dec 4 23:31:59 2014 +0100
Help: Link to cmake-packages(7) from the Module creation documentation.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index 672c9b7..c7bafc0 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
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
--------------------
-----------------------------------------------------------------------
Summary of changes:
Help/manual/cmake-developer.7.rst | 70 +++++++++++++++++++++++++++----------
Help/manual/cmake-packages.7.rst | 2 ++
2 files changed, 53 insertions(+), 19 deletions(-)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list