Compile with explicit language flag when source LANGUAGE property is set

This change was originally made by commit 74b1c9fc8e (Explicitly specify
language flag when source LANGUAGE property is set, 2020-06-01,
v3.19.0-rc1~722^2), but it was reverted by commit 30aa715fac (Revert
"specify language flag when source LANGUAGE property is set",
2020-11-19) to restore compatibility with pre-3.19 behavior.

Implement the change again, but add policy CMP0119 to make this change
while preserving compatibility with existing projects.

Note that the `Compiler/{Clang,Intel,MSVC}-CXX` modules do not need to
specify `-TP` for their MSVC-like variants because we already use the
flag in `CMAKE_CXX_COMPILE_OBJECT`.  Similarly for `Compiler/XL-CXX`
and `Platform/Windows-Embarcadero`.

Note also that this does not seem possible to implement for XL C.
Even with `-qsourcetype=c`, `xlc` complains about an unknown suffix:
`1501-218 (W) file /.../AltExtC.zzz contains an incorrect file suffix`.
It returns non-zero even with `-qsuppress=1501-218`.

Co-Author: Robert Maynard <robert.maynard@kitware.com>
Fixes: #14516, #20716

4 files changed, 49 insertions, 1 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 6f9a24a..85b53c7 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.20
 .. toctree::
    :maxdepth: 1
 
+   CMP0119: LANGUAGE source file property explicitly compiles as language. </policy/CMP0119>
    CMP0118: The GENERATED source file property is now visible in all directories. </policy/CMP0118>
    CMP0117: MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default. </policy/CMP0117>
    CMP0116: Ninja generators transform DEPFILEs from add_custom_command(). </policy/CMP0116>
diff --git a/Help/policy/CMP0119.rst b/Help/policy/CMP0119.rst
new file mode 100644
index 0000000..61c8bdc
--- /dev/null
+++ b/Help/policy/CMP0119.rst
@@ -0,0 +1,36 @@
+CMP0119
+-------
+
+.. versionadded:: 3.20
+
+:prop_sf:`LANGUAGE` source file property explicitly compiles as specified
+language.
+
+The :prop_sf:`LANGUAGE` source file property is documented to mean that the
+source file is written in the specified language.  In CMake 3.19 and below,
+setting this property causes CMake to compile the source file using the
+compiler for the specified language.  However, it only passes an explicit
+flag to tell the compiler to treat the source as the specified language
+for MSVC-like, XL, and Embarcadero compilers for the ``CXX`` language.
+CMake 3.20 and above prefer to also explicitly tell the compiler to use
+the specified language using a flag such as ``-x c`` on all compilers
+for which such flags are known.
+
+This policy provides compatibility for projects that have not been updated
+to expect this behavior.  For example, some projects were setting the
+``LANGUAGE`` property to ``C`` on assembly-language ``.S`` source files
+in order to compile them using the C compiler.  Such projects should be
+updated to use ``enable_language(ASM)``, for which CMake will often choose
+the C compiler as the assembler on relevant platforms anyway.
+
+The ``OLD`` behavior for this policy is to interpret the ``LANGUAGE <LANG>``
+property using its undocumented meaning to "use the ``<LANG>`` compiler".
+The ``NEW`` behavior for this policy is to interpret the ``LANGUAGE <LANG>``
+property using its documented meaning to "compile as a ``<LANG>`` source".
+
+This policy was introduced in CMake version 3.20.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst
index 1dd2554..f14c176 100644
--- a/Help/prop_sf/LANGUAGE.rst
+++ b/Help/prop_sf/LANGUAGE.rst
@@ -1,7 +1,7 @@
 LANGUAGE
 --------
 
-What programming language is the file.
+Specify the programming language in which a source file is written.
 
 A property that can be set to indicate what programming language the
 source file is.  If it is not set the language is determined based on
@@ -9,3 +9,9 @@ the file extension.  Typical values are ``CXX`` (i.e.  C++), ``C``,
 ``CSharp``, ``CUDA``, ``Fortran``, ``ISPC``, and ``ASM``.  Setting this
 property for a file means this file will be compiled.  Do not set this
 for headers or files that should not be compiled.
+
+.. versionchanged:: 3.20
+  Setting this property causes the source file to be compiled as the
+  specified language, using explicit flags if possible.  Previously it
+  only caused the specified language's compiler to be used.
+  See policy :policy:`CMP0119`.
diff --git a/Help/release/dev/explicit-LANGUAGE-flag.rst b/Help/release/dev/explicit-LANGUAGE-flag.rst
new file mode 100644
index 0000000..4de4a47
--- /dev/null
+++ b/Help/release/dev/explicit-LANGUAGE-flag.rst
@@ -0,0 +1,5 @@
+explicit-LANGUAGE-flag
+----------------------
+
+* The :prop_sf:`LANGUAGE` source file property now forces compilation
+  as the specified language.  See policy :policy:`CMP0119`.