diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/message.rst | 16 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 5 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 15 | ||||
| -rw-r--r-- | Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst | 6 | ||||
| -rw-r--r-- | Help/release/dev/0-sample-topic.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/FindCURL-cmake-package.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/deprecate-policy-old.rst | 8 | ||||
| -rw-r--r-- | Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT | 11 | ||||
| -rw-r--r-- | Help/release/dev/vs-per-config-sources.rst | 5 | ||||
| -rw-r--r-- | Help/release/dev/vs-vctargetspath.rst | 10 | ||||
| -rw-r--r-- | Help/release/dev/vs_dotnet_documentation_file.rst | 6 | ||||
| -rw-r--r-- | Help/release/index.rst | 2 | ||||
| -rw-r--r-- | Help/variable/CMAKE_GENERATOR_TOOLSET.rst | 5 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MESSAGE_CONTEXT.rst | 62 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst | 15 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst | 15 |
17 files changed, 194 insertions, 2 deletions
diff --git a/Help/command/message.rst b/Help/command/message.rst index c614286..beb820a 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -59,12 +59,26 @@ 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 ``--log-level`` command-line option to each of these tools can be used to control which messages will be shown. +To make a log level persist between CMake runs, the +:variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead. +Note that the command line option takes precedence over the cache variable. -Messages of log levels ``NOTICE`` and below will also have each line preceded +Messages of log levels ``NOTICE`` and below will have each line preceded by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to a single string by concatenating its list items). For ``STATUS`` to ``TRACE`` messages, this indenting content will be inserted after the hyphens. +Messages of log levels ``NOTICE`` and below can also have each line preceded +with context of the form ``[some.context.example]``. The content between the +square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT` +list variable to a dot-separated string. The message context will always +appear before any indenting content but after any automatically added leading +hyphens. By default, message context is not shown, it has to be explicitly +enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context`` +command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` +variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for +usage examples. + CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs delimited by newlines. Indented text is considered pre-formatted. 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 0442d89..cad0df6 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -70,7 +70,6 @@ Variables that Provide Information /variable/CMAKE_MAKE_PROGRAM /variable/CMAKE_MATCH_COUNT /variable/CMAKE_MATCH_n - /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION /variable/CMAKE_NETRC @@ -205,6 +204,10 @@ Variables that Change Behavior /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_MFC_FLAG /variable/CMAKE_MAXIMUM_RECURSION_DEPTH + /variable/CMAKE_MESSAGE_CONTEXT + /variable/CMAKE_MESSAGE_CONTEXT_SHOW + /variable/CMAKE_MESSAGE_INDENT + /variable/CMAKE_MESSAGE_LOG_LEVEL /variable/CMAKE_MODULE_PATH /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 4ab55a0..71110d1 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -206,9 +206,24 @@ Options The :command:`message` command will only output messages of the specified log level or higher. The default log level is ``STATUS``. + To make a log level persist between CMake runs, set + :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead. + If both the command line option and the variable are given, the command line + option takes precedence. + For backward compatibility reasons, ``--loglevel`` is also accepted as a synonym for this option. +``--log-context`` + Enable the :command:`message` command outputting context attached to each + message. + + This option turns on showing context for the current CMake run only. + To make showing the context persistent for all subsequent CMake runs, set + :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead. + When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` + is ignored. + ``--debug-trycompile`` Do not delete the :command:`try_compile` build tree. Only useful on one :command:`try_compile` at a time. 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/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +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/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/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..401f4b2 --- /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 ``CMP0068`` + and policy ``CMP0069`` (``CMP0067`` 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/feature-CMAKE_MESSAGE_CONTEXT b/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT new file mode 100644 index 0000000..a6a5c71 --- /dev/null +++ b/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT @@ -0,0 +1,11 @@ +feature-CMAKE_MESSAGE_CONTEXT +----------------------------- + +* The :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can now be used + to persist a log level between CMake runs, unlike the ``--log-level`` + command line option which only applies to that particular run. + +* The :command:`message` command learned to output context provided in + the :variable:`CMAKE_MESSAGE_CONTEXT` variable for log levels + ``NOTICE`` and below. Enable this output with the new ``--log-context`` + command-line option or :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable. 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/index.rst b/Help/release/index.rst index 0cc3f97..a4585a5 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ 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_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_MESSAGE_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst new file mode 100644 index 0000000..6b4ca40 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst @@ -0,0 +1,62 @@ +CMAKE_MESSAGE_CONTEXT +--------------------- + +When enabled by the :manual:`cmake <cmake(1)>` ``--log-context`` command line +option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the +:command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a +dot-separated string surrounded by square brackets and prepends it to each line +for messages of log levels ``NOTICE`` and below. + +For logging contexts to work effectively, projects should generally +``APPEND`` and ``POP_BACK`` an item to the current value of +``CMAKE_MESSAGE_CONTEXT`` rather than replace it. +Projects should not assume the message context at the top of the source tree +is empty, as there are scenarios where the context might have already been set +(e.g. hierarchical projects). + +.. warning:: + + Valid context names are restricted to anything that could be used + as a CMake variable name. All names that begin with an underscore + or the string ``cmake_`` are also reserved for use by CMake and + should not be used by projects. + +Example: + +.. code-block:: cmake + + function(bar) + list(APPEND CMAKE_MESSAGE_CONTEXT "bar") + message(VERBOSE "bar VERBOSE message") + endfunction() + + function(baz) + list(APPEND CMAKE_MESSAGE_CONTEXT "baz") + message(DEBUG "baz DEBUG message") + endfunction() + + function(foo) + list(APPEND CMAKE_MESSAGE_CONTEXT "foo") + bar() + message(TRACE "foo TRACE message") + baz() + endfunction() + + list(APPEND CMAKE_MESSAGE_CONTEXT "top") + + message(VERBOSE "Before `foo`") + foo() + message(VERBOSE "After `foo`") + + list(POP_BACK CMAKE_MESSAGE_CONTEXT) + + +Which results in the following output: + +.. code-block:: none + + -- [top] Before `foo` + -- [top.foo.bar] bar VERBOSE message + -- [top.foo] foo TRACE message + -- [top.foo.baz] baz DEBUG message + -- [top] After `foo` diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst new file mode 100644 index 0000000..7ec218e --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst @@ -0,0 +1,15 @@ +CMAKE_MESSAGE_CONTEXT_SHOW +-------------------------- + +Setting this variable to true enables showing a context with each line +logged by the :command:`message` command (see :variable:`CMAKE_MESSAGE_CONTEXT` +for how the context itself is specified). + +This variable is an alternative to providing the ``--log-context`` option +on the :manual:`cmake <cmake(1)>` command line. Whereas the command line +option will apply only to that one CMake run, setting +``CMAKE_MESSAGE_CONTEXT_SHOW`` to true as a cache variable will ensure that +subsequent CMake runs will continue to show the message context. + +Projects should not set ``CMAKE_MESSAGE_CONTEXT_SHOW``. It is intended for +users so that they may control whether or not to include context with messages. diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst new file mode 100644 index 0000000..1d4cfe6 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst @@ -0,0 +1,15 @@ +CMAKE_MESSAGE_LOG_LEVEL +----------------------- + +When set, this variable specifies the logging level used by the +:command:`message` command. Valid values are the same as those for the +``--log-level`` command line option of the :manual:`cmake(1)` program. +If this variable is set and the ``--log-level`` command line option is +given, the command line option takes precedence. + +The main advantage to using this variable is to make a log level persist +between CMake runs. Setting it as a cache variable will ensure that +subsequent CMake runs will continue to use the chosen log level. + +Projects should not set this variable, it is intended for users so that +they may control the log level according to their own needs. |