From aa944c88e3e89398eaabab78297b42dea99d69d4 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 15 Jun 2017 13:49:35 -0400 Subject: Check*CompilerFlag: Rewrite documentation of these modules Format with modern markup. Clarify that the setting of `CMAKE_REQUIRED_DEFINITIONS` is temporary. Add a note warning about contamination of the checks by `CMAKE__FLAGS`. Issue: #16973 --- Modules/CheckCCompilerFlag.cmake | 50 ++++++++++++++++++++------------- Modules/CheckCXXCompilerFlag.cmake | 49 +++++++++++++++++++------------- Modules/CheckFortranCompilerFlag.cmake | 51 ++++++++++++++++++++-------------- 3 files changed, 90 insertions(+), 60 deletions(-) diff --git a/Modules/CheckCCompilerFlag.cmake b/Modules/CheckCCompilerFlag.cmake index 1ba67fc..5a7298b 100644 --- a/Modules/CheckCCompilerFlag.cmake +++ b/Modules/CheckCCompilerFlag.cmake @@ -1,26 +1,36 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. -#.rst: -# CheckCCompilerFlag -# ------------------ -# -# Check whether the C compiler supports a given flag. -# -# CHECK_C_COMPILER_FLAG( ) -# -# :: -# -# - the compiler flag -# - variable to store the result -# Will be created as an internal cache variable. -# -# This internally calls the check_c_source_compiles macro and sets -# CMAKE_REQUIRED_DEFINITIONS to . See help for -# CheckCSourceCompiles for a listing of variables that can otherwise -# modify the build. The result only tells that the compiler does not -# give an error message when it encounters the flag. If the flag has -# any effect or even a specific one is beyond the scope of this module. +#[=======================================================================[.rst: +CheckCCompilerFlag +------------------ + +Check whether the C compiler supports a given flag. + +.. command:: check_c_compiler_flag + + :: + + check_c_compiler_flag( ) + + Check that the ```` is accepted by the compiler without + a diagnostic. Stores the result in an internal cache entry + named ````. + +This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable +and calls the ``check_c_source_compiles`` macro from the +:module:`CheckCSourceCompiles` module. See documentation of that +module for a listing of variables that can otherwise modify the build. + +A positive result from this check indicates only that the compiler did not +issue a diagnostic message when given the flag. Whether the flag has any +effect or even a specific one is beyond the scope of this module. + +.. note:: + Since the :command:`try_compile` command forwards flags from variables + like :variable:`CMAKE_C_FLAGS _FLAGS>`, unknown flags + in such variables may cause a false negative for this check. +#]=======================================================================] include(CheckCSourceCompiles) include(CMakeCheckCompilerFlagCommonPatterns) diff --git a/Modules/CheckCXXCompilerFlag.cmake b/Modules/CheckCXXCompilerFlag.cmake index afbb231..f731b70 100644 --- a/Modules/CheckCXXCompilerFlag.cmake +++ b/Modules/CheckCXXCompilerFlag.cmake @@ -1,25 +1,36 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. -#.rst: -# CheckCXXCompilerFlag -# -------------------- -# -# Check whether the CXX compiler supports a given flag. -# -# CHECK_CXX_COMPILER_FLAG( ) -# -# :: -# -# - the compiler flag -# - variable to store the result -# -# This internally calls the check_cxx_source_compiles macro and sets -# CMAKE_REQUIRED_DEFINITIONS to . See help for -# CheckCXXSourceCompiles for a listing of variables that can otherwise -# modify the build. The result only tells that the compiler does not -# give an error message when it encounters the flag. If the flag has -# any effect or even a specific one is beyond the scope of this module. +#[=======================================================================[.rst: +CheckCXXCompilerFlag +------------------------ + +Check whether the CXX compiler supports a given flag. + +.. command:: check_cxx_compiler_flag + + :: + + check_cxx_compiler_flag( ) + + Check that the ```` is accepted by the compiler without + a diagnostic. Stores the result in an internal cache entry + named ````. + +This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable +and calls the ``check_cxx_source_compiles`` macro from the +:module:`CheckCXXSourceCompiles` module. See documentation of that +module for a listing of variables that can otherwise modify the build. + +A positive result from this check indicates only that the compiler did not +issue a diagnostic message when given the flag. Whether the flag has any +effect or even a specific one is beyond the scope of this module. + +.. note:: + Since the :command:`try_compile` command forwards flags from variables + like :variable:`CMAKE_CXX_FLAGS _FLAGS>`, unknown flags + in such variables may cause a false negative for this check. +#]=======================================================================] include(CheckCXXSourceCompiles) include(CMakeCheckCompilerFlagCommonPatterns) diff --git a/Modules/CheckFortranCompilerFlag.cmake b/Modules/CheckFortranCompilerFlag.cmake index 8519fcc..8a1a8b9 100644 --- a/Modules/CheckFortranCompilerFlag.cmake +++ b/Modules/CheckFortranCompilerFlag.cmake @@ -1,27 +1,36 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. -#.rst: -# CheckFortranCompilerFlag -# ------------------------ -# -# Check whether the Fortran compiler supports a given flag. -# -# CHECK_Fortran_COMPILER_FLAG( ) -# -# :: -# -# - the compiler flag -# - variable to store the result -# Will be created as an internal cache variable. -# -# This internally calls the check_fortran_source_compiles macro and -# sets CMAKE_REQUIRED_DEFINITIONS to . See help for -# CheckFortranSourceCompiles for a listing of variables that can -# otherwise modify the build. The result only tells that the compiler -# does not give an error message when it encounters the flag. If the -# flag has any effect or even a specific one is beyond the scope of -# this module. +#[=======================================================================[.rst: +CheckFortranCompilerFlag +------------------------ + +Check whether the Fortran compiler supports a given flag. + +.. command:: check_fortran_compiler_flag + + :: + + check_fortran_compiler_flag( ) + + Check that the ```` is accepted by the compiler without + a diagnostic. Stores the result in an internal cache entry + named ````. + +This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable +and calls the ``check_fortran_source_compiles`` macro from the +:module:`CheckFortranSourceCompiles` module. See documentation of that +module for a listing of variables that can otherwise modify the build. + +A positive result from this check indicates only that the compiler did not +issue a diagnostic message when given the flag. Whether the flag has any +effect or even a specific one is beyond the scope of this module. + +.. note:: + Since the :command:`try_compile` command forwards flags from variables + like :variable:`CMAKE_Fortran_FLAGS _FLAGS>`, unknown flags + in such variables may cause a false negative for this check. +#]=======================================================================] include(CheckFortranSourceCompiles) include(CMakeCheckCompilerFlagCommonPatterns) -- cgit v0.12