"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "Help/command/find_package.rst" between
cmake-3.13.4.tar.gz and cmake-3.14.0-rc1.tar.gz

About: CMake is a cross-platform build system designed to build, test and package software. Release candidate.

find_package.rst  (cmake-3.13.4):find_package.rst  (cmake-3.14.0-rc1)
skipping to change at line 15 skipping to change at line 15
.. contents:: .. contents::
Find an external project, and load its settings. Find an external project, and load its settings.
.. _`basic signature`: .. _`basic signature`:
Basic Signature and Module Mode Basic Signature and Module Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:: .. code-block:: cmake
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
[REQUIRED] [[COMPONENTS] [components...]] [REQUIRED] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...] [OPTIONAL_COMPONENTS components...]
[NO_POLICY_SCOPE]) [NO_POLICY_SCOPE])
Finds and loads settings from an external project. ``<PackageName>_FOUND`` Finds and loads settings from an external project. ``<PackageName>_FOUND``
will be set to indicate whether the package was found. When the will be set to indicate whether the package was found. When the
package is found package-specific information is provided through package is found package-specific information is provided through
variables and :ref:`Imported Targets` documented by the package itself. The variables and :ref:`Imported Targets` documented by the package itself. The
``QUIET`` option disables messages if the package cannot be found. The ``QUIET`` option disables informational messages, including those indicating
``REQUIRED`` option stops processing with an error message if the package that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED``
cannot be found. option stops processing with an error message if the package cannot be found.
A package-specific list of required components may be listed after the A package-specific list of required components may be listed after the
``COMPONENTS`` option (or after the ``REQUIRED`` option if present). ``COMPONENTS`` option (or after the ``REQUIRED`` option if present).
Additional optional components may be listed after Additional optional components may be listed after
``OPTIONAL_COMPONENTS``. Available components and their influence on ``OPTIONAL_COMPONENTS``. Available components and their influence on
whether a package is considered to be found are defined by the target whether a package is considered to be found are defined by the target
package. package.
The ``[version]`` argument requests a version with which the package found The ``[version]`` argument requests a version with which the package found
should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The
skipping to change at line 54 skipping to change at line 54
package-by-package basis (see the `Version Selection`_ section below). package-by-package basis (see the `Version Selection`_ section below).
See the :command:`cmake_policy` command documentation for discussion See the :command:`cmake_policy` command documentation for discussion
of the ``NO_POLICY_SCOPE`` option. of the ``NO_POLICY_SCOPE`` option.
The command has two modes by which it searches for packages: "Module" The command has two modes by which it searches for packages: "Module"
mode and "Config" mode. The above signature selects Module mode. mode and "Config" mode. The above signature selects Module mode.
If no module is found the command falls back to Config mode, described 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. below. This fall back is disabled if the ``MODULE`` option is given.
In Module mode, CMake searches for a file called ``Find<PackageName>.cmake`` In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``.
in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation. The file is first searched in the :variable:`CMAKE_MODULE_PATH`,
then among the :ref:`Find Modules` provided by the CMake installation.
If the file is found, it is read and processed by CMake. It is responsible 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 for finding the package, checking the version, and producing any needed
messages. Some find-modules provide limited or no support for versioning; messages. Some find-modules provide limited or no support for versioning;
check the module documentation. check the module documentation.
Full Signature and Config Mode Full Signature and Config Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
User code should generally look for packages using the above `basic User code should generally look for packages using the above `basic
signature`_. The remainder of this command documentation specifies the signature`_. The remainder of this command documentation specifies the
full command signature and details of the search process. Project full command signature and details of the search process. Project
maintainers wishing to provide a package to be found by this command maintainers wishing to provide a package to be found by this command
are encouraged to read on. are encouraged to read on.
The complete Config mode command signature is:: The complete Config mode command signature is
.. code-block:: cmake
find_package(<PackageName> [version] [EXACT] [QUIET] find_package(<PackageName> [version] [EXACT] [QUIET]
[REQUIRED] [[COMPONENTS] [components...]] [REQUIRED] [[COMPONENTS] [components...]]
[CONFIG|NO_MODULE] [CONFIG|NO_MODULE]
[NO_POLICY_SCOPE] [NO_POLICY_SCOPE]
[NAMES name1 [name2 ...]] [NAMES name1 [name2 ...]]
[CONFIGS config1 [config2 ...]] [CONFIGS config1 [config2 ...]]
[HINTS path1 [path2 ... ]] [HINTS path1 [path2 ... ]]
[PATHS path1 [path2 ... ]] [PATHS path1 [path2 ... ]]
[PATH_SUFFIXES suffix1 [suffix2 ...]] [PATH_SUFFIXES suffix1 [suffix2 ...]]
skipping to change at line 205 skipping to change at line 208
and the corresponding package configuration file is loaded. and the corresponding package configuration file is loaded.
When multiple package configuration files are available whose version files When multiple package configuration files are available whose version files
claim compatibility with the version requested it is unspecified which claim compatibility with the version requested it is unspecified which
one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
is set no attempt is made to choose a highest or closest version number. is set no attempt is made to choose a highest or closest version number.
To control the order in which ``find_package`` checks for compatibility use To control the order in which ``find_package`` checks for compatibility use
the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
For instance in order to select the highest version one can set:: For instance in order to select the highest version one can set
.. code-block:: cmake
SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
before calling ``find_package``. before calling ``find_package``.
Search Procedure Search Procedure
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
CMake constructs a set of possible installation prefixes for the CMake constructs a set of possible installation prefixes for the
skipping to change at line 289 skipping to change at line 294
variable and the :envvar:`<PackageName>_ROOT` environment variable, variable and the :envvar:`<PackageName>_ROOT` environment variable,
where ``<PackageName>`` is the package to be found. where ``<PackageName>`` is the package to be found.
The package root variables are maintained as a stack so if The package root variables are maintained as a stack so if
called from within a find module, root paths from the parent's find called from within a find module, root paths from the parent's find
module will also be searched after paths for the current package. module will also be searched after paths for the current package.
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
See policy :policy:`CMP0074`. See policy :policy:`CMP0074`.
2. Search paths specified in cmake-specific cache variables. These 2. Search paths specified in cmake-specific cache variables. These
are intended to be used on the command line with a ``-DVAR=value``. are intended to be used on the command line with a ``-DVAR=value``.
The values are interpreted as :ref:`;-lists <CMake Language Lists>`. The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed:: This can be skipped if ``NO_CMAKE_PATH`` is passed::
CMAKE_PREFIX_PATH CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH CMAKE_APPBUNDLE_PATH
3. Search paths specified in cmake-specific environment variables. 3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration, These are intended to be set in the user's shell configuration,
and therefore use the host's native path separator and therefore use the host's native path separator
(``;`` on Windows and ``:`` on UNIX). (``;`` on Windows and ``:`` on UNIX).
skipping to change at line 352 skipping to change at line 357
hard-coded guesses. hard-coded guesses.
.. |FIND_XXX| replace:: find_package .. |FIND_XXX| replace:: find_package
.. |FIND_ARGS_XXX| replace:: <PackageName> .. |FIND_ARGS_XXX| replace:: <PackageName>
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
.. include:: FIND_XXX_ROOT.txt .. include:: FIND_XXX_ROOT.txt
.. include:: FIND_XXX_ORDER.txt .. include:: FIND_XXX_ORDER.txt
By default the value stored in the result variable will be the path at
which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS`
variable may be set to ``TRUE`` before calling ``find_package`` in order
to resolve symbolic links and store the real path to the file.
Every non-REQUIRED ``find_package`` call can be disabled by setting the Every non-REQUIRED ``find_package`` call can be disabled by setting the
:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``.
Package File Interface Variables Package File Interface Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When loading a find module or package configuration file ``find_package`` When loading a find module or package configuration file ``find_package``
defines variables to provide information about the call arguments (and defines variables to provide information about the call arguments (and
restores their original state before returning): restores their original state before returning):
 End of changes. 7 change blocks. 
9 lines changed or deleted 19 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)