cmake: deprecate winbuild, add migration guide from legacy build methods

We recommend migrating to CMake from winbuild and Visual Studio project
files. winbuild is deprecated and will be dropped in September 2025.

CMake supports all the features and options, with new ones added
promptly. It supports out-of-tree, unity and documentation builds.

- deprecate winbuild method in favour of CMake by September 2025.
- add migration guide from winbuild to CMake.
- add migration guide from Visual Studio Project Files to CMake.
- add deprecation message to winbuild.
  Need to ack with `WINBUILD_ACKNOWLEDGE_DEPRECATED=yes`
  Authored-by: Jay Satiro
- mention `CMAKE_BUILD_TYPE` option in `INSTALL-CMAKE`.
- document missing `SSH_PATH` winbuild option.

Closes #15920

winbuild/Makefile.vc

@@ -22,6 +22,21 @@
 #
 #***************************************************************************
 
+!MESSAGE
+!MESSAGE WARNING:
+!MESSAGE
+!MESSAGE The winbuild build system is deprecated and will be removed in
+!MESSAGE September 2025 in favor of the CMake build system.
+!MESSAGE
+!MESSAGE Please see docs/INSTALL-CMAKE.md : "Migrating from winbuild builds"
+!MESSAGE
+!MESSAGE To use the winbuild build system you must acknowledge this warning by
+!MESSAGE setting command line option WINBUILD_ACKNOWLEDGE_DEPRECATED=yes
+!MESSAGE
+!IF "$(WINBUILD_ACKNOWLEDGE_DEPRECATED)"!="yes"
+!ERROR The user must acknowledge the deprecation warning to continue.
+!ENDIF
+
 !IF "$(MODE)"=="static"
 TARGET = $(LIB_NAME_STATIC)
 AS_DLL = false

winbuild/README.md

@@ -106,6 +106,7 @@ where `<options>` is one or many of:
  - `WOLFSSL_PATH=<path>`         - Custom path for wolfSSL
  - `NGHTTP2_PATH=<path>`         - Custom path for nghttp2
  - `MSH3_PATH=<path>`            - Custom path for msh3
+ - `SSH_PATH=<path>`             - Custom path for libssh
  - `SSH2_PATH=<path>`            - Custom path for libssh2
  - `SSL_PATH=<path>`             - Custom path for OpenSSL
  - `ZLIB_PATH=<path>`            - Custom path for zlib