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.
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.
This reverts commit cfab942e5f.
Since commit v2.8.11~362^2 (Generate an early-return guard in target
Export files, 2012-11-30) an external include guard is not needed.
When a project is packaged for redistribution the local package
registries should not be updated or consulted. They are for developers.
Add variables to disable use of package registries globally:
* CMAKE_EXPORT_NO_PACKAGE_REGISTRY that disables the export(PACKAGE)
command
* CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY that disables the User Package
Registry in all the find_package calls.
* CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY that disables the
System Package Registry in all the find_package calls.
Update documentation and unit tests.
There is not really any need to. Downstreams can either rely on it
being provided by CMake, or copy and distribute it.
Change the documented include for the find_dependency macro.
Brad King
Stephen Kelly
Iosif Neitzke
Daniele E. Domenichelli