From 463d59d3311f344f85cbc87cbe61e562cb5c80ce Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Thu, 4 Oct 2018 09:04:14 +0200 Subject: Help: Rephrase summary in find_package command docs --- Help/command/find_package.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index b486b79..07e1cc2 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,7 +1,7 @@ find_package ------------ -Load settings for an external project. +Find an external project, and load its settings. :: -- cgit v0.12 From 336dce1c95d6605181456f8ca7e702ffe0f790c4 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Thu, 4 Oct 2018 09:29:12 +0200 Subject: Help: Add table of contents to find_package command docs --- Help/command/find_package.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 07e1cc2..041d5df 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,6 +1,10 @@ find_package ------------ +.. only:: html + + .. contents:: + Find an external project, and load its settings. :: -- cgit v0.12 From 56310b06713c452eb17bcc90683c0bdb4270e9a9 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Thu, 4 Oct 2018 10:50:25 +0200 Subject: Help: Move find_package NO_POLICY_SCOPE to more appropriate location --- Help/command/find_package.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 041d5df..67a2db7 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -39,6 +39,9 @@ automatically from the outer call (including the ``EXACT`` flag for ``[version]``). Version support is currently provided only on a package-by-package basis (details below). +See the :command:`cmake_policy` command documentation for discussion +of the ``NO_POLICY_SCOPE`` option. + User code should generally look for packages using the above simple signature. The remainder of this command documentation specifies the full command signature and details of the search process. Project @@ -381,6 +384,3 @@ configuration file to handle components in a way that makes sense for the package. The package configuration file may set ``_FOUND`` to false to tell ``find_package`` that component requirements are not satisfied. - -See the :command:`cmake_policy` command documentation for discussion -of the ``NO_POLICY_SCOPE`` option. -- cgit v0.12 From aaf5ea2d7034eb42659e985ae5bd51dde3625134 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Wed, 3 Oct 2018 21:37:32 +0200 Subject: Help: Add section headers to find_package command The document is pretty long but is already mostly organized into sections. Add explicit section headers. --- Help/command/find_package.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 67a2db7..d54b514 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -7,6 +7,9 @@ find_package Find an external project, and load its settings. +Basic Signature and Module Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + :: find_package( [version] [EXACT] [QUIET] [MODULE] @@ -42,6 +45,9 @@ package-by-package basis (details below). See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. +Full Signature and Config Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + User code should generally look for packages using the above simple signature. The remainder of this command documentation specifies the full command signature and details of the search process. Project @@ -114,6 +120,9 @@ fatal error is generated and the configure step stops executing. If ``_DIR`` has been set to a directory not containing a configuration file CMake will ignore it and search from scratch. +Version Selection +^^^^^^^^^^^^^^^^^ + When the ``[version]`` argument is given Config mode will only find a version of the package that claims compatibility with the requested version (format is ``major[.minor[.patch[.tweak]]]``). If the ``EXACT`` @@ -206,6 +215,9 @@ package configuration files are encouraged to name and install them such that the procedure outlined below will find them without requiring use of additional options. +Search Procedure +^^^^^^^^^^^^^^^^ + CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a configuration file. The tables below show the directories searched. @@ -346,6 +358,9 @@ enabled. Every non-REQUIRED ``find_package`` call can be disabled by setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_` variable to ``TRUE``. +Package File Interface Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + When loading a find module or package configuration file ``find_package`` defines variables to provide information about the call arguments (and restores their original state before returning): -- cgit v0.12 From 11058a2e7cd3e673cc72d0f5bb1b214b4ecb4ad3 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Thu, 4 Oct 2018 09:53:50 +0200 Subject: Help: Add internal section link to find_package command docs --- Help/command/find_package.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index d54b514..1db386b 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -7,6 +7,8 @@ find_package Find an external project, and load its settings. +.. _`basic signature`: + Basic Signature and Module Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -40,7 +42,7 @@ should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The inside a find-module, the corresponding arguments are forwarded automatically from the outer call (including the ``EXACT`` flag for ``[version]``). Version support is currently provided only on a -package-by-package basis (details below). +package-by-package basis (see the `Version Selection`_ section below). See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. @@ -48,15 +50,15 @@ of the ``NO_POLICY_SCOPE`` option. Full Signature and Config Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -User code should generally look for packages using the above simple -signature. The remainder of this command documentation specifies the +User code should generally look for packages using the above `basic +signature`_. The remainder of this command documentation specifies the full command signature and details of the search process. Project maintainers wishing to provide a package to be found by this command are encouraged to read on. The command has two modes by which it searches for packages: "Module" mode and "Config" mode. Module mode is available when the command is -invoked with the above reduced signature. CMake searches for a file +invoked with the above `basic signature`_. CMake searches for a file called ``Find.cmake`` in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation. If the file is found, it is read and processed by CMake. It is responsible for finding the package, @@ -91,8 +93,8 @@ The complete Config mode command signature is:: The ``CONFIG`` option may be used to skip Module mode explicitly and switch to Config mode. It is synonymous to using ``NO_MODULE``. Config -mode is also implied by use of options not specified in the reduced -signature. +mode is also implied by use of options not specified in the `basic +signature`_. Config mode attempts to locate a configuration file provided by the package to be found. A cache entry called ``_DIR`` is created to -- cgit v0.12 From 26dac50220ec677229c9569be959b9306c9967e2 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 4 Oct 2018 15:01:59 -0400 Subject: Help: Remove redundant recommendation We suggest that users prefer the basic signature in two places. Drop the latter and move its related content to a better section. --- Help/command/find_package.rst | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 1db386b..aba80b2 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -122,6 +122,10 @@ fatal error is generated and the configure step stops executing. If ``_DIR`` has been set to a directory not containing a configuration file CMake will ignore it and search from scratch. +Package maintainers providing CMake package configuration files are +encouraged to name and install them such that the `Search Procedure`_ +outlined below will find them without requiring use of additional options. + Version Selection ^^^^^^^^^^^^^^^^^ @@ -205,18 +209,6 @@ For instance in order to select the highest version one can set:: before calling ``find_package``. -Config mode provides an elaborate interface and search procedure. -Much of the interface is provided for completeness and for use -internally by find-modules loaded by Module mode. Most user code -should simply call:: - - find_package( [major[.minor]] [EXACT] [REQUIRED|QUIET]) - -in order to find a package. Package maintainers providing CMake -package configuration files are encouraged to name and install them -such that the procedure outlined below will find them without -requiring use of additional options. - Search Procedure ^^^^^^^^^^^^^^^^ -- cgit v0.12 From c90f3dff82e7b0fb3cd21a60df3b2ce1f268b70e Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Thu, 4 Oct 2018 11:39:42 +0200 Subject: Help: Clarify find_package Module and Config mode relation --- Help/command/find_package.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index aba80b2..3ad571c 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -24,7 +24,6 @@ will be set to indicate whether the package was found. When the package is found package-specific information is provided through variables and :ref:`Imported Targets` documented by the package itself. The ``QUIET`` option disables messages if the package cannot be found. The -``MODULE`` option disables the second signature documented below. The ``REQUIRED`` option stops processing with an error message if the package cannot be found. @@ -47,6 +46,18 @@ package-by-package basis (see the `Version Selection`_ section below). See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. +The command has two modes by which it searches for packages: "Module" +mode and "Config" mode. The above signature selects Module mode. +If no module is found the command falls back to Config mode, described +below. This fall back is disabled if the ``MODULE`` option is given. + +In Module mode, CMake searches for a file called ``Find.cmake`` +in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation. +If the file is found, it is read and processed by CMake. It is responsible +for finding the package, checking the version, and producing any needed +messages. Some find-modules provide limited or no support for versioning; +check the module documentation. + Full Signature and Config Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -56,17 +67,6 @@ full command signature and details of the search process. Project maintainers wishing to provide a package to be found by this command are encouraged to read on. -The command has two modes by which it searches for packages: "Module" -mode and "Config" mode. Module mode is available when the command is -invoked with the above `basic signature`_. CMake searches for a file -called ``Find.cmake`` in the :variable:`CMAKE_MODULE_PATH` -followed by the CMake installation. If the file is found, it is read -and processed by CMake. It is responsible for finding the package, -checking the version, and producing any needed messages. Many -find-modules provide limited or no support for versioning; check -the module documentation. If no module is found and the ``MODULE`` -option is not given the command proceeds to Config mode. - The complete Config mode command signature is:: find_package( [version] [EXACT] [QUIET] @@ -91,12 +91,12 @@ The complete Config mode command signature is:: ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH]) -The ``CONFIG`` option may be used to skip Module mode explicitly and -switch to Config mode. It is synonymous to using ``NO_MODULE``. Config -mode is also implied by use of options not specified in the `basic -signature`_. +The ``CONFIG`` option, the synonymous ``NO_MODULE`` option, or the use +of options not specified in the `basic signature`_ all enforce pure Config +mode. In pure Config mode, the command skips Module mode search and +proceeds at once with Config mode search. -Config mode attempts to locate a configuration file provided by the +Config mode search attempts to locate a configuration file provided by the package to be found. A cache entry called ``_DIR`` is created to hold the directory containing the file. By default the command searches for a package with the name ````. If the ``NAMES`` option -- cgit v0.12