Imported Upstream version 3.20.2upstream/3.20.2

5 files changed, 50 insertions, 122 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index 24e43e93c..31de610b2 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -922,7 +922,8 @@ system search path like ``$ENV{PATH}``.  A search path will be converted
 to a cmake-style list separated by ``;`` characters.
 
 The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
-path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere).
+path with platform-specific slashes (``\`` on Windows hosts and ``/``
+elsewhere).
 
 Always use double quotes around the ``<path>`` to be sure it is treated
 as a single argument to this command.
diff --git a/Help/command/if.rst b/Help/command/if.rst
index f327ca943..fbf3e363f 100644
--- a/Help/command/if.rst
+++ b/Help/command/if.rst
@@ -153,7 +153,16 @@ File Operations
  only for full paths.
 
 ``if(IS_ABSOLUTE path)``
- True if the given path is an absolute path.
+ True if the given path is an absolute path.  Note the following special
+ cases:
+
+ * An empty ``path`` evaluates to false.
+ * On Windows hosts, any ``path`` that begins with a drive letter and colon
+   (e.g. ``C:``), a forward slash or a backslash will evaluate to true.
+   This means a path like ``C:no\base\dir`` will evaluate to true, even
+   though the non-drive part of the path is relative.
+ * On non-Windows hosts, any ``path`` that begins with a tilde (``~``)
+   evaluates to true.
 
 Comparisons
 """""""""""
diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst
index 0d15ddfc3..2c2b04cbe 100644
--- a/Help/manual/cmake-compile-features.7.rst
+++ b/Help/manual/cmake-compile-features.7.rst
@@ -130,118 +130,21 @@ Optional Compile Features
 =========================
 
 Compile features may be preferred if available, without creating a hard
-requirement.  For example, a library may provides alternative
-implementations depending on whether the ``cxx_variadic_templates``
-feature is available:
-
-.. code-block:: c++
-
-  #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
-  template<int I, int... Is>
-  struct Interface;
-
-  template<int I>
-  struct Interface<I>
-  {
-    static int accumulate()
-    {
-      return I;
-    }
-  };
-
-  template<int I, int... Is>
-  struct Interface
-  {
-    static int accumulate()
-    {
-      return I + Interface<Is...>::accumulate();
-    }
-  };
-  #else
-  template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
-  struct Interface
-  {
-    static int accumulate() { return I1 + I2 + I3 + I4; }
-  };
-  #endif
-
-Such an interface depends on using the correct preprocessor defines for the
-compiler features.  CMake can generate a header file containing such
-defines using the :module:`WriteCompilerDetectionHeader` module.  The
-module contains the ``write_compiler_detection_header`` function which
-accepts parameters to control the content of the generated header file:
-
-.. code-block:: cmake
-
-  write_compiler_detection_header(
-    FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
-    PREFIX Foo
-    COMPILERS GNU
-    FEATURES
-      cxx_variadic_templates
-  )
-
-Such a header file may be used internally in the source code of a project,
-and it may be installed and used in the interface of library code.
-
-For each feature listed in ``FEATURES``, a preprocessor definition
-is created in the header file, and defined to either ``1`` or ``0``.
-
-Additionally, some features call for additional defines, such as the
-``cxx_final`` and ``cxx_override`` features. Rather than being used in
-``#ifdef`` code, the ``final`` keyword is abstracted by a symbol
-which is defined to either ``final``, a compiler-specific equivalent, or
-to empty.  That way, C++ code can be written to unconditionally use the
-symbol, and compiler support determines what it is expanded to:
-
-.. code-block:: c++
-
-  struct Interface {
-    virtual void Execute() = 0;
-  };
-
-  struct Concrete Foo_FINAL {
-    void Execute() Foo_OVERRIDE;
-  };
-
-In this case, ``Foo_FINAL`` will expand to ``final`` if the
-compiler supports the keyword, or to empty otherwise.
-
-In this use-case, the CMake code will wish to enable a particular language
-standard if available from the compiler. The :prop_tgt:`CXX_STANDARD`
-target property variable may be set to the desired language standard
-for a particular target, and the :variable:`CMAKE_CXX_STANDARD` may be
-set to influence all following targets:
-
-.. code-block:: cmake
-
-  write_compiler_detection_header(
-    FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
-    PREFIX Foo
-    COMPILERS GNU
-    FEATURES
-      cxx_final cxx_override
-  )
-
-  # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
-  # which will expand to 'final' if the compiler supports the requested
-  # CXX_STANDARD.
-  add_library(foo foo.cpp)
-  set_property(TARGET foo PROPERTY CXX_STANDARD 11)
-
-  # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
-  # which will expand to 'final' if the compiler supports the feature,
-  # even though CXX_STANDARD is not set explicitly.  The requirement of
-  # cxx_constexpr causes CMake to set CXX_STANDARD internally, which
-  # affects the compile flags.
-  add_library(foo_impl foo_impl.cpp)
-  target_compile_features(foo_impl PRIVATE cxx_constexpr)
-
-The ``write_compiler_detection_header`` function also creates compatibility
-code for other features which have standard equivalents.  For example, the
-``cxx_static_assert`` feature is emulated with a template and abstracted
-via the ``<PREFIX>_STATIC_ASSERT`` and ``<PREFIX>_STATIC_ASSERT_MSG``
-function-macros.
+requirement.   This can be achieved by *not* specifying features with
+:command:`target_compile_features` and instead checking the compiler
+capabilities with preprocessor conditions in project code.
+
+In this use-case, the project may wish to establish a particular language
+standard if available from the compiler, and use preprocessor conditions
+to detect the features actually available.  A language standard may be
+established by `Requiring Language Standards`_ using
+:command:`target_compile_features` with meta-features like ``cxx_std_11``,
+or by setting the :prop_tgt:`CXX_STANDARD` target property or
+:variable:`CMAKE_CXX_STANDARD` variable.
+
+See also policy :policy:`CMP0120` and legacy documentation on
+:ref:`Example Usage <WCDH Example Usage>` of the deprecated
+:module:`WriteCompilerDetectionHeader` module.
 
 Conditional Compilation Options
 ===============================
@@ -284,13 +187,12 @@ while a header at ``no_variadics/interface.h`` may contain:
     static int accumulate() { return I1 + I2 + I3 + I4; }
   };
 
-It would be possible to write a abstraction ``interface.h`` header
+It may be possible to write an abstraction ``interface.h`` header
 containing something like:
 
 .. code-block:: c++
 
-  #include "foo_compiler_detection.h"
-  #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
+  #ifdef HAVE_CXX_VARIADIC_TEMPLATES
   #include "with_variadics/interface.h"
   #else
   #include "no_variadics/interface.h"
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 157ea5f9d..02828ac5b 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -105,6 +105,7 @@ Generator
   is already configured in the shell.  When using one of the
   :ref:`IDE Build Tool Generators`, no particular environment is needed.
 
+.. _`Generate a Project Buildsystem`:
 
 Generate a Project Buildsystem
 ==============================
diff --git a/Help/release/3.20.rst b/Help/release/3.20.rst
index e452926be..f77304fcf 100644
--- a/Help/release/3.20.rst
+++ b/Help/release/3.20.rst
@@ -47,11 +47,7 @@ Compilers
   * The ``icx``/``icpx`` C/C++ compilers on Linux, and the ``icx``
     C/C++ compiler on Windows, are fully supported as of oneAPI 2021.1.
 
-  * The ``ifx`` Fortran compiler on Linux is partially supported.
-    As of oneAPI 2021.1, ``ifx`` does not define several identification
-    macros, so CMake identifies it as the classic ``Intel`` compiler.
-    This works in many cases because ``ifx`` accepts the same command line
-    parameters as ``ifort``.  A future version of oneAPI may fix this.
+  * The ``ifx`` Fortran compiler on Linux is supported as of oneAPI 2021.1.
 
   * The ``ifx`` Fortran compiler on Windows is not yet supported.
 
@@ -298,6 +294,10 @@ Deprecated and Removed Features
 Other Changes
 =============
 
+* When running :manual:`cmake(1)` to :ref:`Generate a Project Buildsystem`,
+  unknown command-line arguments starting with a hyphen (``-``) are now
+  rejected with an error.  Previously they were silently ignored.
+
 * Source file extensions must now be explicit.
   See policy :policy:`CMP0115` for details.
 
@@ -347,3 +347,18 @@ Changes made since CMake 3.20.0 include the following.
   iOS, tvOS and watchOS should now default to ``@rpath`` instead of using
   a full absolute path and failing at runtime when the library or framework
   is embedded in an application bundle (see :prop_tgt:`XCODE_EMBED_<type>`).
+
+3.20.2
+------
+
+* The Intel Classic 2021 compiler version numbers are now detected correctly
+  as having major version 2021.  CMake 3.20.1 and below were not aware of a
+  change to the identification macro version scheme made by Intel starting
+  in version 2021, and detected the version as 20.2.
+
+* The Intel oneAPI Fortran compiler is now identified as ``IntelLLVM``.
+  The oneAPI 2021.1 Fortran compiler is missing an identification macro,
+  so CMake 3.20.1 and below identified it as ``Intel``.  CMake now has
+  a special case to recognize oneAPI 2021.1 Fortran as ``IntelLLVM``.
+  The oneAPI 2021.2 Fortran compiler defines the proper identification
+  macro and so is identified as ``IntelLLVM`` by all CMake 3.20 versions.