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