try_compile: Add optional LOG_DESCRIPTION to record in configure log

Issue: #23200

Help/command/try_compile.rst

@@ -18,6 +18,7 @@ Try Compiling Whole Projects
               SOURCE_DIR <srcdir>
               [BINARY_DIR <bindir>]
               [TARGET <targetName>]
+              [LOG_DESCRIPTION <text>]
               [NO_CACHE]
               [CMAKE_FLAGS <flags>...]
               [OUTPUT_VARIABLE <var>])
@@ -47,6 +48,7 @@ which was present in older versions of CMake:
 
   try_compile(<resultVar> <bindir> <srcdir>
               <projectName> [<targetName>]
+              [LOG_DESCRIPTION <text>]
               [NO_CACHE]
               [CMAKE_FLAGS <flags>...]
               [OUTPUT_VARIABLE <var>])
@@ -63,6 +65,7 @@ Try Compiling Source Files
                SOURCE_FROM_CONTENT <name> <content> |
                SOURCE_FROM_VAR <name> <var>         |
                SOURCE_FROM_FILE <name> <path>       >...
+              [LOG_DESCRIPTION <text>]
               [NO_CACHE]
               [CMAKE_FLAGS <flags>...]
               [COMPILE_DEFINITIONS <defs>...]
@@ -115,6 +118,7 @@ which was present in older versions of CMake:
 .. code-block:: cmake
 
   try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
+              [LOG_DESCRIPTION <text>]
               [NO_CACHE]
               [CMAKE_FLAGS <flags>...]
               [COMPILE_DEFINITIONS <defs>...]
@@ -171,6 +175,12 @@ The options are:
   set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
   project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
 
+``LOG_DESCRIPTION <text>``
+  .. versionadded:: 3.26
+
+  Specify a non-empty text description of the purpose of the check.
+  This is recorded in the :manual:`cmake-configure-log(7)` entry.
+
 ``NO_CACHE``
   .. versionadded:: 3.25
 

Help/command/try_run.rst

@@ -17,6 +17,7 @@ Try Compiling and Running Source Files
            SOURCE_FROM_CONTENT <name> <content> |
            SOURCE_FROM_VAR <name> <var>         |
            SOURCE_FROM_FILE <name> <path>       >...
+          [LOG_DESCRIPTION <text>]
           [NO_CACHE]
           [CMAKE_FLAGS <flags>...]
           [COMPILE_DEFINITIONS <defs>...]
