OpenWatcom: Allow specifying the runtime library

Add a `CMAKE_WATCOM_RUNTIME_LIBRARY` variable to control the
runtime library selection.  Add policy CMP0136 to switch to
in place of the old hard-coded default flags.

Fixes: #23178

9 files changed, 147 insertions, 0 deletions

diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index 08f8d5b..4b2a631 100644
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@@ -150,6 +150,7 @@ Other Behavior Settings
   * :variable:`CMAKE_LINK_SEARCH_END_STATIC`
   * :variable:`CMAKE_MSVC_RUNTIME_LIBRARY`
   * :variable:`CMAKE_POSITION_INDEPENDENT_CODE`
+  * :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
 
   If :policy:`CMP0056` is set to ``NEW``, then
   :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well.
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index b3091fa..259cebb 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -58,6 +58,7 @@ Policies Introduced by CMake 3.24
 .. toctree::
    :maxdepth: 1
 
+   CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136>
    CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135>
    CMP0134: Fallback to \"HOST\" Windows registry view when \"TARGET\" view is not usable. </policy/CMP0134>
    CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133>
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 8c2f8c4..f86fdfe 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -423,6 +423,7 @@ Properties on Targets
    /prop_tgt/VS_WINRT_COMPONENT
    /prop_tgt/VS_WINRT_EXTENSIONS
    /prop_tgt/VS_WINRT_REFERENCES
+   /prop_tgt/WATCOM_RUNTIME_LIBRARY
    /prop_tgt/WIN32_EXECUTABLE
    /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS
    /prop_tgt/XCODE_ATTRIBUTE_an-attribute
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 98fc228..5c66088 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -521,6 +521,7 @@ Variables that Control the Build
    /variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES
    /variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES
    /variable/CMAKE_VS_WINRT_BY_DEFAULT
+   /variable/CMAKE_WATCOM_RUNTIME_LIBRARY
    /variable/CMAKE_WIN32_EXECUTABLE
    /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
    /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute
