Merge #244: [FIXUP] cmake: Improve description and document `APPEND_*…

…FLAGS`

9a5f39f [FIXUP] cmake: Improve description and document `APPEND_*FLAGS` (Hennadii Stepanov)

Pull request description:

  Descriptions and the comment have been aligned with bitcoin-core/secp256k1#1546.

  Closes #239.

ACKs for top commit:
  real-or-random:
    utACK 9a5f39f

Tree-SHA512: 23675b3e1dfb53def0ddba89b6578b2e4634c3c4d034d2243b9fdba556fc3165f5c3eb912dab74254e2ff43eb8c45d8f7d5dcf2f8c1fb1726359111cd42fac7c

CMakeLists.txt

@@ -165,10 +165,12 @@ cmake_dependent_option(ENABLE_FUZZ "Build for fuzzing. Enabling this will disabl
 
 option(INSTALL_MAN "Install man pages." ON)
 
-set(APPEND_CPPFLAGS "" CACHE STRING "Preprocessor flags that are appended to the flags added by the build system.")
-set(APPEND_CFLAGS "" CACHE STRING "C compiler flags that are appended to the flags added by the build system.")
-set(APPEND_CXXFLAGS "" CACHE STRING "(Objective) C++ compiler flags that are appended to the flags added by the build system.")
-set(APPEND_LDFLAGS "" CACHE STRING "Linker flags that are appended to the flags added by the build system.")
+set(APPEND_CPPFLAGS "" CACHE STRING "Preprocessor flags that are appended to the command line after all other flags added by the build system. This variable is intended for debugging and special builds.")
+set(APPEND_CFLAGS "" CACHE STRING "C compiler flags that are appended to the command line after all other flags added by the build system. This variable is intended for debugging and special builds.")
+set(APPEND_CXXFLAGS "" CACHE STRING "(Objective) C++ compiler flags that are appended to the command line after all other flags added by the build system. This variable is intended for debugging and special builds.")
+set(APPEND_LDFLAGS "" CACHE STRING "Linker flags that are appended to the command line after all other flags added by the build system. This variable is intended for debugging and special builds.")
+# Appending to this low-level rule variables is the only way to
+# guarantee that the flags appear at the end of the command line.
 string(APPEND CMAKE_CXX_COMPILE_OBJECT " ${APPEND_CPPFLAGS} ${APPEND_CXXFLAGS}")
 string(APPEND CMAKE_CXX_CREATE_SHARED_LIBRARY " ${APPEND_LDFLAGS}")
 string(APPEND CMAKE_CXX_LINK_EXECUTABLE " ${APPEND_LDFLAGS}")