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
2025-01-06 23:34:19 +01:00 · 2025-01-06 23:34:19 +01:00 · fdc588dc10
commit fdc588dc10
parent 0494566ae8
5 changed files with 118 additions and 2 deletions
--- 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
--- 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
--- 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
--- 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
--- 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
 - `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