diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/find_package.rst | 83 | ||||
| -rw-r--r-- | Help/policy/CMP0077.rst | 44 | ||||
| -rw-r--r-- | Help/release/3.13.rst | 12 | ||||
| -rw-r--r-- | Help/release/dev/0-sample-topic.rst | 7 | ||||
| -rw-r--r-- | Help/release/index.rst | 2 | ||||
| -rw-r--r-- | Help/variable/CMAKE_OSX_VARIABLE.txt | 2 |
6 files changed, 99 insertions, 51 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/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/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst deleted file mode 100644 index e4cc01e..0000000 --- a/Help/release/dev/0-sample-topic.rst +++ /dev/null @@ -1,7 +0,0 @@ -0-sample-topic --------------- - -* This is a sample release note for the change in a topic. - Developers should add similar notes for each topic branch - making a noteworthy change. Each document should be named - and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/index.rst b/Help/release/index.rst index 7ef3a8e..fbe4cf6 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,8 +7,6 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. -.. include:: dev.txt - Releases ======== 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. |