CLI: Rename --loglevel to --log-level for naming consistency

Other multi-word command line options use hyphens to separate
the words, so the --loglevel option introduced in CMake 3.15 was
inconsistent in this regard. Rename it to --log-level but still support
the original --loglevel name to preserve backward compatibility.

Help/command/message.rst

@@ -57,7 +57,7 @@ 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
+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.
 
 Messages of log levels ``NOTICE`` and below will also have each line preceded

Help/manual/cmake.1.rst

@@ -200,12 +200,15 @@ 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>``
+``--log-level=<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``.
 
+ For backward compatibility reasons, ``--loglevel`` is also accepted as a
+ synonym for this option.
+
 ``--debug-trycompile``
  Do not delete the :command:`try_compile` build tree.
  Only useful on one :command:`try_compile` at a time.

Help/release/3.16.rst

@@ -56,6 +56,11 @@ Command-Line
   option that can be used to redirect ``--trace`` output to a file instead
   of ``stderr``.
 
+* The :manual:`cmake(1)` ``--loglevel`` command line option has been
+  renamed to ``--log-level`` to make it consistent with the naming of other
+  command line options.  The ``--loglevel`` option is still supported to
+  preserve backward compatibility.
+
 Commands
 --------
 

Source/cmake.cxx

@@ -725,7 +725,18 @@ void cmake::SetArgs(const std::vector<std::string>& args)
     } else if (arg.find("--debug-output", 0) == 0) {
       std::cout << "Running with debug output on.\n";
       this->SetDebugOutputOn(true);
+    } else if (arg.find("--log-level=", 0) == 0) {
+      const auto logLevel =
+        StringToLogLevel(arg.substr(sizeof("--log-level=") - 1));
+      if (logLevel == LogLevel::LOG_UNDEFINED) {
+        cmSystemTools::Error("Invalid level specified for --log-level");
+        return;
+      }
+      this->SetLogLevel(logLevel);
     } else if (arg.find("--loglevel=", 0) == 0) {
+      // This is supported for backward compatibility. This option only
+      // appeared in the 3.15.x release series and was renamed to
+      // --log-level in 3.16.0
       const auto logLevel =
         StringToLogLevel(arg.substr(sizeof("--loglevel=") - 1));
       if (logLevel == LogLevel::LOG_UNDEFINED) {

Source/cmakemain.cxx

@@ -70,8 +70,9 @@ const char* cmDocumentationOptions[][2] = {
     "Generate graphviz of dependencies, see "
     "CMakeGraphVizOptions.cmake for more." },
   { "--system-information [file]", "Dump information about this system." },
-  { "--loglevel=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>",
-    "Set the verbosity of messages from CMake files." },
+  { "--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>",
+    "Set the verbosity of messages from CMake files. "
+    "--loglevel is also accepted for backward compatibility reasons." },
   { "--debug-trycompile",
     "Do not delete the try_compile build tree. Only "
     "useful on one try_compile at a time." },

Tests/RunCMake/message/RunCMakeTest.cmake

@@ -11,47 +11,49 @@ run_cmake(warnmessage)
 run_cmake(errormessage_deprecated)
 run_cmake(errormessage_dev)
 
-run_cmake_command(
-    message-loglevel-invalid
-    ${CMAKE_COMMAND} --loglevel=blah -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
-  )
+foreach(opt IN ITEMS loglevel log-level)
+  run_cmake_command(
+      message-${opt}-invalid
+      ${CMAKE_COMMAND} --${opt}=blah -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
+    )
 
-# Checking various combinations of `message(...)` and log levels `WARNING` to `TRACE`
-# - no CLI option -> `WARNING` to `STATUS` output
-run_cmake_command(
-    message-loglevel-default
-    ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
-  )
-# - Only `WARNING` output
-run_cmake_command(
-    message-loglevel-warning
-    ${CMAKE_COMMAND} --loglevel=warning -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
-  )
-# - Only `WARNING` and `NOTICE` output
-run_cmake_command(
-    message-loglevel-notice
-    ${CMAKE_COMMAND} --loglevel=notice -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
-  )
-# - `WARNING` to `STATUS` output
-run_cmake_command(
-    message-loglevel-status
-    ${CMAKE_COMMAND} --loglevel=status -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
-  )
-# - `WARNING` to `VERBOSE` output
-run_cmake_command(
-    message-loglevel-verbose
-    ${CMAKE_COMMAND} --loglevel=verbose -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
-  )
-# - `WARNING` to `DEBUG` output
-run_cmake_command(
-    message-loglevel-debug
-    ${CMAKE_COMMAND} --loglevel=debug -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
-  )
-# - `WARNING` to `TRACE` output
-run_cmake_command(
-    message-loglevel-trace
-    ${CMAKE_COMMAND} --loglevel=trace -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
-  )
+  # Checking various combinations of `message(...)` and log levels `WARNING` to `TRACE`
+  # - no CLI option -> `WARNING` to `STATUS` output
+  run_cmake_command(
+      message-${opt}-default
+      ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
+    )
+  # - Only `WARNING` output
+  run_cmake_command(
+      message-${opt}-warning
+      ${CMAKE_COMMAND} --${opt}=warning -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
+    )
+  # - Only `WARNING` and `NOTICE` output
+  run_cmake_command(
+      message-${opt}-notice
+      ${CMAKE_COMMAND} --${opt}=notice -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
+    )
+  # - `WARNING` to `STATUS` output
+  run_cmake_command(
+      message-${opt}-status
+      ${CMAKE_COMMAND} --${opt}=status -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
+    )
+  # - `WARNING` to `VERBOSE` output
+  run_cmake_command(
+      message-${opt}-verbose
+      ${CMAKE_COMMAND} --${opt}=verbose -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
+    )
+  # - `WARNING` to `DEBUG` output
+  run_cmake_command(
+      message-${opt}-debug
+      ${CMAKE_COMMAND} --${opt}=debug -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
+    )
+  # - `WARNING` to `TRACE` output
+  run_cmake_command(
+      message-${opt}-trace
+      ${CMAKE_COMMAND} --${opt}=trace -P ${RunCMake_SOURCE_DIR}/message-all-loglevels.cmake
+    )
+endforeach()
 
 run_cmake_command(
     message-indent

Tests/RunCMake/message/message-log-level-debug-stderr.txt

@@ -0,0 +1,12 @@
+^CMake Deprecation Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:2 \(message\):
+  Deprecation warning
++
+CMake Warning \(dev\) at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:3 \(message\):
+  Author warning message
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
++
+CMake Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:4 \(message\):
+  Warning message
++
+Default NOTICE message
+NOTICE message$

Tests/RunCMake/message/message-log-level-debug-stdout.txt

@@ -0,0 +1,3 @@
+-- STATUS message
+-- VERBOSE message
+-- DEBUG message

Tests/RunCMake/message/message-log-level-default-stderr.txt

@@ -0,0 +1,12 @@
+^CMake Deprecation Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:2 \(message\):
+  Deprecation warning
++
+CMake Warning \(dev\) at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:3 \(message\):
+  Author warning message
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
++
+CMake Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:4 \(message\):
+  Warning message
++
+Default NOTICE message
+NOTICE message$

Tests/RunCMake/message/message-log-level-default-stdout.txt

@@ -0,0 +1 @@
+-- STATUS message

Tests/RunCMake/message/message-log-level-invalid-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/message/message-log-level-invalid-stderr.txt

@@ -0,0 +1 @@
+CMake Error: Invalid level specified for --log-level

Tests/RunCMake/message/message-log-level-notice-stderr.txt

@@ -0,0 +1,12 @@
+^CMake Deprecation Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:2 \(message\):
+  Deprecation warning
++
+CMake Warning \(dev\) at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:3 \(message\):
+  Author warning message
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
++
+CMake Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:4 \(message\):
+  Warning message
++
+Default NOTICE message
+NOTICE message$

Tests/RunCMake/message/message-log-level-status-stderr.txt

@@ -0,0 +1,12 @@
+^CMake Deprecation Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:2 \(message\):
+  Deprecation warning
++
+CMake Warning \(dev\) at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:3 \(message\):
+  Author warning message
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
++
+CMake Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:4 \(message\):
+  Warning message
++
+Default NOTICE message
+NOTICE message$

Tests/RunCMake/message/message-log-level-status-stdout.txt

@@ -0,0 +1 @@
+-- STATUS message

Tests/RunCMake/message/message-log-level-trace-stderr.txt

@@ -0,0 +1,12 @@
+^CMake Deprecation Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:2 \(message\):
+  Deprecation warning
++
+CMake Warning \(dev\) at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:3 \(message\):
+  Author warning message
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
++
+CMake Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:4 \(message\):
+  Warning message
++
+Default NOTICE message
+NOTICE message$

Tests/RunCMake/message/message-log-level-trace-stdout.txt

@@ -0,0 +1,4 @@
+-- STATUS message
+-- VERBOSE message
+-- DEBUG message
+-- TRACE message

Tests/RunCMake/message/message-log-level-verbose-stderr.txt

@@ -0,0 +1,12 @@
+^CMake Deprecation Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:2 \(message\):
+  Deprecation warning
++
+CMake Warning \(dev\) at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:3 \(message\):
+  Author warning message
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
++
+CMake Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:4 \(message\):
+  Warning message
++
+Default NOTICE message
+NOTICE message$

Tests/RunCMake/message/message-log-level-verbose-stdout.txt

@@ -0,0 +1,2 @@
+-- STATUS message
+-- VERBOSE message

Tests/RunCMake/message/message-log-level-warning-stderr.txt

@@ -0,0 +1,9 @@
+^CMake Deprecation Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:2 \(message\):
+  Deprecation warning
++
+CMake Warning \(dev\) at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:3 \(message\):
+  Author warning message
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
++
+CMake Warning at.*/Tests/RunCMake/message/message-all-loglevels\.cmake:4 \(message\):
+  Warning message$