ARMClang: Do not automatically add cpu/arch compile or link options

The compile options `--march=<arch>` and `--mcpu=<cpu>` and the
link option `--cpu=<cpu>` are automatically added by CMake based
on `CMAKE_SYSTEM_PROCESSOR` or `CMAKE_SYSTEM_ARCH`. But this is not
sufficient, because armclang also supports enabling or disabling
features using `+<feature>`:

    -mcpu=<name>[+[no]<feature>+...]

For example:

    -mcpu=cortex-a57+nocrypto+nofp+nosimd+crc

(Reference: https://developer.arm.com/documentation/dui0774/k/Compiler-Command-line-Options/-mcpu?lang=en)

The problem is, even if a project adds a flag with features it needs,
CMake still adds flags, resulting in code that is compiled with wrong
CPU features and unable to run.

Add policy `CMP0123` to not automatically add compile or link options,
and let projects set them instead.

Co-Author: Brad King <brad.king@kitware.com>
Fixes: #21173

3 files changed, 40 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 5dfa894..b41ce59 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.21
 .. toctree::
    :maxdepth: 1
 
+   CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly. </policy/CMP0123>
    CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122>
    CMP0121: The list command detects invalid indicies. </policy/CMP0121>
 
diff --git a/Help/policy/CMP0123.rst b/Help/policy/CMP0123.rst
new file mode 100644
index 0000000..e09b5ec
--- /dev/null
+++ b/Help/policy/CMP0123.rst
@@ -0,0 +1,32 @@
+CMP0123
+-------
+
+.. versionadded:: 3.21
+
+``ARMClang`` cpu/arch compile and link flags must be set explicitly.
+
+CMake 3.20 and lower automatically maps the :variable:`CMAKE_SYSTEM_PROCESSOR`
+variable and an undocumented ``CMAKE_SYSTEM_ARCH`` to compile and link options
+for ``ARMClang``.  For example, the ``-mcpu=cortex-m33`` flag is added when
+:variable:`CMAKE_SYSTEM_PROCESSOR` equals ``cortex-m33``.  CMake requires
+projects to set either variable or it raises a fatal error.  However, the
+project may need to additionally specify CPU features using e.g.
+``-mcpu=cortex-m33+nodsp``, conflicting with the ``-mcpu=cortex-m33`` added
+by CMake.  This results in either link errors or unusable binaries.
+
+CMake 3.21 and above prefer instead to not add any cpu/arch compile and link
+flags automatically.  Instead, projects must specify them explicitly.
+This policy provides compatibility for projects that have not been updated.
+
+The ``OLD`` behavior of this policy requires projects that use ``ARMClang``
+to set either :variable:`CMAKE_SYSTEM_PROCESSOR` or ``CMAKE_SYSTEM_ARCH``
+and it automatically adds a compile option ``-mcpu=`` or ``-march=`` and
+a link option ``--cpu=`` based on those variables.  The ``NEW`` behavior
+does not add compile or link options, and projects are responsible for
+setting correct options.
+
+This policy was introduced in CMake version 3.21.  CMake version |release|
+warns when the policy is not set and uses ``OLD`` behavior.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/ARMClang-cpu-arch-flags.rst b/Help/release/dev/ARMClang-cpu-arch-flags.rst
new file mode 100644
index 0000000..5e885fe
--- /dev/null
+++ b/Help/release/dev/ARMClang-cpu-arch-flags.rst
@@ -0,0 +1,7 @@
+ARMClang-cpu-arch-flags
+-----------------------
+
+* ``ARMClang`` cpu/arch compile and link flags are no longer added
+  automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR`
+  variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable.
+  They must be specified explicitly.  See policy :policy:`CMP0123`.