diff options
Diffstat (limited to 'Help')
26 files changed, 122 insertions, 19 deletions
diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt index a723375..3f66181 100644 --- a/Help/command/LINK_OPTIONS_LINKER.txt +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -1,8 +1,8 @@ -To pass options to the linker tool, each compiler driver has is own syntax. -The ``LINKER:`` prefix can be used to specify, in a portable way, options -to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required -driver option and the rest of the option string defines linker arguments using -``,`` as separator. These arguments will be formatted according to the +To pass options to the linker tool, each compiler driver has its own syntax. +The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable +way, options to pass to the linker tool. ``LINKER:`` is replaced by the +appropriate driver option and ``,`` by the appropriate driver separator. +The driver prefix and driver separator are given by the values of the :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables. @@ -12,11 +12,11 @@ For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix expression. -The ``LINKER:`` prefix supports, as alternate syntax, specification of -arguments using ``SHELL:`` prefix and space as separator. Previous example -becomes ``"LINKER:SHELL:-z defs"``. +The ``LINKER:`` prefix supports, as an alternative syntax, specification of +arguments using the ``SHELL:`` prefix and space as separator. The previous +example then becomes ``"LINKER:SHELL:-z defs"``. .. note:: - Specifying ``SHELL:`` prefix elsewhere than at the beginning of the + Specifying the ``SHELL:`` prefix anywhere other than at the beginning of the ``LINKER:`` prefix is not supported. diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 530c012..0f8ec32 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,9 +1,9 @@ The final set of compile or link options used for a target is constructed by accumulating options from the current target and the usage requirements of -it dependencies. The set of options is de-duplicated to avoid repetition. +its dependencies. The set of options is de-duplicated to avoid repetition. While beneficial for individual options, the de-duplication step can break up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may specify a group of options using shell-like quoting along with a ``SHELL:`` -prefix. The ``SHELL:`` prefix is dropped and the rest of the option string +prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. diff --git a/Help/command/math.rst b/Help/command/math.rst index 3cbe719..ddb1ec6 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -8,7 +8,8 @@ Evaluate a mathematical expression. math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>]) Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the -resulting value. +resulting value. The result of the expression must be representable as a +64-bit signed integer. The mathematical expression must be given as a string (i.e. enclosed in double quotation marks). An example is ``"5 * (10 + 13)"``. diff --git a/Help/command/project.rst b/Help/command/project.rst index 3951456..b6093d3 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -102,9 +102,12 @@ options are intended for use as default values in package metadata and documenta 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 +If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set, +the files they point to will be included as the first step of the ``project()`` command. +If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be +included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`. If the :variable:`CMAKE_PROJECT_INCLUDE` or :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index 3a32f41..d283948 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -47,6 +47,9 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. +The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly +useful for specifying a language-specific header to precompile for +only one language (e.g. ``CXX`` and not ``C``). Usage ^^^^^ @@ -56,6 +59,7 @@ Usage target_precompile_headers(<target> PUBLIC project_header.h + "$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>" PRIVATE [["other_header.h"]] <unordered_map> diff --git a/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst new file mode 100644 index 0000000..e9e0810 --- /dev/null +++ b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,9 @@ +CMAKE_EXPORT_COMPILE_COMMANDS +----------------------------- + +.. include:: ENV_VAR.txt + +The default value for :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` when there +is no explicit configuration given on the first run while creating a new +build tree. On later runs in an existing build tree the value persists in +the cache as :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`. diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 96ceb94..c98f18f 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -23,6 +23,7 @@ Environment Variables that Control the Build /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_CONFIG_TYPE + /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 6e7f9b5..ba9887c 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -211,7 +211,7 @@ Variable Queries .. code-block:: cmake target_compile_definitions(myapp - PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Clang>>:COMPILING_CXX_WITH_CLANG> + PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG> $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL> $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG> ) diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 1369aa3..02e07eb 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -342,6 +342,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_DOTNET_DOCUMENTATION_FILE /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_PROJECT_TYPES diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index cad0df6..026740c 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -216,6 +216,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE + /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS @@ -241,6 +242,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_ENVIRONMENT /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES diff --git a/Help/policy/CMP0097.rst b/Help/policy/CMP0097.rst index 8a5ff88..4840aa6 100644 --- a/Help/policy/CMP0097.rst +++ b/Help/policy/CMP0097.rst @@ -14,7 +14,7 @@ to expect the new behavior. The ``OLD`` behavior for this policy is for ``GIT_SUBMODULES`` when set to an empty string to initialize and update all git submodules. -The ``New`` behavior for this policy is for ``GIT_SUBMODULES`` when set to +The ``NEW`` behavior for this policy is for ``GIT_SUBMODULES`` when set to an empty string to initialize and update no git submodules. This policy was introduced in CMake version 3.16. Use the diff --git a/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst new file mode 100644 index 0000000..1bc361c --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst @@ -0,0 +1,6 @@ +VS_DOTNET_DOCUMENTATION_FILE +---------------------------- + +Visual Studio managed project .NET documentation output + +Sets the target XML documentation file output. diff --git a/Help/release/dev/FindCURL-cmake-package.rst b/Help/release/dev/FindCURL-cmake-package.rst new file mode 100644 index 0000000..67c5bbc --- /dev/null +++ b/Help/release/dev/FindCURL-cmake-package.rst @@ -0,0 +1,7 @@ +FindCURL-cmake-package +---------------------- + +* The :module:`FindCURL` module learned to find CURL using + the ``CURLConfig.cmake`` package configuration file generated by + CURL's cmake buildsystem. It also gained a new ``CURL_NO_CURL_CMAKE`` + option to disable this behavior. diff --git a/Help/release/dev/export-compile-commands-environment-variable.rst b/Help/release/dev/export-compile-commands-environment-variable.rst new file mode 100644 index 0000000..da9d66b --- /dev/null +++ b/Help/release/dev/export-compile-commands-environment-variable.rst @@ -0,0 +1,6 @@ +export-compile-commands-environment-variable +-------------------------------------------- + +* The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its + initial value from the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment + variable if no explicit configuration is given. diff --git a/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT b/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst index a6a5c71..a6a5c71 100644 --- a/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT +++ b/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst diff --git a/Help/release/dev/vs-per-config-sources.rst b/Help/release/dev/vs-per-config-sources.rst new file mode 100644 index 0000000..bf7572b --- /dev/null +++ b/Help/release/dev/vs-per-config-sources.rst @@ -0,0 +1,5 @@ +vs-per-config-sources +--------------------- + +* :ref:`Visual Studio Generators` learned to support per-config sources. + Previously only :ref:`Command-Line Build Tool Generators` supported them. diff --git a/Help/release/dev/vs-vctargetspath.rst b/Help/release/dev/vs-vctargetspath.rst new file mode 100644 index 0000000..d40af34 --- /dev/null +++ b/Help/release/dev/vs-vctargetspath.rst @@ -0,0 +1,10 @@ +vs-vctargetspath +---------------- + +* With :ref:`Visual Studio Generators` for VS 2010 and above, + the :variable:`CMAKE_GENERATOR_TOOLSET` setting gained an option + to specify the ``VCTargetsPath`` value for project files. + +* The :variable:`CMAKE_VS_GLOBALS` variable value now applies during + compiler identification and in targets created by the + :command:`add_custom_target` command. diff --git a/Help/release/dev/vs_dotnet_documentation_file.rst b/Help/release/dev/vs_dotnet_documentation_file.rst new file mode 100644 index 0000000..fdffb1c --- /dev/null +++ b/Help/release/dev/vs_dotnet_documentation_file.rst @@ -0,0 +1,6 @@ +vs_dotnet_documentation_file +---------------------------- + +* The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added + to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile`` + reference in ``.csproj`` files. diff --git a/Help/release/dev/xcode-scheme-env.rst b/Help/release/dev/xcode-scheme-env.rst new file mode 100644 index 0000000..238cb61 --- /dev/null +++ b/Help/release/dev/xcode-scheme-env.rst @@ -0,0 +1,5 @@ +xcode-scheme-env +---------------- + +* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added + to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property. diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst index 4548abc..6d2450b 100644 --- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -25,6 +25,9 @@ form. The format of the JSON file looks like: } ] +This is initialized by the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment +variable. + .. note:: This option is implemented only by :ref:`Makefile Generators` and the :generator:`Ninja`. It is ignored on other generators. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 222824f..53ad2f3 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -58,3 +58,8 @@ Supported pairs are: Specify the toolset version to use. Supported by VS 2017 and above with the specified toolset installed. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable. + +``VCTargetsPath=<path>`` + Specify an alternative ``VCTargetsPath`` value for Visual Studio + project files. This allows use of VS platform extension configuration + files (``.props`` and ``.targets``) that are not installed with VS. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst index 965c94e..5835264 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -5,5 +5,6 @@ A CMake language file or module to be included as the last step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst index 70b15e6..280c14a 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -5,5 +5,6 @@ A CMake language file or module to be included as the first step of all :command:`project` command calls. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and :variable:`CMAKE_PROJECT_INCLUDE` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst index 3485c38..74247f1 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -6,5 +6,6 @@ A CMake language file or module to be included as the last step of any name. This is intended for injecting custom code into project builds without modifying their source. -See also the :variable:`CMAKE_PROJECT_INCLUDE` and +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE` and :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst new file mode 100644 index 0000000..db1432d --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE +------------------------------------------- + +A CMake language file or module to be included as the first step of any +:command:`project` command calls that specify ``<PROJECT-NAME>`` as the project +name. This is intended for injecting custom code into project builds without +modifying their source. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_INCLUDE` and +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst new file mode 100644 index 0000000..4832659 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_ENVIRONMENT +------------------------------ + +Specify environment variables that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of environment variables and values of the form +``MYVAR=value`` those environment variables will be added to the +scheme. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. |