Help: Add a CMake manual for Packages related docs.

Help/index.rst

@@ -28,6 +28,7 @@ Reference Manuals
    /manual/cmake-commands.7
    /manual/cmake-generators.7
    /manual/cmake-modules.7
+   /manual/cmake-packages.7
    /manual/cmake-policies.7
    /manual/cmake-properties.7
    /manual/cmake-variables.7

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.