@@ -55,6 +56,7 @@ which was present in older versions of CMake:
 
   try_run(<runResultVar> <compileResultVar>
           <bindir> <srcfile|SOURCES srcfile...>
+          [LOG_DESCRIPTION <text>]
           [NO_CACHE]
           [CMAKE_FLAGS <flags>...]
           [COMPILE_DEFINITIONS <defs>...]

Help/manual/cmake-configure-log.7.rst

@@ -141,6 +141,7 @@ A ``try_compile-v1`` event is a YAML mapping:
   kind: "try_compile-v1"
   backtrace:
     - "CMakeLists.txt:123 (try_compile)"
+  description: "Explicit LOG_DESCRIPTION"
   directories:
     source: "/path/to/.../TryCompile-01234"
     binary: "/path/to/.../TryCompile-01234"
@@ -153,6 +154,10 @@ A ``try_compile-v1`` event is a YAML mapping:
 
 The keys specific to ``try_compile-v1`` mappings are:
 
+``description``
+  An optional key that is present when the ``LOG_DESCRIPTION <text>`` option
+  was used.  Its value is a string containing the description ``<text>``.
+
 ``directories``
   A mapping describing the directories associated with the
   compilation attempt.  It has the following keys:
@@ -207,6 +212,7 @@ A ``try_run-v1`` event is a YAML mapping:
   kind: "try_run-v1"
   backtrace:
     - "CMakeLists.txt:456 (try_run)"
+  description: "Explicit LOG_DESCRIPTION"
   directories:
     source: "/path/to/.../TryCompile-56789"
     binary: "/path/to/.../TryCompile-56789"

Help/release/dev/configure-log.rst

@@ -6,3 +6,7 @@ Configure Log
 
 * The :manual:`cmake-file-api(7)` gained a new "configureLog" object kind
   that enables stable access to the :manual:`cmake-configure-log(7)`.
+
+* The :command:`try_compile` and :command:`try_run` commands gained
+  a ``LOG_DESCRIPTION`` option specifying text to be recorded in the
+  :manual:`cmake-configure-log(7)`.

Source/cmCoreTryCompile.cxx

@@ -151,6 +151,7 @@ cmArgumentParser<Arguments> makeTryRunParser(
 auto const TryCompileBaseArgParser =
   cmArgumentParser<Arguments>{}
     .Bind(0, &Arguments::CompileResultVariable)
+    .Bind("LOG_DESCRIPTION"_s, &Arguments::LogDescription)
     .Bind("NO_CACHE"_s, &Arguments::NoCache)
     .Bind("CMAKE_FLAGS"_s, &Arguments::CMakeFlags)
     .Bind("__CMAKE_INTERNAL"_s, &Arguments::CMakeInternal)
@@ -1138,6 +1139,9 @@ cm::optional<cmTryCompileResult> cmCoreTryCompile::TryCompileCode(
   }
 
   cmTryCompileResult result;
+  if (arguments.LogDescription) {
+    result.LogDescription = *arguments.LogDescription;
+  }
   result.SourceDirectory = sourceDirectory;
   result.BinaryDirectory = this->BinaryDirectory;
   result.Variable = *arguments.CompileResultVariable;
@@ -1290,6 +1294,9 @@ void cmCoreTryCompile::WriteTryCompileEventFields(
   cmConfigureLog& log, cmTryCompileResult const& compileResult)
 {
 #ifndef CMAKE_BOOTSTRAP
+  if (compileResult.LogDescription) {
+    log.WriteValue("description"_s, *compileResult.LogDescription);
+  }
   log.BeginObject("directories"_s);
   log.WriteValue("source"_s, compileResult.SourceDirectory);
   log.WriteValue("binary"_s, compileResult.BinaryDirectory);

Source/cmCoreTryCompile.h

@@ -21,6 +21,8 @@ class cmRange;
 
 struct cmTryCompileResult
 {
+  cm::optional<std::string> LogDescription;
+
   std::string SourceDirectory;
   std::string BinaryDirectory;
 
@@ -71,6 +73,7 @@ public:
     cm::optional<std::string> OutputVariable;
     cm::optional<std::string> CopyFileTo;
     cm::optional<std::string> CopyFileError;
+    cm::optional<ArgumentParser::NonEmpty<std::string>> LogDescription;
     bool NoCache = false;
 
     // Argument for try_run only.

Tests/RunCMake/try_compile/ConfigureLog-config.txt

@@ -21,6 +21,7 @@ events:
     backtrace:
       - "ConfigureLog.cmake:[0-9]+ \(try_compile\)"
       - "CMakeLists.txt:[0-9]+ \(include\)"
+    description: "Source that should not compile\."
     directories:
       source: "[^"]*/Tests/RunCMake/try_compile/ConfigureLog-build/CMakeFiles/CMakeScratch/TryCompile-[^/]+"
       binary: "[^"]*/Tests/RunCMake/try_compile/ConfigureLog-build/CMakeFiles/CMakeScratch/TryCompile-[^/]+"
@@ -34,6 +35,7 @@ events:
     backtrace:
       - "ConfigureLog.cmake:[0-9]+ \(try_compile\)"
       - "CMakeLists.txt:[0-9]+ \(include\)"
+    description: "Source that should compile\."
     directories:
       source: "[^"]*/Tests/RunCMake/try_compile/ConfigureLog-build/CMakeFiles/CMakeScratch/TryCompile-[^/]+"
       binary: "[^"]*/Tests/RunCMake/try_compile/ConfigureLog-build/CMakeFiles/CMakeScratch/TryCompile-[^/]+"

Tests/RunCMake/try_compile/ConfigureLog.cmake

@@ -2,8 +2,10 @@ enable_language(C)
 
 try_compile(COMPILE_RESULT
   SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/ConfigureLog-bad.c
+  LOG_DESCRIPTION "Source that should not compile."
   )
 
 try_compile(COMPILE_RESULT
   SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/ConfigureLog-test.c
+  LOG_DESCRIPTION "Source that should compile."
   )

