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