From: Viktor Szakats Date: Mon, 6 Jan 2025 22:34:19 +0000 (+0100) Subject: cmake: deprecate winbuild, add migration guide from legacy build methods X-Git-Tag: curl-8_12_0~157 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fdc588dc10c6fc7e9a7adc03eee4cec69909defe;p=thirdparty%2Fcurl.git 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 3de37a6276..85588ed931 100644 --- 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 24d594852a..7f974a3f1c 100644 --- 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 33622a3b2d..a1774d7861 100644 --- 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 . + +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`, `CMAKE_SHARED_LINKER_FLAGS=/Fd` +`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=` +`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 bc20d05d85..97fc761f29 100644 --- 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 a7ac7db4e9..14c3081645 100644 --- a/winbuild/README.md +++ b/winbuild/README.md @@ -106,6 +106,7 @@ where `` is one or many of: - `WOLFSSL_PATH=` - Custom path for wolfSSL - `NGHTTP2_PATH=` - Custom path for nghttp2 - `MSH3_PATH=` - Custom path for msh3 + - `SSH_PATH=` - Custom path for libssh - `SSH2_PATH=` - Custom path for libssh2 - `SSL_PATH=` - Custom path for OpenSSL - `ZLIB_PATH=` - Custom path for zlib