Tests/RunCMake/try_compile/EmptyValueArgs-stderr.txt

@@ -7,3 +7,11 @@ CMake Error at EmptyValueArgs.cmake:[0-9]+ \(try_compile\):
   COPY_FILE_ERROR must be followed by a variable name
 Call Stack \(most recent call first\):
   CMakeLists.txt:[0-9]+ \(include\)
++
+CMake Error at EmptyValueArgs.cmake:[0-9]+ \(try_compile\):
+  Error after keyword "LOG_DESCRIPTION":
+
+    empty string not allowed
+
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)

Tests/RunCMake/try_compile/EmptyValueArgs.cmake

@@ -5,3 +5,6 @@ try_compile(RESULT ${try_compile_bindir_or_SOURCES}
 try_compile(RESULT ${try_compile_bindir_or_SOURCES}
   ${CMAKE_CURRENT_SOURCE_DIR}/src.c
   COPY_FILE "x" COPY_FILE_ERROR "")
+try_compile(RESULT ${try_compile_bindir_or_SOURCES}
+  ${CMAKE_CURRENT_SOURCE_DIR}/src.c
+  LOG_DESCRIPTION "")

Tests/RunCMake/try_compile/NoLogDescription-result.txt

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

Tests/RunCMake/try_compile/NoLogDescription-stderr.txt

@@ -0,0 +1,7 @@
+CMake Error at NoLogDescription.cmake:[0-9]+ \(try_compile\):
+  Error after keyword "LOG_DESCRIPTION":
+
+    missing required value
+
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/try_compile/NoLogDescription.cmake

@@ -0,0 +1,4 @@
+include(${CMAKE_CURRENT_SOURCE_DIR}/${try_compile_DEFS})
+try_compile(RESULT ${try_compile_bindir_or_SOURCES}
+  ${CMAKE_CURRENT_SOURCE_DIR}/src.c
+  LOG_DESCRIPTION)

Tests/RunCMake/try_compile/old_and_new_signature_tests.cmake

@@ -12,6 +12,7 @@ run_cmake(NoCopyFile)
 run_cmake(NoCopyFile2)
 run_cmake(NoCopyFileError)
 run_cmake(NoCStandard)
+run_cmake(NoLogDescription)
 run_cmake(NoOutputVariable)
 run_cmake(NoOutputVariable2)
 run_cmake(BadLinkLibraries)

Tests/RunCMake/try_run/ConfigureLog-config.txt

@@ -20,6 +20,7 @@ events:
     backtrace:
       - "ConfigureLog.cmake:[0-9]+ \(try_run\)"
       - "CMakeLists.txt:[0-9]+ \(include\)"
+    description: "Source that should not compile\."
     directories:
       source: "[^"]*/Tests/RunCMake/try_run/ConfigureLog-build/CMakeFiles/CMakeScratch/TryCompile-[^/]+"
       binary: "[^"]*/Tests/RunCMake/try_run/ConfigureLog-build/CMakeFiles/CMakeScratch/TryCompile-[^/]+"
@@ -36,6 +37,7 @@ events:
     backtrace:
       - "ConfigureLog.cmake:[0-9]+ \(try_run\)"
       - "CMakeLists.txt:[0-9]+ \(include\)"
+    description: "Source that should compile\."
     directories:
       source: "[^"]*/Tests/RunCMake/try_run/ConfigureLog-build/CMakeFiles/CMakeScratch/TryCompile-[^/]+"
       binary: "[^"]*/Tests/RunCMake/try_run/ConfigureLog-build/CMakeFiles/CMakeScratch/TryCompile-[^/]+"

Tests/RunCMake/try_run/ConfigureLog.cmake

@@ -1,9 +1,11 @@
 try_run(RUN_RESULT COMPILE_RESULT
   SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/ConfigureLog-bad.c
+  LOG_DESCRIPTION "Source that should not compile."
   )
 
 try_run(RUN_RESULT COMPILE_RESULT
   SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/ConfigureLog-test.c
+  LOG_DESCRIPTION "Source that should compile."
   )
 
 try_run(RUN_RESULT COMPILE_RESULT