1CMP0091
2-------
3
4.. versionadded:: 3.15
5
6MSVC runtime library flags are selected by an abstraction.
7
8Compilers targeting the MSVC ABI have flags to select the MSVC runtime library.
9Runtime library selection typically varies with build configuration because
10there is a separate runtime library for Debug builds.
11
12In CMake 3.14 and below, MSVC runtime library selection flags are added to
13the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake
14automatically.  This allows users to edit their cache entries to adjust the
15flags.  However, the presence of such default flags is problematic for
16projects that want to choose a different runtime library programmatically.
17In particular, it requires string editing of the
18:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the
19CMake builtin defaults so they can be replaced.
20
21CMake 3.15 and above prefer to leave the MSVC runtime library selection flags
22out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead
23offer a first-class abstraction.  The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY`
24variable and :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property may be set to
25select the MSVC runtime library.  If they are not set then CMake uses the
26default value ``MultiThreaded$<$<CONFIG:Debug>:Debug>DLL`` which is
27equivalent to the original flags.
28
29This policy provides compatibility with projects that have not been updated
30to be aware of the abstraction.  The policy setting takes effect as of the
31first :command:`project` or :command:`enable_language` command that enables
32a language whose compiler targets the MSVC ABI.
33
34.. note::
35
36  Once the policy has taken effect at the top of a project, that choice
37  must be used throughout the tree.  In projects that have nested projects
38  in subdirectories, be sure to convert everything together.
39
40The ``OLD`` behavior for this policy is to place MSVC runtime library
41flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
42entries and ignore the :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` abstraction.
43The ``NEW`` behavior for this policy is to *not* place MSVC runtime
44library flags in the default cache entries and use the abstraction instead.
45
46This policy was introduced in CMake version 3.15.  Use the
47:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
48Unlike many policies, CMake version |release| does *not* warn
49when this policy is not set and simply uses ``OLD`` behavior.
50
51.. include:: DEPRECATED.txt
52