From cfd92dece3df698e432bb628f15c432142bc662f Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 28 Jul 2023 15:08:51 -0400 Subject: CheckLanguage: Modernize documentation formatting --- Modules/CheckLanguage.cmake | 39 +++++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/Modules/CheckLanguage.cmake b/Modules/CheckLanguage.cmake index 69913a3..4c49d9a 100644 --- a/Modules/CheckLanguage.cmake +++ b/Modules/CheckLanguage.cmake @@ -5,26 +5,37 @@ CheckLanguage ------------- -Check if a language can be enabled +Check whether a language can be enabled by the :command:`enable_language` +or :command:`project` commands: -Usage: +.. command:: check_language -:: + .. code-block:: cmake - check_language() + check_language() -where ```` is a language that may be passed to :command:`enable_language` -such as ``Fortran``. If :variable:`CMAKE__COMPILER` is already defined -the check does nothing. Otherwise it tries enabling the language in a -test project. The result is cached in :variable:`CMAKE__COMPILER` -as the compiler that was found, or ``NOTFOUND`` if the language cannot be -enabled. For CUDA which can have an explicit host compiler, the cache -:variable:`CMAKE_CUDA_HOST_COMPILER` variable will be set if it was required -for compilation (and cleared if it was not). + Try enabling language ```` in a test project and record results + in the cache: -Example: + :variable:`CMAKE__COMPILER` + If the language can be enabled, this variable is set to the compiler + that was found. If the language cannot be enabled, this variable is + set to ``NOTFOUND``. -:: + If this variable is already set, either explicitly or cached by + a previous call, the check is skipped. + + :variable:`CMAKE_CUDA_HOST_COMPILER` + This variable is set when ```` is ``CUDA``. + + If the check detects an explicit host compiler that is required for + compilation, this variable will be set to that compiler. + If the check detects that no explicit host compiler is needed, + this variable will be cleared. + +For example: + +.. code-block:: cmake check_language(Fortran) if(CMAKE_Fortran_COMPILER) -- cgit v0.12 From 13d78bbf16fdf27f0bd1fcc366817510540e0f1d Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 28 Jul 2023 15:09:26 -0400 Subject: CheckLanguage: Document that CMAKE_CUDA_HOST_COMPILER should not be set alone Follow up commit 7968d9d442 (Help: Document CMAKE_CUDA_HOST_COMPILER as specific to NVIDIA nvcc, 2020-07-14, v3.19.0-rc1~501^2) with an explicit note in `CheckLanguage`. Issue: #25093 --- Modules/CheckLanguage.cmake | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Modules/CheckLanguage.cmake b/Modules/CheckLanguage.cmake index 4c49d9a..04e721c 100644 --- a/Modules/CheckLanguage.cmake +++ b/Modules/CheckLanguage.cmake @@ -33,6 +33,14 @@ or :command:`project` commands: If the check detects that no explicit host compiler is needed, this variable will be cleared. + If this variable is already set, its value is preserved only if + :variable:`CMAKE_CUDA_COMPILER _COMPILER>` is also set. + Otherwise, the check runs and overwrites + :variable:`CMAKE_CUDA_HOST_COMPILER` with a new result. + Note that :variable:`CMAKE_CUDA_HOST_COMPILER` documents it should + not be set without also setting + :variable:`CMAKE_CUDA_COMPILER _COMPILER>` to a NVCC compiler. + For example: .. code-block:: cmake -- cgit v0.12 From be03265fa0e9134f84466e4aa92e62afb78cbc83 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 28 Jul 2023 15:20:14 -0400 Subject: Help: Explicitly note that projects should not set CMAKE_CUDA_HOST_COMPILER Issue: #25093 --- Help/variable/CMAKE_CUDA_HOST_COMPILER.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst index 9817b1a..6e2d756 100644 --- a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -26,4 +26,11 @@ is read-only and changes to it are undefined behavior. .. note:: + Projects should not try to set ``CMAKE_CUDA_HOST_COMPILER`` to match + :variable:`CMAKE_CXX_COMPILER _COMPILER>` themselves. + It is the end-user's responsibility, not the project's, to ensure that + the C++ and CUDA compilers target the same ABI. + +.. note:: + Ignored when using :ref:`Visual Studio Generators`. -- cgit v0.12