diff options
Diffstat (limited to 'Help/policy')
| -rw-r--r-- | Help/policy/CMP0026.rst | 4 | ||||
| -rw-r--r-- | Help/policy/CMP0051.rst | 2 | ||||
| -rw-r--r-- | Help/policy/CMP0115.rst | 34 | ||||
| -rw-r--r-- | Help/policy/CMP0116.rst | 41 | ||||
| -rw-r--r-- | Help/policy/CMP0117.rst | 43 | ||||
| -rw-r--r-- | Help/policy/CMP0118.rst | 25 | ||||
| -rw-r--r-- | Help/policy/CMP0119.rst | 36 | ||||
| -rw-r--r-- | Help/policy/CMP0120.rst | 47 |
8 files changed, 229 insertions, 3 deletions
diff --git a/Help/policy/CMP0026.rst b/Help/policy/CMP0026.rst index 3401d4a..e08fd54 100644 --- a/Help/policy/CMP0026.rst +++ b/Help/policy/CMP0026.rst @@ -9,12 +9,12 @@ determine the eventual location of build targets. This relies on the assumption that all necessary information is available at configure-time to determine the final location and filename of the target. However, this property is not fully determined until later at -generate-time. At generate time, the ``$<TARGET_FILE>`` generator +generate-time. At generate time, the :genex:`$<TARGET_FILE>` generator expression can be used to determine the eventual :prop_tgt:`LOCATION` of a target output. Code which reads the :prop_tgt:`LOCATION` target property can be ported to -use the ``$<TARGET_FILE>`` generator expression together with the +use the :genex:`$<TARGET_FILE>` generator expression together with the :command:`file(GENERATE)` subcommand to generate a file containing the target location. diff --git a/Help/policy/CMP0051.rst b/Help/policy/CMP0051.rst index 053bc97..3558909 100644 --- a/Help/policy/CMP0051.rst +++ b/Help/policy/CMP0051.rst @@ -3,7 +3,7 @@ CMP0051 .. versionadded:: 3.1 -List TARGET_OBJECTS in SOURCES target property. +List :genex:`TARGET_OBJECTS` in SOURCES target property. CMake 3.0 and lower did not include the ``TARGET_OBJECTS`` :manual:`generator expression <cmake-generator-expressions(7)>` when diff --git a/Help/policy/CMP0115.rst b/Help/policy/CMP0115.rst new file mode 100644 index 0000000..7f82c43 --- /dev/null +++ b/Help/policy/CMP0115.rst @@ -0,0 +1,34 @@ +CMP0115 +------- + +.. versionadded:: 3.20 + +Source file extensions must be explicit. + +In CMake 3.19 and below, if a source file could not be found by the name +specified, it would append a list of known extensions to the name to see if +the file with the extension could be found. For example, this would allow the +user to run: + +.. code-block:: cmake + + add_executable(exe main) + +and put ``main.c`` in the executable without specifying the extension. + +Starting in CMake 3.20, CMake prefers all source files to have their extensions +explicitly listed: + +.. code-block:: cmake + + add_executable(exe main.c) + +The ``OLD`` behavior for this policy is to implicitly append known extensions +to source files if they can't be found. The ``NEW`` behavior of this policy is +to not append known extensions and require them to be explicit. + +This policy was introduced in CMake version 3.20. 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/policy/CMP0116.rst b/Help/policy/CMP0116.rst new file mode 100644 index 0000000..18e5a96 --- /dev/null +++ b/Help/policy/CMP0116.rst @@ -0,0 +1,41 @@ +CMP0116 +------- + +.. versionadded:: 3.20 + +Ninja generators transform ``DEPFILE`` s from :command:`add_custom_command`. + +In CMake 3.19 and below, files given to the ``DEPFILE`` argument of +:command:`add_custom_command` were passed directly to Ninja's ``depfile`` +variable without any path resolution. This meant that if +:command:`add_custom_command` was called from a subdirectory (created by +:command:`add_subdirectory`), the ``DEPFILE`` argument would have to be either +an absolute path or a path relative to :variable:`CMAKE_BINARY_DIR`, rather +than :variable:`CMAKE_CURRENT_BINARY_DIR`. In addition, no transformation was +done on the file listed in ``DEPFILE``, which meant that the paths within the +``DEPFILE`` had the same restrictions. + +Starting with CMake 3.20, the ``DEPFILE`` argument is relative to +:variable:`CMAKE_CURRENT_BINARY_DIR` (unless it is absolute), and the paths in +the ``DEPFILE`` are also relative to :variable:`CMAKE_CURRENT_BINARY_DIR`. +CMake automatically transforms the paths in the ``DEPFILE`` (unless they are +absolute) after the custom command is run. The file listed in ``DEPFILE`` is +not modified in any way. Instead, CMake writes the transformation to its own +internal file, and passes this internal file to Ninja's ``depfile`` variable. +This transformation happens regardless of whether or not ``DEPFILE`` is +relative, and regardless of whether or not :command:`add_custom_command` is +called from a subdirectory. + +The ``OLD`` behavior for this policy is to pass the ``DEPFILE`` to Ninja +unaltered. The ``NEW`` behavior for this policy is to transform the ``DEPFILE`` +after running the custom command. The status of ``CMP0116`` is recorded at the +time of the custom command's creation, and you can have custom commands in the +same directory with different values for ``CMP0116`` by setting the policy +before each custom command. + +This policy was introduced in CMake version 3.20. Unlike most policies, +CMake version |release| does *not* warn by default when this policy is not set +(unless ``DEPFILE`` is used in a subdirectory) and simply uses ``OLD`` +behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0116 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. diff --git a/Help/policy/CMP0117.rst b/Help/policy/CMP0117.rst new file mode 100644 index 0000000..0c4dd30 --- /dev/null +++ b/Help/policy/CMP0117.rst @@ -0,0 +1,43 @@ +CMP0117 +------- + +.. versionadded:: 3.20 + +MSVC RTTI flag ``/GR`` is not added to +:variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` by default. + +When using MSVC-like compilers in CMake 3.19 and below, the RTTI flag +``/GR`` is added to :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` by +default. This behavior is left from support for MSVC versions from Visual +Studio 2003 and below that did not enable RTTI by default. It is no longer +necessary. Furthermore, it is problematic for projects that want to change +to ``/GR-`` programmatically. In particular, it requires string editing of +the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable with knowledge +of the CMake builtin default so it can be replaced. + +CMake 3.20 and above prefer to leave out ``/GR`` from the value of +:variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` by default. + +This policy provides compatibility with projects that have not been updated +to expect the lack of the ``/GR`` flag. The policy setting takes effect as +of the first :command:`project` or :command:`enable_language` command that +initializes :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. + +.. note:: + + Once the policy has taken effect at the top of a project for a given + language, that choice must be used throughout the tree for that language. + In projects that have nested projects in subdirectories, be sure to + convert everything together. + +The ``OLD`` behavior for this policy is to place the MSVC ``/GR`` flag in the +default :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` cache entry. The +``NEW`` behavior for this policy is to *not* place the MSVC ``/GR`` flag in +the default cache entry. + +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/policy/CMP0118.rst b/Help/policy/CMP0118.rst new file mode 100644 index 0000000..aa7e0f7 --- /dev/null +++ b/Help/policy/CMP0118.rst @@ -0,0 +1,25 @@ +CMP0118 +------- + +.. versionadded:: 3.20 + +The :prop_sf:`GENERATED` source file property is now visible in all directories. + +Whether or not a source file is generated is an all-or-nothing global +property of the source. Consequently, the associated ``GENERATED`` +property is now visible from any directory scope, not only from the scope +for which it was set. + +Additionally, the ``GENERATED`` property may now be set only to boolean +values, and may not be turned off once turned on. + +The ``OLD`` behavior of this policy is to only allow ``GENERATED`` to be +visible from the directory scope for which it was set. The ``NEW`` +behavior on the other hand allows it to be visible from any scope. + +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 with regard +to visibility of the ``GENERATED`` property. However, CMake does warn +about setting the ``GENERATED`` property to a non-boolean value. 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/policy/CMP0120.rst b/Help/policy/CMP0120.rst new file mode 100644 index 0000000..9d2f6c9 --- /dev/null +++ b/Help/policy/CMP0120.rst @@ -0,0 +1,47 @@ +CMP0120 +------- + +.. versionadded:: 3.20 + +The :module:`WriteCompilerDetectionHeader` module is removed. + +CMake versions 3.1 through 3.19 provide this module to generate a +C++ compatibility layer by re-using information from CMake's table of +preprocessor checks for :manual:`cmake-compile-features(7)`. However: + +* Those granular features have been superseded by meta-features for + :ref:`Requiring Language Standards` such as ``cxx_std_11``. Therefore + no new granular feature checks will be added and projects will need to + use other means to conditionally use new C++ features. + +* The module exposes some of CMake's implementation details directly + to C++ translation units. + +* The module's approach effectively provides a header file with CMake, + thus tying the version of the header to the version of CMake. + Many projects found that the :module:`WriteCompilerDetectionHeader` was + best used by manually generating its header locally with a recent version + of CMake and then bundling it with the project source so that it could + be used with older CMake versions. + +For reasons including the above, CMake 3.20 and above prefer to not +provide the :module:`WriteCompilerDetectionHeader` module. This policy +provides compatibility for projects that have not been ported away from +it. Projects using the module should be updated to stop using it. +Alternatives include: + +* Bundle a copy of the generated header in the project's source. +* Use a third-party alternative, such as the CC0-licensed `Hedley`_. +* Drop support for compilers too old to provide the features natively. + +The ``OLD`` behavior of this policy is for inclusion of the deprecated +:module:`WriteCompilerDetectionHeader` module to work. The ``NEW`` +behavior is for inclusion of the module to fail as if it does not exist. + +This policy was introduced in CMake version 3.20. 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 + +.. _`Hedley`: https://nemequ.github.io/hedley/ |