README.md (9659B)
1 <!-- 2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4 SPDX-License-Identifier: curl 5 --> 6 7 # Deprecation warning 8 9 This winbuild build system is deprecated and is going to be removed in 10 September 2025 in favor of the CMake build system. 11 12 Please see docs/INSTALL-CMAKE.md : "Migrating from winbuild builds" 13 14 # Building curl with Visual C++ 15 16 This document describes how to compile, build and install curl and libcurl 17 from sources using the Visual C++ build tool. To build with VC++, you have to 18 first install VC++. The minimum required version of VC is 9 (part of Visual 19 Studio 2008). However using a more recent version is strongly recommended. 20 21 VC++ is also part of the Windows Platform SDK. You do not have to install the 22 full Visual Studio or Visual C++ if all you want is to build curl. 23 24 The latest Platform SDK can be downloaded freely from [Windows SDK and 25 emulator 26 archive](https://developer.microsoft.com/en-us/windows/downloads/sdk-archive) 27 28 ## Prerequisites 29 30 If you wish to support zlib, OpenSSL, c-ares, ssh2, you have to download them 31 separately and copy them to the `deps` directory as shown below: 32 33 somedirectory\ 34 |_curl-src 35 | |_winbuild 36 | 37 |_deps 38 |_ lib 39 |_ include 40 |_ bin 41 42 It is also possible to create the `deps` directory in some other random places 43 and tell the `Makefile` its location using the `WITH_DEVEL` option. 44 45 ## Open a command prompt 46 47 Open a Visual Studio Command prompt: 48 49 Using the **'VS [version] [platform] [type] Command Prompt'** menu entry: 50 where [version] is the Visual Studio version, [platform] is e.g. x64 and 51 [type] Native or Cross platform build. This type of command prompt may not 52 exist in all Visual Studio versions. For example, to build a 64-bit curl open 53 the x64 Native Tools prompt. 54 55 See also: 56 57 [How to: Enable a 64-Bit, x64 hosted MSVC toolset on the command line](https://docs.microsoft.com/en-us/cpp/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line) 58 59 [Set the Path and Environment Variables for Command-Line Builds](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line) 60 61 [Developer Command Prompt for Visual Studio](https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs) 62 63 ## Build in the console 64 65 Once you are in the console, go to the winbuild directory in the curl 66 sources: 67 68 cd curl-src\winbuild 69 70 Then you can call `nmake /f Makefile.vc` with the desired options (see 71 below). The builds are in the top src directory, `builds\` directory, in a 72 directory named using the options given to the nmake call. 73 74 nmake /f Makefile.vc mode=<static or dll> <options> 75 76 where `<options>` is one or many of: 77 78 - `VC=<num>` - VC version. 6 or later. 79 - `WITH_DEVEL=<path>` - Paths for the development files (SSL, zlib, etc.) 80 Defaults to sibling directory: `../deps` 81 - `WITH_SSL=<dll/static>` - Enable OpenSSL support, DLL or static 82 - `WITH_NGHTTP2=<dll/static>` - Enable HTTP/2 support, DLL or static 83 - `WITH_MSH3=<dll/static>` - Enable (experimental) HTTP/3 support, DLL or static 84 - `WITH_MBEDTLS=<dll/static>` - Enable mbedTLS support, DLL or static 85 - `WITH_WOLFSSL=<dll/static>` - Enable wolfSSL support, DLL or static 86 - `WITH_CARES=<dll/static>` - Enable c-ares support, DLL or static 87 - `WITH_ZLIB=<dll/static>` - Enable zlib support, DLL or static 88 - `WITH_SSH=<dll/static>` - Enable libssh support, DLL or static 89 - `WITH_SSH2=<dll/static>` - Enable libssh2 support, DLL or static 90 - `WITH_PREFIX=<dir>` - Where to install the build 91 - `ENABLE_SSPI=<yes/no>` - Enable SSPI support, defaults to yes 92 - `ENABLE_IPV6=<yes/no>` - Enable IPv6, defaults to yes 93 - `ENABLE_IDN=<yes or no>` - Enable use of Windows IDN APIs, defaults to yes 94 Requires Windows Vista or later 95 - `ENABLE_SCHANNEL=<yes/no>` - Enable native Windows SSL support, defaults 96 to yes if SSPI and no other SSL library 97 - `ENABLE_OPENSSL_AUTO_LOAD_CONFIG=<yes/no>` 98 - Enable loading OpenSSL configuration 99 automatically, defaults to yes 100 - `ENABLE_UNICODE=<yes/no>` - Enable Unicode support, defaults to no 101 - `GEN_PDB=<yes/no>` - Generate External Program Database 102 (debug symbols for release build) 103 - `DEBUG=<yes/no>` - Debug builds 104 - `MACHINE=<x86/x64/arm64>` - Target architecture (default is x86) 105 - `CARES_PATH=<path>` - Custom path for c-ares 106 - `MBEDTLS_PATH=<path>` - Custom path for mbedTLS 107 - `WOLFSSL_PATH=<path>` - Custom path for wolfSSL 108 - `NGHTTP2_PATH=<path>` - Custom path for nghttp2 109 - `MSH3_PATH=<path>` - Custom path for msh3 110 - `SSH_PATH=<path>` - Custom path for libssh 111 - `SSH2_PATH=<path>` - Custom path for libssh2 112 - `SSL_PATH=<path>` - Custom path for OpenSSL 113 - `ZLIB_PATH=<path>` - Custom path for zlib 114 115 ## Cleaning a build 116 117 For most build configurations you can remove a bad build by using the same 118 options with the added keyword "clean". For example: 119 120 nmake /f Makefile.vc mode=static clean 121 122 Build errors due to switching Visual Studio platform tools or mistakenly 123 specifying the wrong machine platform for the tools can usually be solved by 124 first cleaning the bad build. 125 126 ## Static linking of Microsoft's C runtime (CRT): 127 128 If you are using mode=static, nmake creates and links to the static build of 129 libcurl but *not* the static CRT. If you must you can force nmake to link in 130 the static CRT by passing `RTLIBCFG=static`. Typically you shouldn't use that 131 option, and nmake defaults to the DLL CRT. `RTLIBCFG` is rarely used and 132 therefore rarely tested. When passing `RTLIBCFG` for a configuration that was 133 already built but not with that option, or if the option was specified 134 differently, you must destroy the build directory containing the 135 configuration so that nmake can build it from scratch. 136 137 This option is not recommended unless you have enough development experience 138 to know how to match the runtime library for linking (that is, the CRT). If 139 `RTLIBCFG=static` then release builds use `/MT` and debug builds use `/MTd`. 140 141 ## Building your own application with libcurl (Visual Studio example) 142 143 When you build curl and libcurl, nmake shows the relative path where the 144 output directory is. The output directory is named from the options nmake 145 used when building. You may also see temp directories of the same name but 146 with suffixes -obj-curl and -obj-lib. 147 148 For example let's say you have built curl.exe and libcurl.dll from the Visual 149 Studio 2010 x64 Win64 Command Prompt: 150 151 nmake /f Makefile.vc mode=dll VC=10 152 153 The output directory has a name similar to 154 `..\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel`. 155 156 The output directory contains subdirectories bin, lib and include. Those are 157 the directories to set in your Visual Studio project. You can either copy the 158 output directory to your project or leave it in place. Following the example, 159 let's assume you leave it in place and your curl top source directory is 160 `C:\curl-7.82.0`. You would set these options for configurations using the 161 x64 platform: 162 163 ~~~ 164 - Configuration Properties > Debugging > Environment 165 PATH=C:\curl-7.82.0\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel\bin;%PATH% 166 167 - C/C++ > General > Additional Include Directories 168 C:\curl-7.82.0\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel\include; 169 170 - Linker > General > Additional Library Directories 171 C:\curl-7.82.0\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel\lib; 172 173 - Linker > Input > Additional Dependencies 174 libcurl.lib; 175 ~~~ 176 177 For configurations using the x86 platform (aka Win32 platform) you would 178 need to make a separate x86 build of libcurl. 179 180 If you build libcurl static (`mode=static`) or debug (`DEBUG=yes`) then the 181 library name varies and separate builds may be necessary for separate 182 configurations of your project within the same platform. This is discussed in 183 the next section. 184 185 ## Building your own application with a static libcurl 186 187 When building an application that uses the static libcurl library on Windows, 188 you must define `CURL_STATICLIB`. Otherwise the linker looks for dynamic 189 import symbols. 190 191 The static library name has an `_a` suffix in the basename and the debug 192 library name has a `_debug` suffix in the basename. For example, 193 `libcurl_a_debug.lib` is a static debug build of libcurl. 194 195 You may need a separate build of libcurl for each VC configuration combination 196 (for example: Debug|Win32, Debug|x64, Release|Win32, Release|x64). 197 198 You must specify any additional dependencies needed by your build of static 199 libcurl (for example: 200 `advapi32.lib;crypt32.lib;normaliz.lib;ws2_32.lib;wldap32.lib`). 201 202 ## Legacy Windows and SSL 203 204 When you build curl using the build files in this directory the default SSL 205 backend is Schannel (Windows SSPI), the native SSL library that comes with 206 the Windows OS. Schannel in Windows 8 and earlier is not able to connect to 207 servers that no longer support the legacy handshakes and algorithms used by 208 those versions. If you are using curl in one of those earlier versions of 209 Windows you should choose another SSL backend like OpenSSL.