From ba9b9d79fb1a753c564be44e17e2d3b979f8108c Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 2 Apr 2015 16:16:14 -0400 Subject: [PATCH 1/5] Help: Fix syntax in non-relocatable usage requirements example The example in cmake-packages(7) is meant to be incorrect for use of absolute paths, not for its syntax. --- Help/manual/cmake-packages.7.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 3367ba472..b477cab59 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -385,11 +385,11 @@ generate config file packages: .. code-block:: cmake target_link_libraries(ClimbingStats INTERFACE - ${Boost_LIBRARIES};${OtherDep_LIBRARIES}> - ) + ${Boost_LIBRARIES} ${OtherDep_LIBRARIES} + ) target_include_directories(ClimbingStats INTERFACE - $ - ) + "$" + ) Dependencies must provide their own :ref:`IMPORTED targets ` which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and From 6e331ce9d47c8f9adbf29ee0158b4307debbc02c Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 2 Apr 2015 17:17:36 -0400 Subject: [PATCH 2/5] Help: Fix typo in cmake-packages(7) manual relevnt => relevant --- Help/manual/cmake-packages.7.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index b477cab59..6ee9df9a6 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -375,7 +375,7 @@ to be incompatible. Note that it is not advisable to populate any properties which may contain paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and -:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevnt to dependencies. +:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies. That would hard-code into installed packages the include directory or library paths for dependencies **as found on the machine the package was made on**. From 031d894fb882ca2e8c2269ba1674578f82155420 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 2 Apr 2015 15:45:48 -0400 Subject: [PATCH 3/5] Help: Place relocatable package notes in their own subsections These notes apply only for the use case of creating a package for redistribution on machines other than that where it is built. Clarify this to readers by placing the discussion in dedicated sections titled accordingly. --- Help/command/target_include_directories.rst | 3 +++ Help/command/target_link_libraries.rst | 9 ++++++--- Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst | 3 +++ Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst | 3 +++ Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst | 3 +++ Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst | 3 +++ 6 files changed, 21 insertions(+), 3 deletions(-) diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 1d236ce31..30ec2cb27 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -55,5 +55,8 @@ installation prefix. For example: $ # /include/mylib ) +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index e6a82b617..88a555aa4 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -49,9 +49,6 @@ CMake will also propagate :ref:`usage requirements ` from linked library targets. Usage requirements of dependencies affect compilation of sources in the ````. -.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` -.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt - If an ```` is a library in a Mac OX framework, the ``Headers`` directory of the framework will also be processed as a :ref:`usage requirement `. This has the same @@ -153,3 +150,9 @@ will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. + +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst index 1cfd7a85f..b1c40b224 100644 --- a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst @@ -22,5 +22,8 @@ installation prefix. For example: $ # /include/mylib ) +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index 55b7b8d40..832d12bbc 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -17,5 +17,8 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_LINK_LIBRARIES`` .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst index 2e859ebf7..2dcf45cbd 100644 --- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst @@ -24,5 +24,8 @@ property if policy :policy:`CMP0022` is ``NEW``. This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` instead. +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES`` .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst index 7f2b5dd94..22ee5a68b 100644 --- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst @@ -13,5 +13,8 @@ property if policy :policy:`CMP0022` is ``NEW``. This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` instead. +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES_`` .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt From 227992c3a693bb56ee6f6600a10c6eb19c6fb311 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 2 Apr 2015 16:12:00 -0400 Subject: [PATCH 4/5] Help: Reorganize and refine discussion of relocatable packages Re-organize the content added to the cmake-packages(7) manual by * commit v3.0.0-rc1~184^2 (Help: Document export(EXPORT) in the cmake-packages manual, 2013-12-23), * commit v3.0.0-rc1~154^2~1 (Help: Add notes about relocatability of config-file packages, 2014-01-07), and * commit v3.2.0-rc1~345^2 (Help: Warn that paths should not be used in INTERFACE_ build properties, 2014-11-22). These commits broke the natural flow of the original manual and made wording after the new content make less sense. Move the content into new subsections to restore the flow of the original manual and to make explicitly the purpose of the new content. Shorten the relocatable usage requirement "warnings". Refer to the new cmake-packages(7) manual subsection to reduce duplication. Also clarify the distinction between paths to library dependencies and paths to their header files. --- .../INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt | 38 ++--- .../INTERFACE_LINK_LIBRARIES_WARNING.txt | 25 +-- Help/manual/cmake-buildsystem.7.rst | 5 + Help/manual/cmake-packages.7.rst | 152 ++++++++++-------- 4 files changed, 106 insertions(+), 114 deletions(-) diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt index 33f71837e..a54d7280d 100644 --- a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt +++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt @@ -1,30 +1,18 @@ Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the -|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies. -That would hard-code into installed packages the include directory paths -for dependencies **as found on the machine the package was made on**. +|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include +directories of dependencies. That would hard-code into installed packages +the include directory paths for dependencies +**as found on the machine the package was made on**. The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only -suitable for specifying the required include directories of the target itself, -not its dependencies. +suitable for specifying the required include directories for headers +provided with the target itself, not those provided by the transitive +dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target +property. Those dependencies should themselves be targets that specify +their own header locations in |INTERFACE_PROPERTY_LINK|. -That is, code like this is incorrect for targets which will be used to -generate :manual:`cmake-packages(7)`: - -.. code-block:: cmake - - target_include_directories(mylib INTERFACE - $ - ) - -Dependencies must provide their own :ref:`IMPORTED targets ` -which have their own |INTERFACE_PROPERTY_LINK| populated -appropriately. Those :ref:`IMPORTED targets ` may then be -used with the :command:`target_link_libraries` command for ``mylib``. - -That way, when a consumer uses the installed package, the -consumer will run the appropriate :command:`find_package` command to find -the dependencies on their own machine and populate the -:ref:`IMPORTED targets ` with appropriate paths. See -:ref:`Creating Packages` for more. Note that many modules currently shipped -with CMake do not currently provide :ref:`IMPORTED targets `. +See the :ref:`Creating Relocatable Packages` section of the +:manual:`cmake-packages(7)` manual for discussion of additional care +that must be taken when specifying usage requirements while creating +packages for redistribution. diff --git a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt index ceefa4d2b..46e84ac22 100644 --- a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt +++ b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt @@ -1,23 +1,10 @@ Note that it is not advisable to populate the -|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies. -That would hard-code into installed packages the include directory paths +|INTERFACE_PROPERTY_LINK| of a target with absolute paths to dependencies. +That would hard-code into installed packages the library file paths for dependencies **as found on the machine the package was made on**. -That is, code like this is incorrect for targets which will be used to -generate :manual:`cmake-packages(7)`: - -.. code-block:: cmake - - target_link_libraries(mylib INTERFACE - ${Boost_LIBRARIES};${OtherDep_LIBRARIES} - ) - -Dependencies must provide their own :ref:`IMPORTED targets ` -which have their own :prop_tgt:`IMPORTED_LOCATION` populated -appropriately. That way, when a consumer uses the installed package, the -consumer will run the appropriate :command:`find_package` command to find -the dependencies on their own machine and populate the -:ref:`IMPORTED targets ` with appropriate paths. See -:ref:`Creating Packages` for more. Note that many modules currently shipped -with CMake do not currently provide :ref:`IMPORTED targets `. +See the :ref:`Creating Relocatable Packages` section of the +:manual:`cmake-packages(7)` manual for discussion of additional care +that must be taken when specifying usage requirements while creating +packages for redistribution. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 002f2c2e8..ae5e58e15 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -143,6 +143,11 @@ use particular :prop_tgt:`COMPILE_OPTIONS` or the properties must be **requirements**, not merely recommendations or convenience. +See the :ref:`Creating Relocatable Packages` section of the +:manual:`cmake-packages(7)` manual for discussion of additional care +that must be taken when specifying usage requirements while creating +packages for redistribution. + Target Properties ----------------- diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 6ee9df9a6..28c0798e4 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -373,38 +373,6 @@ attempt to use version 3 together with version 4. Packages can choose to employ such a pattern if different major versions of the package are designed to be incompatible. -Note that it is not advisable to populate any properties which may contain -paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and -:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies. -That would hard-code into installed packages the include directory or library -paths for dependencies **as found on the machine the package was made on**. - -That is, code like this is incorrect for targets which will be used to -generate config file packages: - -.. code-block:: cmake - - target_link_libraries(ClimbingStats INTERFACE - ${Boost_LIBRARIES} ${OtherDep_LIBRARIES} - ) - target_include_directories(ClimbingStats INTERFACE - "$" - ) - -Dependencies must provide their own :ref:`IMPORTED targets ` -which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and -:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those -:ref:`IMPORTED targets ` may then be -used with the :command:`target_link_libraries` command for ``ClimbingStats``. - -That way, when a consumer uses the installed package, the -consumer will run the appropriate :command:`find_package` command (via the -find_dependency macro described below) to find -the dependencies on their own machine and populate the -:ref:`IMPORTED targets ` with appropriate paths. Note that -many modules currently shipped with CMake do not currently provide -:ref:`IMPORTED targets `. - 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 @@ -418,6 +386,9 @@ directory in the :variable:`CMAKE_INSTALL_PREFIX`. When the ``IMPORTED`` target is used by downsteam, it automatically consumes the entries from that property. +Creating a Package Configuration File +------------------------------------- + In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as: .. code-block:: cmake @@ -429,44 +400,6 @@ 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. -Packages created by :command:`install(EXPORT)` are designed to be relocatable, -using paths relative to the location of the package itself. When defining -the interface of a target for ``EXPORT``, keep in mind that the include -directories should be specified as relative paths which are relative to the -:variable:`CMAKE_INSTALL_PREFIX`: - -.. code-block:: cmake - - target_include_directories(tgt INTERFACE - # Wrong, not relocatable: - $ - ) - - target_include_directories(tgt INTERFACE - # Ok, relocatable: - $ - ) - -The ``$`` -:manual:`generator expression ` may be used as -a placeholder for the install prefix without resulting in a non-relocatable -package. This is necessary if complex generator expressions are used: - -.. code-block:: cmake - - target_include_directories(tgt INTERFACE - # Ok, relocatable: - $:$/include/TgtName>> - ) - -The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets -definition file which is specific to the build-tree, and is not relocatable. -This can similiarly be used with a suitable package configuration file and -package version file to define a package for the build tree which may be used -without installation. Consumers of the build tree can simply ensure that the -:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the -``ClimbingStats_DIR`` to ``/ClimbingStats`` in the cache. - This can also be extended to cover dependencies: .. code-block:: cmake @@ -526,6 +459,85 @@ 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. +Creating a Package Configuration File for the Build Tree +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets +definition file which is specific to the build-tree, and is not relocatable. +This can similiarly be used with a suitable package configuration file and +package version file to define a package for the build tree which may be used +without installation. Consumers of the build tree can simply ensure that the +:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the +``ClimbingStats_DIR`` to ``/ClimbingStats`` in the cache. + +.. _`Creating Relocatable Packages`: + +Creating Relocatable Packages +----------------------------- + +Packages created by :command:`install(EXPORT)` are designed to be relocatable, +using paths relative to the location of the package itself. When defining +the interface of a target for ``EXPORT``, keep in mind that the include +directories should be specified as relative paths which are relative to the +:variable:`CMAKE_INSTALL_PREFIX`: + +.. code-block:: cmake + + target_include_directories(tgt INTERFACE + # Wrong, not relocatable: + $ + ) + + target_include_directories(tgt INTERFACE + # Ok, relocatable: + $ + ) + +The ``$`` +:manual:`generator expression ` may be used as +a placeholder for the install prefix without resulting in a non-relocatable +package. This is necessary if complex generator expressions are used: + +.. code-block:: cmake + + target_include_directories(tgt INTERFACE + # Ok, relocatable: + $:$/include/TgtName>> + ) + +This also applies to paths referencing external dependencies. +It is not advisable to populate any properties which may contain +paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and +:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies. +That would hard-code into installed packages the include directory or library +paths for dependencies **as found on the machine the package was made on**. + +That is, code like this is incorrect for targets which will be used to +generate config file packages: + +.. code-block:: cmake + + target_link_libraries(ClimbingStats INTERFACE + ${Boost_LIBRARIES} ${OtherDep_LIBRARIES} + ) + target_include_directories(ClimbingStats INTERFACE + "$" + ) + +Dependencies must provide their own :ref:`IMPORTED targets ` +which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and +:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those +:ref:`IMPORTED targets ` may then be +used with the :command:`target_link_libraries` command for ``ClimbingStats``. + +That way, when a consumer uses the installed package, the +consumer will run the appropriate :command:`find_package` command (via the +find_dependency macro described below) to find +the dependencies on their own machine and populate the +:ref:`IMPORTED targets ` with appropriate paths. Note that +many modules currently shipped with CMake do not currently provide +:ref:`IMPORTED targets `. + .. _`Package Registry`: Package Registry From 3af137824d993ca0a7c18c0768efb12b76154ad0 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 3 Apr 2015 09:57:05 -0400 Subject: [PATCH 5/5] Help: Update discussion of relocable packages in cmake-packages(7) Explain at the beginning of the section the requirements for a package to be relocatable to justify the rest of the section content. Generalize example to use fictional package names instead of real ones, especially because FindBoost provides no alternative yet. Reword the discussion to represent the preferred approach as "ideal" but also suggest workarounds when find modules do not provide the imported targets. --- Help/manual/cmake-packages.7.rst | 64 ++++++++++++++++++++++---------- 1 file changed, 45 insertions(+), 19 deletions(-) diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 28c0798e4..b9073a57c 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -475,6 +475,10 @@ without installation. Consumers of the build tree can simply ensure that the Creating Relocatable Packages ----------------------------- +A relocatable package must not reference absolute paths of files on +the machine where the package is built that will not exist on the +machines where the package may be installed. + Packages created by :command:`install(EXPORT)` are designed to be relocatable, using paths relative to the location of the package itself. When defining the interface of a target for ``EXPORT``, keep in mind that the include @@ -509,34 +513,56 @@ This also applies to paths referencing external dependencies. It is not advisable to populate any properties which may contain paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies. -That would hard-code into installed packages the include directory or library -paths for dependencies **as found on the machine the package was made on**. - -That is, code like this is incorrect for targets which will be used to -generate config file packages: +For example, this code may not work well for a relocatable package: .. code-block:: cmake target_link_libraries(ClimbingStats INTERFACE - ${Boost_LIBRARIES} ${OtherDep_LIBRARIES} + ${Foo_LIBRARIES} ${Bar_LIBRARIES} ) target_include_directories(ClimbingStats INTERFACE - "$" + "$" ) -Dependencies must provide their own :ref:`IMPORTED targets ` -which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and -:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those -:ref:`IMPORTED targets ` may then be -used with the :command:`target_link_libraries` command for ``ClimbingStats``. +The referenced variables may contain the absolute paths to libraries +and include directories **as found on the machine the package was made on**. +This would create a package with hard-coded paths to dependencies and not +suitable for relocation. -That way, when a consumer uses the installed package, the -consumer will run the appropriate :command:`find_package` command (via the -find_dependency macro described below) to find -the dependencies on their own machine and populate the -:ref:`IMPORTED targets ` with appropriate paths. Note that -many modules currently shipped with CMake do not currently provide -:ref:`IMPORTED targets `. +Ideally such dependencies should be used through their own +:ref:`IMPORTED targets ` that have their own +:prop_tgt:`IMPORTED_LOCATION` and usage requirement properties +such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated +appropriately. Those imported targets may then be used with +the :command:`target_link_libraries` command for ``ClimbingStats``: + +.. code-block:: cmake + + target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar) + +With this approach the package references its external dependencies +only through the names of :ref:`IMPORTED targets `. +When a consumer uses the installed package, the consumer will run the +appropriate :command:`find_package` commands (via the ``find_dependency`` +macro described above) to find the dependencies and populate the +imported targets with appropriate paths on their own machine. + +Unfortunately many :manual:`modules ` shipped with +CMake do not yet provide :ref:`IMPORTED targets ` +because their development pre-dated this approach. This may improve +incrementally over time. Workarounds to create relocatable packages +using such modules include: + +* When building the package, specify each ``Foo_LIBRARY`` cache + entry as just a library name, e.g. ``-DFoo_LIBRARY=foo``. This + tells the corresponding find module to populate the ``Foo_LIBRARIES`` + with just ``foo`` to ask the linker to search for the library + instead of hard-coding a path. + +* Or, after installing the package content but before creating the + package installation binary for redistribution, manually replace + the absolute paths with placeholders for substitution by the + installation tool when the package is installed. .. _`Package Registry`: