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

diff --git a/appveyor.sh b/appveyor.sh
index 3de37a6276bd4c1344ca733749a8c88687d6ce49..85588ed93110d59252cd96dd35fe74154c579f87 100644 (file)
--- a/appveyor.sh
+++ b/appveyor.sh
@@ -81,7 +81,7 @@ elif [ "${BUILD_SYSTEM}" = 'winbuild_vs2015' ]; then
     cat << EOF > _make.bat
       call "C:/Program Files/Microsoft SDKs/Windows/v7.1/Bin/SetEnv.cmd" /x64
       call "C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/vcvarsall.bat" x86_amd64
-      nmake -f Makefile.vc mode=dll VC=14 "SSL_PATH=${openssl_root_win}" WITH_SSL=dll MACHINE=x64 DEBUG=${DEBUG} ENABLE_UNICODE=${ENABLE_UNICODE}
+      nmake -f Makefile.vc mode=dll VC=14 "SSL_PATH=${openssl_root_win}" WITH_SSL=dll MACHINE=x64 DEBUG=${DEBUG} ENABLE_UNICODE=${ENABLE_UNICODE} WINBUILD_ACKNOWLEDGE_DEPRECATED=yes
 EOF
     ./_make.bat
     rm _make.bat
@@ -93,7 +93,7 @@ elif [ "${BUILD_SYSTEM}" = 'winbuild_vs2017' ]; then
     cd winbuild
     cat << EOF > _make.bat
       call "C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Auxiliary/Build/vcvars64.bat"
-      nmake -f Makefile.vc mode=dll VC=14.10 "SSL_PATH=${openssl_root_win}" WITH_SSL=dll MACHINE=x64 DEBUG=${DEBUG} ENABLE_UNICODE=${ENABLE_UNICODE}
+      nmake -f Makefile.vc mode=dll VC=14.10 "SSL_PATH=${openssl_root_win}" WITH_SSL=dll MACHINE=x64 DEBUG=${DEBUG} ENABLE_UNICODE=${ENABLE_UNICODE} WINBUILD_ACKNOWLEDGE_DEPRECATED=yes
 EOF
     ./_make.bat
     rm _make.bat

diff --git a/docs/DEPRECATE.md b/docs/DEPRECATE.md
index 24d594852ab9486de3a387b3bd0ddf317f2ca7fe..7f974a3f1c7767dcf966583afd0f980938242e55 100644 (file)
--- a/docs/DEPRECATE.md
+++ b/docs/DEPRECATE.md
@@ -37,6 +37,13 @@ their experimental status in a future.
 
 We remove msh3 support from the curl source tree in July 2025.
 
+## winbuild build system
+
+curl drops support for the winbuild build method after September 2025.
+
+We recommend migrating to CMake. See the migration guide in
+`docs/INSTALL-CMAKE.md`.
+
 ## Past removals
 
  - Pipelining

diff --git a/docs/INSTALL-CMAKE.md b/docs/INSTALL-CMAKE.md
index 33622a3b2d32ad8d22aed0a5bc0ad3e16dc2ef35..a1774d7861397bcf459026d46396e44edec45dd0 100644 (file)
--- a/docs/INSTALL-CMAKE.md
+++ b/docs/INSTALL-CMAKE.md
@@ -252,6 +252,7 @@ assumes that CMake generates `Makefile`:
 
 ## CMake options
 
+- `CMAKE_BUILD_TYPE`:                       (see CMake)
 - `CMAKE_DEBUG_POSTFIX`:                    Default: `-d`
 - `CMAKE_IMPORT_LIBRARY_SUFFIX`             (see CMake)
 - `CMAKE_INSTALL_BINDIR`                    (see CMake)
@@ -374,3 +375,95 @@ Details via CMake
 - `HTTPD`:                                  Default: `apache2`
 - `TEST_NGHTTPX`:                           Default: `nghttpx`
 - `VSFTPD`:                                 Default: `vsftps`
