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/command/project.rst | 2 | ||||
| -rw-r--r-- | Help/command/target_link_libraries.rst | 24 | ||||
| -rw-r--r-- | Help/envvar/CTEST_PROGRESS_OUTPUT.rst | 14 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 21 | ||||
| -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 |
12 files changed, 166 insertions, 72 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/command/project.rst b/Help/command/project.rst index c1de057..bd8b4ef 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -44,6 +44,7 @@ Variables corresponding to unspecified versions are set to the empty string If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION` and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument. +These variables will be cleared if ``DESCRIPTION`` is not given. The description is expected to be a relatively short string, usually no more than a few words. @@ -51,6 +52,7 @@ The optional ``HOMEPAGE_URL`` sets the analogous variables :variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`. When this option is given, the URL provided should be the canonical home for the project. +These variables will be cleared if ``HOMEPAGE_URL`` is not given. Note that the description and homepage URL may be used as defaults for things like packaging meta-data, documentation, etc. diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index e1c374e..229d10c 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -78,6 +78,20 @@ Each ``<item>`` may be: flags explicitly. The flags will then be placed at the toolchain-defined flag position in the link command. +* **A generator expression**: A ``$<...>`` :manual:`generator expression + <cmake-generator-expressions(7)>` may evaluate to any of the above + items or to a :ref:`;-list <CMake Language Lists>` of them. + If the ``...`` contains any ``;`` characters, e.g. after evaluation + of a ``${list}`` variable, be sure to use an explicitly quoted + argument ``"$<...>"`` so that this command receives it as a + single ``<item>``. + + Additionally, a generator expression may be used as a fragment of + any of the above items, e.g. ``foo$<1:_d>``. + + Note that generator expressions will not be used in OLD handling of + policy :policy:`CMP0003` or policy :policy:`CMP0004`. + * A ``debug``, ``optimized``, or ``general`` keyword immediately followed by another ``<item>``. The item following such a keyword will be used only for the corresponding build configuration. The ``debug`` keyword @@ -88,18 +102,16 @@ Each ``<item>`` may be: optional. Higher granularity may be achieved for per-configuration rules by creating and linking to :ref:`IMPORTED library targets <Imported Targets>`. + These keywords are interpreted immediately by this command and therefore + have no special meaning when produced by a generator expression. Items containing ``::``, such as ``Foo::Bar``, are assumed to be :ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library target names and will cause an error if no such target exists. See policy :policy:`CMP0028`. -Arguments to ``target_link_libraries`` may use "generator expressions" -with the syntax ``$<...>``. Note however, that generator expressions -will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. -See the :manual:`cmake-generator-expressions(7)` manual for available -expressions. See the :manual:`cmake-buildsystem(7)` manual for more on -defining buildsystem properties. +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. Libraries for a Target and/or its Dependents ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/envvar/CTEST_PROGRESS_OUTPUT.rst b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst new file mode 100644 index 0000000..a8e15bc --- /dev/null +++ b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst @@ -0,0 +1,14 @@ +CTEST_PROGRESS_OUTPUT +--------------------- + +Boolean environment variable that affects how :manual:`ctest <ctest(1)>` +command output reports overall progress. When set to 1, TRUE, ON or anything +else that evaluates to boolean true, progress is reported by repeatedly +updating the same line. This greatly reduces the overall verbosity, but is +only supported when output is sent directly to a terminal. If the environment +variable is not set or has a value that evaluates to false, output is reported +normally with each test having its own start and end lines logged to the +output. + +The ``--progress`` option to :manual:`ctest <ctest(1)>` overrides this +environment variable if both are given. diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 42aeabc..31aa723 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -53,5 +53,6 @@ Environment Variables for CTest /envvar/CTEST_INTERACTIVE_DEBUG_MODE /envvar/CTEST_OUTPUT_ON_FAILURE /envvar/CTEST_PARALLEL_LEVEL + /envvar/CTEST_PROGRESS_OUTPUT /envvar/CTEST_USE_LAUNCHERS_DEFAULT /envvar/DASHBOARD_TEST_FROM_CTEST diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 9553d15..e24b10d 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -35,6 +35,19 @@ Options which one should be tested. Example configurations are "Debug" and "Release". +``--progress`` + Enable short progress output from tests. + + When the output of ``ctest`` is being sent directly to a terminal, the + progress through the set of tests is reported by updating the same line + rather than printing start and end messages for each test on new lines. + This can significantly reduce the verbosity of the test output. + Test completion messages are still output on their own line for failed + tests and the final test summary will also still be logged. + + This option can also be enabled by setting the environment variable + :envvar:`CTEST_PROGRESS_OUTPUT`. + ``-V,--verbose`` Enable verbose output from tests. @@ -55,8 +68,8 @@ Options ``--output-on-failure`` Output anything outputted by the test program if the test should fail. - This option can also be enabled by setting the environment variable - ``CTEST_OUTPUT_ON_FAILURE``. + This option can also be enabled by setting the + :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable ``-F`` Enable failover. @@ -70,7 +83,7 @@ Options This option tells CTest to run the tests in parallel using given number of jobs. This option can also be set by setting the - environment variable ``CTEST_PARALLEL_LEVEL``. + :envvar:`CTEST_PARALLEL_LEVEL` environment variable. This option can be used with the :prop_test:`PROCESSORS` test property. @@ -867,7 +880,7 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE` * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``, - initialized by the ``CMAKE_CONFIG_TYPE`` environment variable + initialized by the :envvar:`CMAKE_CONFIG_TYPE` environment variable ``LabelsForSubprojects`` Specify a semicolon-separated list of labels that will be treated as 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. |