diff options
Diffstat (limited to 'Help')
36 files changed, 295 insertions, 107 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index fc8c55e..40f1c1a 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -90,7 +90,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting - the :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` to ``FALSE``. + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. See policy :policy:`CMP0074`. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index e6ad037..14f879d 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -80,7 +80,9 @@ Options: ``COMMAND_ECHO <where>`` The command being run will be echo'ed to ``<where>`` with ``<where>`` - being set to ``STDERR``|``STDOUT``|``NONE``. + being set to one of ``STDERR``, ``STDOUT`` or ``NONE``. + See the :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable for a way + to control the default behavior when this option is not present. ``ENCODING <name>`` On Windows, the encoding that is used to decode output from the process. diff --git a/Help/command/file.rst b/Help/command/file.rst index 666a532..c06451a 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -503,6 +503,11 @@ regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given path. The results will be ordered lexicographically. +On Windows and macOS, globbing is case-insensitive even if the underlying +filesystem is case-sensitive (both filenames and globbing expressions are +converted to lowercase before matching). On other platforms, globbing is +case-sensitive. + If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic to the main build system check target to rerun the flagged ``GLOB`` commands at build time. If any of the outputs change, CMake will regenerate the build diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index e5e5b2c..6e1d232 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -330,8 +330,10 @@ enabled. 6. Search paths stored in the CMake :ref:`User Package Registry`. This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by - setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` - to ``TRUE``. + setting the variable :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` + to ``FALSE`` or the deprecated variable + :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the user package registry. diff --git a/Help/command/list.rst b/Help/command/list.rst index 4444af7..39e7e2a 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -207,84 +207,81 @@ but if duplicates are encountered, only the first instance is preserved. [OUTPUT_VARIABLE <output variable>]) Transforms the list by applying an action to all or, by specifying a -``<SELECTOR>``, to the selected elements of the list, storing result in-place -or in the specified output variable. +``<SELECTOR>``, to the selected elements of the list, storing the result +in-place or in the specified output variable. .. note:: - ``TRANSFORM`` sub-command does not change the number of elements of the + The ``TRANSFORM`` sub-command does not change the number of elements in the list. If a ``<SELECTOR>`` is specified, only some elements will be changed, - the other ones will remain same as before the transformation. + the other ones will remain the same as before the transformation. -``<ACTION>`` specify the action to apply to the elements of list. -The actions have exactly the same semantics as sub-commands of -:command:`string` command. - -The ``<ACTION>`` may be one of: +``<ACTION>`` specifies the action to apply to the elements of the list. +The actions have exactly the same semantics as sub-commands of the +:command:`string` command. ``<ACTION>`` must be one of the following: ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of the list. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) + list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower characters. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) + list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) ``STRIP``: Remove leading and trailing spaces from each element of the list. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> STRIP ...) + list(TRANSFORM <list> STRIP ...) ``GENEX_STRIP``: Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` from each element of the list. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> GENEX_STRIP ...) + list(TRANSFORM <list> GENEX_STRIP ...) ``REPLACE``: Match the regular expression as many times as possible and substitute the replacement expression for the match for each element of the list (Same semantic as ``REGEX REPLACE`` from :command:`string` command). -.. code-block:: cmake - - list(TRANSFORM <list> REPLACE <regular_expression> - <replace_expression> ...) + .. code-block:: cmake -``<SELECTOR>`` select which elements of the list will be transformed. Only one -type of selector can be specified at a time. + list(TRANSFORM <list> REPLACE <regular_expression> + <replace_expression> ...) -The ``<SELECTOR>`` may be one of: +``<SELECTOR>`` determines which elements of the list will be transformed. +Only one type of selector can be specified at a time. When given, +``<SELECTOR>`` must be one of the following: ``AT``: Specify a list of indexes. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) + list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) ``FOR``: Specify a range with, optionally, an increment used to iterate over the range. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) + list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) ``REGEX``: Specify a regular expression. Only elements matching the regular expression will be transformed. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) + list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) Ordering diff --git a/Help/command/message.rst b/Help/command/message.rst index 3f9216a..5dca6b4 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -53,12 +53,12 @@ The optional ``<mode>`` keyword determines the type of message: The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout with the message preceded by two hyphens and a space. All other message types -are sent to stderr and are not prefixed with hyphens. The CMake GUI displays -all messages in its log area. The interactive dialogs (:manual:`ccmake(1)` -and :manual:`cmake-gui(1)`) show ``STATUS`` to ``TRACE`` messages one at a -time on a status line and other messages in interactive pop-up boxes. -The ``--loglevel`` command-line option to each of these tools can be used to -control which messages will be shown. +are sent to stderr and are not prefixed with hyphens. The +:manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area. +The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE`` +messages one at a time on a status line and other messages in an +interactive pop-up box. The ``--loglevel`` command-line option to each of +these tools can be used to control which messages will be shown. CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs diff --git a/Help/command/project.rst b/Help/command/project.rst index 41e1112..baf18be 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -31,14 +31,6 @@ Further variables are set by the optional arguments described in the following. If any of these arguments is not used, then the corresponding variables are set to the empty string. -If the variable :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` exists, the file -pointed to by that variable will be included as the first step of the project -command. - -If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` -or :variable:`CMAKE_PROJECT_INCLUDE` exists, the file pointed to by that -variable will be included as the last step of the project command. - Options ^^^^^^^ @@ -63,7 +55,7 @@ The options are: * :variable:`PROJECT_VERSION_TWEAK`, :variable:`<PROJECT-NAME>_VERSION_TWEAK`. - When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + When the ``project()`` command is called from the top-level ``CMakeLists.txt``, then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`. ``DESCRIPTION <project-description-string>`` @@ -76,7 +68,7 @@ The options are: It is recommended that this description is a relatively short string, usually no more than a few words. - When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + When the ``project()`` command is called from the top-level ``CMakeLists.txt``, then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`. ``HOMEPAGE_URL <url-string>`` @@ -87,7 +79,7 @@ The options are: to ``<url-string>``, which should be the canonical home URL for the project. - When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + When the ``project()`` command is called from the top-level ``CMakeLists.txt``, then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. ``LANGUAGES <language-name>...`` @@ -106,18 +98,31 @@ The options are: The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` options are intended for use as default values in package metadata and documentation. +Code Injection +^^^^^^^^^^^^^^ + +If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file +pointed to by that variable will be included as the first step of the +``project()`` command. + +If the :variable:`CMAKE_PROJECT_INCLUDE` or +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files +they point to will be included as the last step of the ``project()`` command. +If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`. + Usage ^^^^^ The top-level ``CMakeLists.txt`` file for a project must contain a -literal, direct call to the :command:`project` command; loading one +literal, direct call to the ``project()`` command; loading one through the :command:`include` command is not sufficient. If no such call exists, CMake will issue a warning and pretend there is a ``project(Project)`` at the top to enable the default languages (``C`` and ``CXX``). .. note:: - Call the :command:`project()` command near the top of the top-level + Call the ``project()`` command near the top of the top-level ``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`. It is important to establish version and policy settings before invoking other commands whose behavior they may affect. diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index f5aa42d..4b2934a 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -654,8 +654,13 @@ allows one to disable them using the following variables: :command:`export(PACKAGE)` populates the user package registry unless the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable explicitly disables it. -* :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the - User Package Registry in all the :command:`find_package` calls. +* :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls when + set to ``FALSE``. +* Deprecated :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls when set + to ``TRUE``. This variable is ignored when + :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` has been set. * :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables the System Package Registry in all the :command:`find_package` calls. diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 77b1ae8..0beca82 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -331,6 +331,7 @@ Properties on Targets /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION + /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_PROJECT_TYPES /prop_tgt/VS_GLOBAL_ROOTNAMESPACE diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index df4531b..7435d9a 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -101,6 +101,14 @@ values for the compilers. The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is cross-compiling. +Note that using the :variable:`CMAKE_SOURCE_DIR` or :variable:`CMAKE_BINARY_DIR` +variables inside a toolchain file is typically undesirable. The toolchain +file is used in contexts where these variables have different values when used +in different places (e.g. as part of a call to :command:`try_compile`). In most +cases, where there is a need to evaluate paths inside a toolchain file, the more +appropriate variable to use would be :variable:`CMAKE_CURRENT_LIST_DIR`, since +it always has an unambiguous, predictable value. + Cross Compiling for Linux ------------------------- diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index cc6a7d2..e0ce6f7 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -98,6 +98,7 @@ Variables that Provide Information /variable/CMAKE_STATIC_LIBRARY_PREFIX /variable/CMAKE_STATIC_LIBRARY_SUFFIX /variable/CMAKE_Swift_MODULE_DIRECTORY + /variable/CMAKE_Swift_NUM_THREADS /variable/CMAKE_TOOLCHAIN_FILE /variable/CMAKE_TWEAK_VERSION /variable/CMAKE_VERBOSE_MAKEFILE @@ -157,6 +158,7 @@ Variables that Change Behavior /variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES /variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT /variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS + /variable/CMAKE_ECLIPSE_RESOURCE_ENCODING /variable/CMAKE_ECLIPSE_VERSION /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION @@ -183,7 +185,8 @@ Variables that Change Behavior /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH /variable/CMAKE_FIND_USE_CMAKE_PATH /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH - /variable/CMAKE_FIND_USE_PACAKGE_ROOT_PATH + /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY + /variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH /variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 13cba71..7b5399d 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -200,11 +200,11 @@ Options from the top of a binary tree for a CMake project it will dump additional information such as the cache, log files etc. -``--loglevel=<error|warning|notice|status|verbose|debug|trace>`` +``--loglevel=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>`` Set the log level. The :command:`message` command will only output messages of the specified - log level or higher. The default log level is ``status``. + log level or higher. The default log level is ``STATUS``. ``--debug-trycompile`` Do not delete the :command:`try_compile` build tree. @@ -290,7 +290,8 @@ following options: value of ``1`` can be used to limit to a single job. ``--target <tgt>..., -t <tgt>...`` - Build ``<tgt>`` instead of default targets. May be specified multiple times. + Build ``<tgt>`` instead of the default target. Multiple targets may be + given, separated by spaces. ``--config <cfg>`` For multi-configuration tools, choose configuration ``<cfg>``. @@ -333,16 +334,16 @@ The options are: Project binary directory to install. This is required and must be first. ``--config <cfg>`` - For multi-configuration tools, choose configuration ``<cfg>``. + For multi-configuration generators, choose configuration ``<cfg>``. ``--component <comp>`` Component-based install. Only install component ``<comp>``. ``--prefix <prefix>`` - The installation prefix :variable:`CMAKE_INSTALL_PREFIX`. + Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`. ``--strip`` - Strip before installing by setting ``CMAKE_INSTALL_DO_STRIP``. + Strip before installing. ``-v, --verbose`` Enable verbose output. diff --git a/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst index 893a298..b6f6160 100644 --- a/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst +++ b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst @@ -13,5 +13,5 @@ part of the ``make clean`` target. Arguments to :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. -This property only works for the the Makefile generators. +This property only works for the Makefile generators. It is ignored on other generators. diff --git a/Help/prop_test/SKIP_RETURN_CODE.rst b/Help/prop_test/SKIP_RETURN_CODE.rst index a05fbf3..3d48c2f 100644 --- a/Help/prop_test/SKIP_RETURN_CODE.rst +++ b/Help/prop_test/SKIP_RETURN_CODE.rst @@ -6,4 +6,5 @@ Return code to mark a test as skipped. Sometimes only a test itself can determine if all requirements for the test are met. If such a situation should not be considered a hard failure a return code of the process can be specified that will mark the test as -``Not Run`` if it is encountered. +``Not Run`` if it is encountered. Valid values are in the range of +0 to 255, inclusive. diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst index 13c9c1d..d978b94 100644 --- a/Help/prop_tgt/BUILD_RPATH.rst +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -8,3 +8,6 @@ tree. See also the :prop_tgt:`INSTALL_RPATH` target property. This property is initialized by the value of the variable :variable:`CMAKE_BUILD_RPATH` if it is set when a target is created. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/FRAMEWORK.rst b/Help/prop_tgt/FRAMEWORK.rst index 9dad060..3dff1be 100644 --- a/Help/prop_tgt/FRAMEWORK.rst +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -6,7 +6,9 @@ Build ``SHARED`` or ``STATIC`` library as Framework Bundle on the macOS and iOS. If such a library target has this property set to ``TRUE`` it will be built as a framework when built on the macOS and iOS. It will have the directory structure required for a framework and will be suitable to -be used with the ``-framework`` option +be used with the ``-framework`` option. This property is initialized by the +value of the :variable:`CMAKE_FRAMEWORK` variable if it is set when a target is +created. To customize ``Info.plist`` file in the framework, use :prop_tgt:`MACOSX_FRAMEWORK_INFO_PLIST` target property. diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst index 6403f4c..93b4488 100644 --- a/Help/prop_tgt/INSTALL_RPATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -7,3 +7,6 @@ A semicolon-separated list specifying the rpath to use in installed targets (for platforms that support it). This property is initialized by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set when a target is created. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/VS_DPI_AWARE.rst b/Help/prop_tgt/VS_DPI_AWARE.rst new file mode 100644 index 0000000..82640cc --- /dev/null +++ b/Help/prop_tgt/VS_DPI_AWARE.rst @@ -0,0 +1,14 @@ +VS_DPI_AWARE +------------ + +Set the Manifest Tool -> Input and Output -> DPI Awareness in the Visual Studio +target project properties. + +Valid values are ``PerMonitor``, ``ON``, or ``OFF``. + +For example: + +.. code-block:: cmake + + add_executable(myproject myproject.cpp) + set_property(TARGET myproject PROPERTY VS_DPI_AWARE "PerMonitor") diff --git a/Help/release/dev/add_cmake_find_use_package_registry.rst b/Help/release/dev/add_cmake_find_use_package_registry.rst new file mode 100644 index 0000000..1b02bad --- /dev/null +++ b/Help/release/dev/add_cmake_find_use_package_registry.rst @@ -0,0 +1,11 @@ +add_cmake_find_use_package_registry +----------------------------------- + +* The :command:`find_package` command has learned to check the following + variables to control searching + + * :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` - Controls the searching the + cmake user registry. + +* The :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` has been deprecated. + Instead use :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` diff --git a/Help/release/dev/build-install-rpath-genex.rst b/Help/release/dev/build-install-rpath-genex.rst new file mode 100644 index 0000000..644b1b2 --- /dev/null +++ b/Help/release/dev/build-install-rpath-genex.rst @@ -0,0 +1,5 @@ +build-install-rpath-genex +------------------------- + +* :prop_tgt:`BUILD_RPATH` and :prop_tgt:`INSTALL_RPATH` now support + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..440efa9 --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,8 @@ +deprecate-policy-old +-------------------- + +* An explicit deprecation diagnostic was added for policy ``CMP0067`` + (``CMP0066`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. diff --git a/Help/release/dev/eclipse-resource-encoding.rst b/Help/release/dev/eclipse-resource-encoding.rst new file mode 100644 index 0000000..6ceca0c --- /dev/null +++ b/Help/release/dev/eclipse-resource-encoding.rst @@ -0,0 +1,6 @@ +eclipse-resource-encoding +------------------------- + +* The :generator:`Eclipse CDT4` extra generator gained a new + :variable:`CMAKE_ECLIPSE_RESOURCE_ENCODING` option to specify + the resource encoding. diff --git a/Help/release/dev/global-controls-over-find-locations.rst b/Help/release/dev/global-controls-over-find-locations.rst index d915fbb..79bc869 100644 --- a/Help/release/dev/global-controls-over-find-locations.rst +++ b/Help/release/dev/global-controls-over-find-locations.rst @@ -4,8 +4,18 @@ global-controls-over-find-locations * The :command:`find_file`, :command:`find_library`, :command:`find_path`, and :command:`find_program` commands have learned to check the following variables to control searching - * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the searching the cmake-specific environment variables. - * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the searching the cmake-specific cache variables. - * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the searching cmake platform specific variables. - * :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` - Controls the searching of :variable:`<PackageName>_ROOT` variables. - * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the searching the standard system environment variables. + + * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the searching + the cmake-specific environment variables. + + * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the searching the + cmake-specific cache variables. + + * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the searching + cmake platform specific variables. + + * :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the searching of + :variable:`<PackageName>_ROOT` variables. + + * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the searching + the standard system environment variables. diff --git a/Help/release/dev/vs-dpi-aware.rst b/Help/release/dev/vs-dpi-aware.rst new file mode 100644 index 0000000..f76f26c --- /dev/null +++ b/Help/release/dev/vs-dpi-aware.rst @@ -0,0 +1,6 @@ +vs-dpi-aware +------------ + +* The :prop_tgt:`VS_DPI_AWARE` target property was added to tell + :ref:`Visual Studio Generators` to set the ``EnableDpiAwareness`` + property in ``.vcxproj`` files. diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst index eea2c4f..6d34c5c 100644 --- a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -4,4 +4,5 @@ CMAKE_CUDA_HOST_COMPILER Executable to use when compiling host code when compiling ``CUDA`` language files. Maps to the ``nvcc -ccbin`` option. Will only be used by CMake on the first configuration to determine a valid host compiler for ``CUDA``. After a valid -host compiler has been found, this value is read-only. +host compiler has been found, this value is read-only. This variable takes +priority over the :envvar:`CUDAHOSTCXX` environment variable. diff --git a/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst new file mode 100644 index 0000000..314efe5 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst @@ -0,0 +1,6 @@ +CMAKE_ECLIPSE_RESOURCE_ENCODING +------------------------------- + +This cache variable tells the :generator:`Eclipse CDT4` project generator +to set the resource encoding to the given value in generated project files. +If no value is given, no encoding will be set. diff --git a/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst b/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst index 4a3121c..76561d8 100644 --- a/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst +++ b/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst @@ -1,6 +1,6 @@ CMAKE_EXECUTE_PROCESS_COMMAND_ECHO ---------------------------------- -If this variable is set to ``STDERR``|``STDOUT``|``NONE`` then commands in -:command:`execute_process` calls will be printed to either stderr or stdout -or not at all. +If this variable is set to ``STDERR``, ``STDOUT`` or ``NONE`` then commands +in :command:`execute_process` calls will be printed to either stderr or +stdout or not at all. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst index 9058471..ffb8a2c 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst @@ -1,12 +1,23 @@ CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY -------------------------------------- -Skip :ref:`User Package Registry` in :command:`find_package` calls. +.. deprecated:: 3.16 + + Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable instead. + +By default this variable is not set. If neither +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` nor +``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is set, then +:command:`find_package()` will use the `User Package Registry` unless the +`NO_CMAKE_PACKAGE_REGISTRY` option is provided. + +``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is ignored if +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` is set. In some cases, for example to locate only system wide installations, it is not desirable to use the :ref:`User Package Registry` when searching for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` -variable is enabled, all the :command:`find_package` commands will skip +variable is ``TRUE``, all the :command:`find_package` commands will skip the :ref:`User Package Registry` as if they were called with the ``NO_CMAKE_PACKAGE_REGISTRY`` argument. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst index 3db510f..33514a0 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst @@ -1,11 +1,18 @@ CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH ------------------------------------- -Controls the searching the cmake-specific environment variables by the :command:`find_program`, -:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`. +Controls the searching the cmake-specific environment variables by the +:command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path` commands. This is useful in cross-compiling environments. -By default this this is set to ``TRUE``. +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the :command:`find_program`, +:command:`find_library`, :command:`find_file`, and :command:`find_path` +commands take precedence over this variable. -See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, -:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, and :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` variables. +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst index 86a6186..cefc645 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst @@ -1,11 +1,18 @@ CMAKE_FIND_USE_CMAKE_PATH ------------------------- -Controls the searching the cmake-specific cache variables by the :command:`find_program`, -:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`. +Controls the searching the cmake-specific cache variables by the +:command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path` commands. This is useful in cross-compiling environments. -By default this this is set to ``TRUE``. +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the :command:`find_program`, +:command:`find_library`, :command:`find_file`, and :command:`find_path` +commands take precedence over this variable. -See also the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, -:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, and :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` variables. +See also the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst index b4171c0..2aa544d 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst @@ -1,11 +1,18 @@ CMAKE_FIND_USE_CMAKE_SYSTEM_PATH -------------------------------- -Controls the searching cmake platform specific variables by the :command:`find_program`, -:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`. +Controls the searching cmake platform specific variables by the +:command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path` commands. This is useful in cross-compiling environments. -By default this this is set to ``TRUE``. +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the :command:`find_program`, +:command:`find_library`, :command:`find_file`, and :command:`find_path` +commands take precedence over this variable. -See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, -:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, and :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` variables. +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACAKGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACAKGE_ROOT_PATH.rst deleted file mode 100644 index ac25ec9..0000000 --- a/Help/variable/CMAKE_FIND_USE_PACAKGE_ROOT_PATH.rst +++ /dev/null @@ -1,11 +0,0 @@ -CMAKE_FIND_USE_PACAKGE_ROOT_PATH --------------------------------- - -Controls the searching of :variable:`<PackageName>_ROOT` variables by the :command:`find_program`, -:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`. -This is useful in cross-compiling environments. - -By default this this is set to ``TRUE``. - -See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, -:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, and :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..75e910f --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst @@ -0,0 +1,29 @@ +CMAKE_FIND_USE_PACKAGE_REGISTRY +------------------------------- + +Controls the searching the :ref:`User Package Registry` by the :command:`find_package` +command. + +By default this variable is not set and the behavior will fall back +to that determined by the deprecated :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` +variable. If that is also not set, then `find_package()` will use the +`User Package Registry` unless the `NO_CMAKE_PACKAGE_REGISTRY` option +is provided. + +This variable takes precedence over :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` +when both are set. + +In some cases, for example to locate only system wide installations, it +is not desirable to use the :ref:`User Package Registry` when searching +for packages. If the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` +variable is ``FALSE``, all the :command:`find_package` commands will skip +the :ref:`User Package Registry` as if they were called with the +``NO_CMAKE_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst new file mode 100644 index 0000000..899e62e --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst @@ -0,0 +1,18 @@ +CMAKE_FIND_USE_PACKAGE_ROOT_PATH +-------------------------------- + +Controls the searching of :variable:`<PackageName>_ROOT` variables by the +:command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path` commands. +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the :command:`find_program`, +:command:`find_library`, :command:`find_file`, and :command:`find_path` +commands take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +and :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variables. diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst index fd0582f..604c710 100644 --- a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst @@ -1,11 +1,18 @@ CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH -------------------------------------- -Controls the searching the standard system environment variables by the :command:`find_program`, -:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`. +Controls the searching the standard system environment variables by the +:command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path` commands. This is useful in cross-compiling environments. -By default this this is set to ``TRUE``. +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the :command:`find_program`, +:command:`find_library`, :command:`find_file`, and :command:`find_path` +commands take precedence over this variable. -See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, -:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, and :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` variables. +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_Swift_NUM_THREADS.rst b/Help/variable/CMAKE_Swift_NUM_THREADS.rst new file mode 100644 index 0000000..cb33678 --- /dev/null +++ b/Help/variable/CMAKE_Swift_NUM_THREADS.rst @@ -0,0 +1,8 @@ +CMAKE_Swift_NUM_THREADS +----------------------- + +Number of threads for parallel compilation for Swift targets. + +This variable controls the number of parallel jobs that the swift driver creates +for building targets. If not specified, it will default to the number of +logical CPUs on the host. |