+
+# Migrating from Visual Studio IDE Project Files
+
+We recommend CMake to build curl with MSVC.
+
+The project build files reside in project/Windows/VC\* for VS2010, VS2010 and
+VS2013 respectively.
+
+These CMake Visual Studio generators require CMake v3.24 or older. You can
+download them from <https://cmake.org/files/v3.24/>.
+
+You can also use `-G "NMake Makefiles"`, which is supported by all CMake
+versions.
+
+Configuration element             | Equivalent CMake options
+:-------------------------------- | :--------------------------------
+`VC10`                            | `-G "Visual Studio 10 2010"`
+`VC11`                            | `-G "Visual Studio 11 2012"`
+`VC12`                            | `-G "Visual Studio 12 2013"`
+`x64`                             | `-A x64`
+`Win32`                           | `-A Win32`
+`DLL`                             | `BUILD_SHARED_LIBS=ON`, `BUILD_STATIC_LIBS=OFF`, (default)
+`LIB`                             | `BUILD_SHARED_LIBS=OFF`, `BUILD_STATIC_LIBS=ON`
+`Debug`                           | `CMAKE_BUILD_TYPE=Debug`
+`Release`                         | `CMAKE_BUILD_TYPE=Release`
+`DLL Windows SSPI`                | `CURL_USE_SCHANNEL=ON` (with SSPI enabled by default)
+`DLL OpenSSL`                     | `CURL_USE_OPENSSL=ON`, optional: `OPENSSL_ROOT_DIR`, `OPENSSL_USE_STATIC_LIBS=ON`
+`DLL libssh2`                     | `CURL_USE_LIBSSH2=ON`, optional: `LIBSSH2_INCLUDE_DIR`, `LIBSSH2_LIBRARY`
+`DLL WinIDN`                      | `USE_WIN32_IDN=ON`
+
+For example these commands:
+
+    > cd projects
+    > ./generate.bat VC12
+    > msbuild "-property:Configuration=DLL Debug - DLL Windows SSPI - DLL WinIDN" Windows/VC12/curl-all.sln
+
+translate to:
+
+    > cmake . -G "Visual Studio 12 2013" -A x64 -DCMAKE_BUILD_TYPE=Debug -DCURL_USE_SCHANNEL=ON -DUSE_WIN32_IDN=ON -DCURL_USE_LIBPSL=OFF
+
+# Migrating from winbuild builds
+
+We recommend CMake to build curl with MSVC. The winbuild build method is
+deprecated and may be dropped in a future release.
+
+In CMake you can customize the path of dependencies by passing the absolute
+header path and the full path of the library via `*_INCLUDE_DIR` and
+`*_LIBRARY` options (see the complete list in the option listing above).
+The full path to the library can point to a static library or an import
+library, which defines if the dependency is linked as a dll or statically.
+For OpenSSL this works
+[differently](https://cmake.org/cmake/help/latest/module/FindOpenSSL.html):
+You can pass the root directory of the OpenSSL installation via
+`OPENSSL_ROOT_DIR`, then pass `OPENSSL_USE_STATIC_LIBS=ON` to select static
+libs.
+
+winbuild options                  | Equivalent CMake options
+:-------------------------------- | :--------------------------------
+`DEBUG`                           | `CMAKE_BUILD_TYPE=Debug`
+`GEN_PDB`                         | `CMAKE_EXE_LINKER_FLAGS=/Fd<path>`, `CMAKE_SHARED_LINKER_FLAGS=/Fd<path>`
+`LIB_NAME_DLL`, `LIB_NAME_STATIC` | `IMPORT_LIB_SUFFIX`, `LIBCURL_OUTPUT_NAME`, `STATIC_LIB_SUFFIX`
+`VC`                              | see CMake `-G` [options](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
+`MACHINE`: `x64`, `x86`           | `-A x64`, `-A Win32`
+`MODE`: `dll`, `static`           | `BUILD_SHARED_LIBS=ON/OFF`, `BUILD_STATIC_LIBS=ON/OFF`, `BUILD_STATIC_CURL=ON/OFF` (default: dll)
+`RTLIBCFG`: `static`              | `CURL_STATIC_CRT=ON`
+`ENABLE_IDN`                      | `USE_WIN32_IDN=ON`
+`ENABLE_IPV6`                     | `ENABLE_IPV6=ON`
+`ENABLE_MSH3`                     | `USE_MSH3=ON`
+`ENABLE_NGHTTP2`                  | `USE_NGHTTP2=ON`
+`ENABLE_OPENSSL_AUTO_LOAD_CONFIG` | `CURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG=OFF` (default)
+`ENABLE_SCHANNEL`                 | `CURL_USE_SCHANNEL=ON`
+`ENABLE_SSPI`                     | `CURL_WINDOWS_SSPI=ON` (default with Schannel)
+`ENABLE_UNICODE`                  | `ENABLE_UNICODE=ON`
+`WITH_PREFIX`                     | `CMAKE_INSTALL_PREFIX=<path>`
+`WITH_DEVEL`                      | see individual `*_INCLUDE_DIR` and `*_LIBRARY` options and `OPENSSL_ROOT_DIR`
+`WITH_CARES`, `CARES_PATH`        | `ENABLE_ARES=ON`, optional: `CARES_INCLUDE_DIR`, `CARES_LIBRARY`
+`WITH_MBEDTLS`, `MBEDTLS_PATH`    | `CURL_USE_MBEDTLS=ON`, optional: `MBEDTLS_INCLUDE_DIR`, `MBEDTLS_LIBRARY`, `MBEDX509_LIBRARY`, `MBEDCRYPTO_LIBRARY`
+`WITH_MSH3`, `MSH_PATH`           | `USE_MSH3=ON`, optional: `MSH3_INCLUDE_DIR`, `MSH3_LIBRARY`
+`WITH_NGHTTP2`, `NGHTTP2_PATH`    | `USE_NGHTTP2=ON`, optional: `NGHTTP2_INCLUDE_DIR`, `NGHTTP2_LIBRARY`
+`WITH_SSH`, `SSH_PATH`            | `CURL_USE_LIBSSH=ON`, optional: `LIBSSH_INCLUDE_DIR`, `LIBSSH_LIBRARY`
+`WITH_SSH2`, `SSH2_PATH`          | `CURL_USE_LIBSSH2=ON`, optional: `LIBSSH2_INCLUDE_DIR`, `LIBSSH2_LIBRARY`
+`WITH_SSL`, `SSL_PATH`            | `CURL_USE_OPENSSL=ON`, optional: `OPENSSL_ROOT_DIR`, `OPENSSL_USE_STATIC_LIBS=ON`
+`WITH_WOLFSSL`, `WOLFSSL_PATH`    | `CURL_USE_WOLFSSL=ON`, optional: `WOLFSSL_INCLUDE_DIR`, `WOLFSSL_LIBRARY`
+`WITH_ZLIB`, `ZLIB_PATH`          | `CURL_ZLIB=ON`, optional: `ZLIB_INCLUDE_DIR`, `ZLIB_LIBRARY`
+
+For example this command-line:
+
+    > nmake -f Makefile.vc VC=17 MACHINE=x64 DEBUG=ON mode=dll SSL_PATH=C:\OpenSSL WITH_SSL=dll ENABLE_UNICODE=ON
+
+translates to:
+
+    > cmake . -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=ON -DOPENSSL_ROOT_DIR=C:\OpenSSL -DCURL_USE_OPENSSL=ON -DENABLE_UNICODE=ON -DCURL_USE_LIBPSL=OFF

diff --git a/winbuild/Makefile.vc b/winbuild/Makefile.vc
index bc20d05d85b2e55cf05f94391abebb57c8ffbc14..97fc761f295bfd3816bac4e3b89600f09b7e496c 100644 (file)
--- a/winbuild/Makefile.vc
+++ b/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

diff --git a/winbuild/README.md b/winbuild/README.md
index a7ac7db4e982b2e33d6d5f77bd93e2b007338e0e..14c308164579b43b21e1d451d779f477145a73ef 100644 (file)
--- a/winbuild/README.md
+++ b/winbuild/README.md
@@ -106,6 +106,7 @@ where `<options>` is one or many of:
  - `WOLFSSL_PATH=<path>`         - Custom path for wolfSSL\r
  - `NGHTTP2_PATH=<path>`         - Custom path for nghttp2\r
  - `MSH3_PATH=<path>`            - Custom path for msh3\r
+ - `SSH_PATH=<path>`             - Custom path for libssh\r
  - `SSH2_PATH=<path>`            - Custom path for libssh2\r
  - `SSL_PATH=<path>`             - Custom path for OpenSSL\r
  - `ZLIB_PATH=<path>`            - Custom path for zlib\r