diff --git a/Help/policy/CMP0136.rst b/Help/policy/CMP0136.rst
new file mode 100644
index 0000000..4a718e9
--- /dev/null
+++ b/Help/policy/CMP0136.rst
@@ -0,0 +1,49 @@
+CMP0136
+-------
+
+.. versionadded:: 3.24
+
+Watcom runtime library flags are selected by an abstraction.
+
+Compilers targeting the Watcom ABI have flags to select the Watcom runtime
+library.
+
+In CMake 3.23 and below, Watcom runtime library selection flags are added to
+the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake
+automatically.  This allows users to edit their cache entries to adjust the
+flags.  However, the presence of such default flags is problematic for
+projects that want to choose a different runtime library programmatically.
+In particular, it requires string editing of the
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the
+CMake builtin defaults so they can be replaced.
+
+CMake 3.24 and above prefer to leave the Watcom runtime library selection flags
+out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead
+offer a first-class abstraction.  The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
+variable and :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property may be set to
+select the Watcom runtime library.  If they are not set then CMake uses the
+default value ``MultiThreadedDLL`` which is equivalent to the original flags.
+
+This policy provides compatibility with projects that have not been updated
+to be aware of the abstraction.  The policy setting takes effect as of the
+first :command:`project` or :command:`enable_language` command that enables
+a language whose compiler targets the Watcom ABI.
+
+.. note::
+
+  Once the policy has taken effect at the top of a project, that choice
+  must be used throughout the tree.  In projects that have nested projects
+  in subdirectories, be sure to convert everything together.
+
+The ``OLD`` behavior for this policy is to place Watcom runtime library
+flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
+entries and ignore the :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` abstraction.
+The ``NEW`` behavior for this policy is to *not* place Watcom runtime
+library flags in the default cache entries and use the abstraction instead.
+
+This policy was introduced in CMake version 3.24.  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_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt
new file mode 100644
index 0000000..c29d73e
--- /dev/null
+++ b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt
@@ -0,0 +1,18 @@
+``SingleThreaded``
+  Compile without additional flags to use a single-threaded
+  statically-linked runtime library.
+``SingleThreadedDLL``
+  Compile with ``-br`` or equivalent flag(s) to use a single-threaded
+  dynamically-linked runtime library.
+``MultiThreaded``
+  Compile with ``-bm`` or equivalent flag(s) to use a multi-threaded
+  statically-linked runtime library.
+``MultiThreadedDLL``
+  Compile with ``-bm -br`` or equivalent flag(s) to use a multi-threaded
+  dynamically-linked runtime library.
+
+The value is ignored on non-Watcom compilers but an unsupported value will
+be rejected as an error when using a compiler targeting the Watcom ABI.
+
+The value may also be the empty string (``""``) in which case no runtime
+library selection flag will be added explicitly by CMake.
diff --git a/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst
new file mode 100644
index 0000000..9f031fa
--- /dev/null
+++ b/Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst
@@ -0,0 +1,33 @@
+WATCOM_RUNTIME_LIBRARY
+----------------------
+
+.. versionadded:: 3.24
+
+Select the Watcom runtime library for use by compilers targeting the Watcom ABI.
+
+The allowed values are:
+
+.. include:: WATCOM_RUNTIME_LIBRARY-VALUES.txt
+
+Use :manual:`generator expressions <cmake-generator-expressions(7)>` to
+support per-configuration specification.
+
+For example, the code:
+
+.. code-block:: cmake
+
+  add_executable(foo foo.c)
+  set_property(TARGET foo PROPERTY
+    WATCOM_RUNTIME_LIBRARY "MultiThreaded")
+
+selects for the target ``foo`` a multi-threaded statically-linked runtime
+library.
+
+If this property is not set then CMake uses the default value
+``MultiThreadedDLL`` to select a Watcom runtime library.
+
+.. note::
+
+  This property has effect only when policy :policy:`CMP0136` is set to ``NEW``
+  prior to the first :command:`project` or :command:`enable_language` command
+  that enables a language using a compiler targeting the Watcom ABI.
diff --git a/Help/release/dev/watcom-runtime-library.rst b/Help/release/dev/watcom-runtime-library.rst
new file mode 100644
index 0000000..3a07b32
--- /dev/null
+++ b/Help/release/dev/watcom-runtime-library.rst
@@ -0,0 +1,7 @@
+watcom-runtime-library
+----------------------
+
+* The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and
+  :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to
+  select the runtime library used by compilers targeting the Watcom ABI.
+  See policy :policy:`CMP0136`.
diff --git a/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst
new file mode 100644
index 0000000..979a533
--- /dev/null
+++ b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst
@@ -0,0 +1,36 @@
+CMAKE_WATCOM_RUNTIME_LIBRARY
+----------------------------
+
+.. versionadded:: 3.24
+
+Select the Watcom runtime library for use by compilers targeting the Watcom ABI.
+This variable is used to initialize the :prop_tgt:`WATCOM_RUNTIME_LIBRARY`
+property on all targets as they are created.  It is also propagated by
+calls to the :command:`try_compile` command into the test project.
+
+The allowed values are:
+
+.. include:: ../prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt
+
+Use :manual:`generator expressions <cmake-generator-expressions(7)>` to
+support per-configuration specification.
+
+For example, the code:
+
+.. code-block:: cmake
+
+  set(CMAKE_WATCOM_RUNTIME_LIBRARY "MultiThreaded")
+
+selects for all following targets a multi-threaded statically-linked runtime
+library.
+
+If this variable is not set then the :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target
+property will not be set automatically.  If that property is not set then
+CMake uses the default value ``MultiThreadedDLL`` to select a Watcom runtime
+library.
+
+.. note::
+
+  This variable has effect only when policy :policy:`CMP0136` is set to ``NEW``
+  prior to the first :command:`project` or :command:`enable_language` command
+  that enables a language using a compiler targeting the Watcom ABI.