diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/find_package.rst | 83 | ||||
| -rw-r--r-- | Help/command/list.rst | 26 | ||||
| -rw-r--r-- | Help/policy/CMP0077.rst | 44 | ||||
| -rw-r--r-- | Help/release/3.13.rst | 12 | ||||
| -rw-r--r-- | Help/variable/CMAKE_OSX_VARIABLE.txt | 2 |
5 files changed, 114 insertions, 53 deletions
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index b486b79..3ad571c 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,7 +1,16 @@ find_package ------------ -Load settings for an external project. +.. only:: html + + .. contents:: + +Find an external project, and load its settings. + +.. _`basic signature`: + +Basic Signature and Module Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -15,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. @@ -33,25 +41,32 @@ 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). -User code should generally look for packages using the above simple -signature. The remainder of this command documentation specifies the +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<PackageName>.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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 -called ``Find<PackageName>.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(<PackageName> [version] [EXACT] [QUIET] @@ -76,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 reduced -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 ``<PackageName>_DIR`` is created to hold the directory containing the file. By default the command searches for a package with the name ``<PackageName>``. If the ``NAMES`` option @@ -107,6 +122,13 @@ fatal error is generated and the configure step stops executing. If ``<PackageName>_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 +^^^^^^^^^^^^^^^^^ + 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`` @@ -187,17 +209,8 @@ 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(<PackageName> [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 +^^^^^^^^^^^^^^^^ CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a @@ -339,6 +352,9 @@ enabled. Every non-REQUIRED ``find_package`` call can be disabled by setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` 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): @@ -377,6 +393,3 @@ configuration file to handle components in a way that makes sense for the package. The package configuration file may set ``<PackageName>_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. diff --git a/Help/command/list.rst b/Help/command/list.rst index ad2c428..2357a9b 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -256,20 +256,24 @@ Reverses the contents of the list in-place. list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) Sorts the list in-place alphabetically. -Use the option ``<compare>`` to select the compare type for sorting. -The ``<compare>`` option may be one of: +Use the ``COMPARE`` keyword to select the comparison method for sorting. +The ``<compare>`` option should be one of: -* ``STRING``: Sorts a list of strings alphabetically. -* ``FILE_BASENAME``: Sort a list of pathnames of files by their basenames. +* ``STRING``: Sorts a list of strings alphabetically. This is the + default behavior if the ``COMPARE`` option is not given. +* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames. -Use the option ``<case>`` to select a case sensitive or case insensitive sort mode. -The ``<case>`` option may be one of: +Use the ``CASE`` keyword to select a case sensitive or case insensitive +sort mode. The ``<case>`` option should be one of: -* ``SENSITIVE``: Sorts the list alphabetically. -* ``INSENSITIVE``: Sorts the list alphabetically in descending order. +* ``SENSITIVE``: List items are sorted in a case-sensitive manner. This is + the default behavior if the ``CASE`` option is not given. +* ``INSENSITIVE``: List items are sorted case insensitively. The order of + items which differ only by upper/lowercase is not specified. -Use the option ``<order>`` to select a case sensitive or case insensitive sort mode. -The ``<order>`` option may be one of: +To control the sort order, the ``ORDER`` keyword can be given. +The ``<order>`` option should be one of: -* ``ASCENDING``: Sorts the list in ascending order. +* ``ASCENDING``: Sorts the list in ascending order. This is the default + behavior when the ``ORDER`` option is not given. * ``DESCENDING``: Sorts the list in descending order. diff --git a/Help/policy/CMP0077.rst b/Help/policy/CMP0077.rst index 8efe198..44797b6 100644 --- a/Help/policy/CMP0077.rst +++ b/Help/policy/CMP0077.rst @@ -3,10 +3,46 @@ CMP0077 :command:`option` honors normal variables. -The ``OLD`` behavior for this policy is to clear any existing normal variables -with the same name. The ``NEW`` behavior for this policy is to not create -a cache entry or modify any existing normal variables if a normal variable -with the same name already exists. +The :command:`option` command is typically used to create a cache entry +to allow users to set the option. However, there are cases in which a +normal (non-cached) variable of the same name as the option may be +defined by the project prior to calling the :command:`option` command. +For example, a project that embeds another project as a subdirectory +may want to hard-code options of the subproject to build the way it needs. + +For historical reasons in CMake 3.12 and below the :command:`option` +command *removes* a normal (non-cached) variable of the same name when: + +* a cache entry of the specified name does not exist at all, or +* a cache entry of the specified name exists but has not been given + a type (e.g. via ``-D<name>=ON`` on the command line). + +In both of these cases (typically on the first run in a new build tree), +the :command:`option` command gives the cache entry type ``BOOL`` and +removes any normal (non-cached) variable of the same name. In the +remaining case that the cache entry of the specified name already +exists and has a type (typically on later runs in a build tree), the +:command:`option` command changes nothing and any normal variable of +the same name remains set. + +In CMake 3.13 and above the :command:`option` command prefers to +do nothing when a normal variable of the given name already exists. +It does not create or update a cache entry or remove the normal variable. +The new behavior is consistent between the first and later runs in a +build tree. This policy provides compatibility with projects that have +not been updated to expect the new behavior. + +When the :command:`option` command sees a normal variable of the given +name: + +* The ``OLD`` behavior for this policy is to proceed even when a normal + variable of the same name exists. If the cache entry does not already + exist and have a type then it is created and/or given a type and the + normal variable is removed. + +* The ``NEW`` behavior for this policy is to do nothing when a normal + variable of the same name exists. The normal variable is not removed. + The cache entry is not created or updated and is ignored if it exists. This policy was introduced in CMake version 3.13. CMake version |release| warns when the policy is not set and uses ``OLD`` behavior. diff --git a/Help/release/3.13.rst b/Help/release/3.13.rst index b08f21d..b993775 100644 --- a/Help/release/3.13.rst +++ b/Help/release/3.13.rst @@ -20,7 +20,7 @@ Generators * The :generator:`Xcode` generator learned to configure more Xcode Scheme fields. See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable. -* The :generator:`Green Hills MULTI` generator has been udpated: +* The :generator:`Green Hills MULTI` generator has been updated: - Added support for architecture selection through :variable:`CMAKE_GENERATOR_PLATFORM`: @@ -157,6 +157,10 @@ Modules * The :module:`FindPkgConfig` module gained an option to create imported targets in global scope. +* The :module:`FindPkgConfig` module gained support for ``<`` and ``>`` + operators for version checks in addition to the already supported + operators ``>=``, ``<=``, and ``=``. + * Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` gain capability to control order of resource lookup on macOS (Framework) and Windows (Registry). @@ -203,8 +207,10 @@ Deprecated and Removed Features Other Changes ============= -* The :command:`option` command now honors existing normal variables instead - of replacing them with a cache entry. See policy :policy:`CMP0077`. +* The :command:`option` command now honors an existing normal variable + of the same name and does nothing instead of possibly creating a cache + entry (or setting its type) and removing the normal variable. + See policy :policy:`CMP0077`. * The :ref:`Makefile Generators` learned to remove custom command and custom target byproducts during ``make clean``. diff --git a/Help/variable/CMAKE_OSX_VARIABLE.txt b/Help/variable/CMAKE_OSX_VARIABLE.txt index 5b84726..16f3c1a 100644 --- a/Help/variable/CMAKE_OSX_VARIABLE.txt +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -2,6 +2,8 @@ The value of this variable should be set prior to the first :command:`project` or :command:`enable_language` command invocation because it may influence configuration of the toolchain and flags. It is intended to be set locally by the user creating a build tree. +This variable should be set as a ``CACHE`` entry (or else CMake may +remove it while initializing a cache entry of the same name). Despite the ``OSX`` part in the variable name(s) they apply also to other SDKs than macOS like iOS, tvOS, or watchOS. |