Merge bitcoin-core/secp256k1#1240: cmake: Improve and document compiler flag checks

a8d059f cmake, doc: Document compiler flags (Hennadii Stepanov)
6ece150 cmake, refactor: Rename `try_add_compile_option` to `try_append_cflags` (Hennadii Stepanov)
19516ed cmake: Use `add_compile_options()` in `try_add_compile_option()` (Hennadii Stepanov)

Pull request description:

  This PR:
  - drops tinkering with the `COMPILE_OPTIONS` directory property in `try_add_compile_option()`  and renames it to `try_append_cflags()`
  - copies related comments from `configure.ac`

ACKs for top commit:
  theuni:
    ACK bitcoin-core/secp256k1@a8d059f .

Tree-SHA512: 7ac011c135e12a65c45f4feb7cd74fd2d961ed77252afecf3a66e2af1d57facab446120c63696507b5ecd5bdb3eee1521760a53028b914c429652d00d03a4462

Author: real-or-random

CMakeLists.txt

@@ -191,25 +191,27 @@ else()
   endif()
 endif()
 
-include(TryAddCompileOption)
+include(TryAppendCFlags)
 if(MSVC)
-  try_add_compile_option(/W2)
-  try_add_compile_option(/wd4146)
+  # Keep the following commands ordered lexicographically.
+  try_append_c_flags(/W2) # Moderate warning level.
+  try_append_c_flags(/wd4146) # Disable warning C4146 "unary minus operator applied to unsigned type, result still unsigned".
 else()
-  try_add_compile_option(-pedantic)
-  try_add_compile_option(-Wall)
-  try_add_compile_option(-Wcast-align)
-  try_add_compile_option(-Wcast-align=strict)
-  try_add_compile_option(-Wconditional-uninitialized)
-  try_add_compile_option(-Wextra)
-  try_add_compile_option(-Wnested-externs)
-  try_add_compile_option(-Wno-long-long)
-  try_add_compile_option(-Wno-overlength-strings)
-  try_add_compile_option(-Wno-unused-function)
-  try_add_compile_option(-Wreserved-identifier)
-  try_add_compile_option(-Wshadow)
-  try_add_compile_option(-Wstrict-prototypes)
-  try_add_compile_option(-Wundef)
+  # Keep the following commands ordered lexicographically.
+  try_append_c_flags(-pedantic)
+  try_append_c_flags(-Wall) # GCC >= 2.95 and probably many other compilers.
+  try_append_c_flags(-Wcast-align) # GCC >= 2.95.
+  try_append_c_flags(-Wcast-align=strict) # GCC >= 8.0.
+  try_append_c_flags(-Wconditional-uninitialized) # Clang >= 3.0 only.
+  try_append_c_flags(-Wextra) # GCC >= 3.4, this is the newer name of -W, which we don't use because older GCCs will warn about unused functions.
+  try_append_c_flags(-Wnested-externs)
+  try_append_c_flags(-Wno-long-long) # GCC >= 3.0, -Wlong-long is implied by -pedantic.
+  try_append_c_flags(-Wno-overlength-strings) # GCC >= 4.2, -Woverlength-strings is implied by -pedantic.
+  try_append_c_flags(-Wno-unused-function) # GCC >= 3.0, -Wunused-function is implied by -Wall.
+  try_append_c_flags(-Wreserved-identifier) # Clang >= 13.0 only.
+  try_append_c_flags(-Wshadow)
+  try_append_c_flags(-Wstrict-prototypes)
+  try_append_c_flags(-Wundef)
 endif()
 
 set(CMAKE_C_VISIBILITY_PRESET hidden)

cmake/TryAddCompileOption.cmake

@@ -0,0 +1,24 @@
+include(CheckCCompilerFlag)
+
+function(secp256k1_check_c_flags_internal flags output)
+  string(MAKE_C_IDENTIFIER "${flags}" result)
+  string(TOUPPER "${result}" result)
+  set(result "C_SUPPORTS_${result}")
+  if(NOT MSVC)
+    set(CMAKE_REQUIRED_FLAGS "-Werror")
+  endif()
+
+  # This avoids running a linker.
+  set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
+  check_c_compiler_flag("${flags}" ${result})
+
+  set(${output} ${${result}} PARENT_SCOPE)
+endfunction()
+
+# Append flags to the COMPILE_OPTIONS directory property if CC accepts them.
+macro(try_append_c_flags)
+  secp256k1_check_c_flags_internal("${ARGV}" result)
+  if(result)
+    add_compile_options(${ARGV})
+  endif()
+endmacro()