1# Building curl with Visual C++ 2 3 This document describes how to compile, build and install curl and libcurl 4 from sources using the Visual C++ build tool. To build with VC++, you will of 5 course have to first install VC++. The minimum required version of VC is 6 6 (part of Visual Studio 6). However using a more recent version is strongly 7 recommended. 8 9 VC++ is also part of the Windows Platform SDK. You do not have to install the 10 full Visual Studio or Visual C++ if all you want is to build curl. 11 12 The latest Platform SDK can be downloaded freely from [Windows SDK and 13 emulator 14 archive](https://developer.microsoft.com/en-us/windows/downloads/sdk-archive) 15 16## Prerequisites 17 18 If you wish to support zlib, openssl, c-ares, ssh2, you will have to download 19 them separately and copy them to the deps directory as shown below: 20 21 somedirectory\ 22 |_curl-src 23 | |_winbuild 24 | 25 |_deps 26 |_ lib 27 |_ include 28 |_ bin 29 30 It is also possible to create the deps directory in some other random places 31 and tell the Makefile its location using the WITH_DEVEL option. 32 33## Building straight from git 34 35 When you check out code git and build it, as opposed from a released source 36 code archive, you need to first run the `buildconf.bat` batch file (present 37 in the source code root directory) to set things up. 38 39## Open a command prompt 40 41Open a Visual Studio Command prompt: 42 43 Using the **'Developer Command Prompt for VS [version]'** menu entry: where 44 [version} is the Visual Studio version. The developer prompt at default uses 45 the x86 mode. It is required to call `Vcvarsall.bat` to setup the prompt for 46 the machine type you want. This type of command prompt may not exist in all 47 Visual Studio versions. 48 49 See also: [Developer Command Prompt for Visual 50 Studio](https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs) 51 and [How to: Enable a 64-Bit, x64 hosted MSVC toolset on the command 52 line](https://docs.microsoft.com/en-us/cpp/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line) 53 54 Using the **'VS [version] [platform] [type] Command Prompt'** menu entry: 55 where [version] is the Visual Studio version, [platform] is e.g. x64 and 56 [type] Native of Cross platform build. This type of command prompt may not 57 exist in all Visual Studio versions. 58 59 See also: [Set the Path and Environment Variables for Command-Line Builds](https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx) 60 61## Build in the console 62 63 Once you are in the console, go to the winbuild directory in the Curl 64 sources: 65 66 cd curl-src\winbuild 67 68 Then you can call `nmake /f Makefile.vc` with the desired options (see 69 below). The builds will be in the top src directory, `builds\` directory, in 70 a directory named using the options given to the nmake call. 71 72 nmake /f Makefile.vc mode=<static or dll> <options> 73 74where `<options>` is one or many of: 75 76 - `VC=<num>` - VC version. 6 or later. 77 - `WITH_DEVEL=<path>` - Paths for the development files (SSL, zlib, etc.) 78 Defaults to sibbling directory deps: ../deps 79 Libraries can be fetched at https://windows.php.net/downloads/php-sdk/deps/ 80 Uncompress them into the deps folder. 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_MBEDTLS=<dll/static>` - Enable mbedTLS support, DLL or static 84 - `WITH_CARES=<dll/static>` - Enable c-ares support, DLL or static 85 - `WITH_ZLIB=<dll/static>` - Enable zlib support, DLL or static 86 - `WITH_SSH2=<dll/static>` - Enable libSSH2 support, DLL or static 87 - `WITH_PREFIX=<dir>` - Where to install the build 88 - `ENABLE_SSPI=<yes/no>` - Enable SSPI support, defaults to yes 89 - `ENABLE_IPV6=<yes/no>` - Enable IPv6, defaults to yes 90 - `ENABLE_IDN=<yes or no>` - Enable use of Windows IDN APIs, defaults to yes 91 Requires Windows Vista or later 92 - `ENABLE_SCHANNEL=<yes/no>` - Enable native Windows SSL support, defaults 93 to yes if SSPI and no other SSL library 94 - `ENABLE_OPENSSL_AUTO_LOAD_CONFIG=<yes/no>` 95 - Enable loading OpenSSL configuration 96 automatically, defaults to yes 97 - `ENABLE_UNICODE=<yes/no>` - Enable UNICODE support, defaults to no 98 - `GEN_PDB=<yes/no>` - Generate External Program Database 99 (debug symbols for release build) 100 - `DEBUG=<yes/no>` - Debug builds 101 - `MACHINE=<x86/x64>` - Target architecture (default is x86) 102 - `CARES_PATH=<path>` - Custom path for c-ares 103 - `MBEDTLS_PATH=<path>` - Custom path for mbedTLS 104 - `NGHTTP2_PATH=<path>` - Custom path for nghttp2 105 - `SSH2_PATH=<path>` - Custom path for libSSH2 106 - `SSL_PATH=<path>` - Custom path for OpenSSL 107 - `ZLIB_PATH=<path>` - Custom path for zlib 108 109## Static linking of Microsoft's C RunTime (CRT): 110 111 If you are using mode=static nmake will create and link to the static build 112 of libcurl but *not* the static CRT. If you must you can force nmake to link 113 in the static CRT by passing RTLIBCFG=static. Typically you shouldn't use 114 that option, and nmake will default to the DLL CRT. RTLIBCFG is rarely used 115 and therefore rarely tested. When passing RTLIBCFG for a configuration that 116 was already built but not with that option, or if the option was specified 117 differently, you must destroy the build directory containing the 118 configuration so that nmake can build it from scratch. 119 120## Building your own application with a static libcurl 121 122 When building an application that uses the static libcurl library on Windows, 123 you must define CURL_STATICLIB. Otherwise the linker will look for dynamic 124 import symbols. 125 126## Legacy Windows and SSL 127 128 When you build curl using the build files in this directory the default SSL 129 backend will be Schannel (Windows SSPI), the native SSL library that comes 130 with the Windows OS. Schannel in Windows <= XP is not able to connect to 131 servers that no longer support the legacy handshakes and algorithms used by 132 those versions. If you will be using curl in one of those earlier versions of 133 Windows you should choose another SSL backend like OpenSSL. 134