cmake: Introduce TEST_SUITE_C_FLAGS, TEST_SUITE_CXX_FLAGS, etc.

[MatzeB]

Summary

Intuitively one would use CMAKE_C_FLAGS, CMAKE_CXX_FLAGS and
CMAKE_EXE_LINKER_FLAGS to inject custom flags into the build. However
this clashes with the use of cmake cache files which want to add flags as well.
A user specifying CMAKE_C_FLAGS would (accidentally) override the flags set by the cache files.

The solution here is to introduce a new set of flags called
TEST_SUITE_C_FLAGS, TEST_SUITE_CXX_FLAGS and TEST_SUITE_EXE_LINKER_FLAGS
as a means for users to specify additional flags. This way the flags
will not override the settings from the cache file.

In order to educate users to use the new flags a warning message is
displayed if CMAKE_C_FLAGS is set.

[MatzeB]

Some additional comments:

The goal of this is to enable things like:

cmake -GNinja -C $TESTSUITE/cmake/caches/target-arm64-iphoneos.cmake -DTEST_SUITE_C_FLAGS="-save-temps=obj" $TESTSUITE

with all the strange flags necessary for cross compilation hidden in the target-arm64-iphoneos.cmake file, while it is still being able to inject extra C flags into the build. Using -DCMAKE_C_FLAGS="-save-temps=obj" would override all the settings done in the cache file.

• I am putting this out for review because lnt should be aware of the new flags. (Though in the meantime using CMAKE_C_FLAGS continues to work but gives you a warning message).

• I tried to use new flag names in the cache files instead of forcing new names on the cmake users. However this did not work out: In all my attempts appending the custom flags to CMAKE_C_FLAGS happens too late in the cmake processing and various cmake environment/configuration checks would fail without the cache files target flags being in effect. Setting the crosscompilation flags early enough is essential for those to work so we need to set CMAKE_C_FLAGS in the cache files.

[MatzeB]

Abandoning this. After some experimentation and discussion with Justin, I believe that I can solve this by other means so the cache files can set their flags in a way that users don't accidentaly override them when setting CMAKE_C_FLAGS.

CMakeLists.txt

 cmake_minimum_required(VERSION 3.2)
 
 include(CheckSymbolExists)
 
 # The test-suite is designed to be built in release mode anyway and
 # falls over unless -DNDEBUG is set.
 if (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
   message(STATUS "No build type selected, defaulting to Release")
   set(CMAKE_BUILD_TYPE "Release" CACHE STRING "")
 endif()
 # Selecting installation directories or build types is untypical.
 mark_as_advanced(CMAKE_INSTALL_PREFIX)
 # On the other hand we often want to switch compiler or cflags
 mark_as_advanced(CLEAR CMAKE_C_COMPILER CMAKE_CXX_COMPILER CMAKE_LINKER
-  CMAKE_C_FLAGS CMAKE_C_FLAGS_DEBUG CMAKE_C_FLAGS_MINSIZEREL
+  CMAKE_C_FLAGS_DEBUG CMAKE_C_FLAGS_MINSIZEREL
   CMAKE_C_FLAGS_RELEASE CMAKE_C_FLAGS_RELWITHDEBINFO
-  CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_MINSIZEREL
+  CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_MINSIZEREL
   CMAKE_CXX_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELWITHDEBINFO
-  CMAKE_EXE_LINKER_FLAGS CMAKE_EXE_LINKER_FLAGS_DEBUG
-  CMAKE_EXE_LINKER_FLAGS_MINSIZEREL CMAKE_EXE_LINKER_FLAGS_RELEASE
-  CMAKE_EXE_LINKER_FLAGS_RELWITHDEBINFO)
+  CMAKE_EXE_LINKER_FLAGS_DEBUG CMAKE_EXE_LINKER_FLAGS_MINSIZEREL
+  CMAKE_EXE_LINKER_FLAGS_RELEASE CMAKE_EXE_LINKER_FLAGS_RELWITHDEBINFO)
+
+# Encourage people to use TEST_SUITE_C_FLAGS/TEST_SUITE_CXX_FLAGS so
+# CMAKE_C_FLAGS can be used exclusively by -C cachefiles for specifying
+# target flags without the user accidentally overriding them.
+set(EXPECTED_CMAKE_C_FLAGS "" CACHE STRING
+    "Allows cache files to disable the CMAKE_C_FLAGS warning message")
+mark_as_advanced(EXPECTED_CMAKE_C_FLAGS)
+if(NOT "${CMAKE_C_FLAGS}" STREQUAL "${EXPECTED_CMAKE_C_FLAGS}")
+  message(WARNING "
+Specifying CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, \
+CMAKE_EXE_LINKER_FLAGS is discouraged. Use TEST_SUITE_C_FLAGS, \
+TEST_SUITE_CXX_FLAGS and TEST_SUITE_EXE_LINKER_FLAGS instead.\
+")
+endif()
+mark_as_advanced(CMAKE_C_FLAGS CMAKE_CXX_FLAGS CMAKE_EXE_LINKER_FLAGS)
+set(TEST_SUITE_C_FLAGS "" CACHE STRING "Flags used by the C compiler.")
+set(TEST_SUITE_CXX_FLAGS "${TEST_SUITE_C_FLAGS}" CACHE STRING "Flags used by the C++ compiler.")
+set(TEST_SUITE_EXE_LINKER_FLAGS "" CACHE STRING "Flags used by the linker.")
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${TEST_SUITE_C_FLAGS}")
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${TEST_SUITE_CXX_FLAGS}")
+set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${TEST_SUITE_EXE_LINKER_FLAGS}")
 
 project(test-suite C CXX)
 
 add_definitions(-DNDEBUG)
 option(TEST_SUITE_SUPPRESS_WARNINGS "Suppress all warnings" ON)
 if(${TEST_SUITE_SUPPRESS_WARNINGS})
   add_definitions(-w)
 endif()

cmake/caches/util/arch_flags.cmake

 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${ARCH_FLAGS}" CACHE STRING "")
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${ARCH_FLAGS}" CACHE STRING "")
 set(CMAKE_MODULE_LINKER_FLAGS "${CMAKE_MODULE_LINKER_FLAGS} ${ARCH_FLAGS}" CACHE STRING "")
 set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${ARCH_FLAGS}" CACHE STRING "")
+# Silence the warning in the toplevel CMakeLists.txt.
+set(EXPECTED_CMAKE_C_FLAGS "${CMAKE_C_FLAGS}" CACHE STRING "")