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 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 **'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 will be in the top src directory, `builds\` directory, in
72 a directory named using the options given to the nmake call.
73
74 nmake /f Makefile.vc mode=<static or dll> <options>
75
76where `<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 - `SSH2_PATH=<path>` - Custom path for libssh2
111 - `SSL_PATH=<path>` - Custom path for OpenSSL
112 - `ZLIB_PATH=<path>` - Custom path for zlib
113
114## Cleaning a build
115
116 For most build configurations you can remove a bad build by using the same
117 options with the added keyword "clean". For example:
118
119 nmake /f Makefile.vc mode=static clean
120
121 Build errors due to switching Visual Studio platform tools or mistakenly
122 specifying the wrong machine platform for the tools can usually be solved by
123 first cleaning the bad build.
124
125## Static linking of Microsoft's C runtime (CRT):
126
127 If you are using mode=static nmake will create and link to the static build
128 of libcurl but *not* the static CRT. If you must you can force nmake to link
129 in the static CRT by passing `RTLIBCFG=static`. Typically you shouldn't use
130 that option, and nmake will default to the DLL CRT. `RTLIBCFG` is rarely used
131 and therefore rarely tested. When passing `RTLIBCFG` for a configuration that
132 was already built but not with that option, or if the option was specified
133 differently, you must destroy the build directory containing the
134 configuration so that nmake can build it from scratch.
135
136 This option is not recommended unless you have enough development experience
137 to know how to match the runtime library for linking (that is, the CRT). If
138 `RTLIBCFG=static` then release builds use `/MT` and debug builds use `/MTd`.
139
140## Building your own application with libcurl (Visual Studio example)
141
142 When you build curl and libcurl, nmake will show the relative path where the
143 output directory is. The output directory is named from the options nmake used
144 when building. You may also see temp directories of the same name but with
145 suffixes -obj-curl and -obj-lib.
146
147 For example let's say you've built curl.exe and libcurl.dll from the Visual
148 Studio 2010 x64 Win64 Command Prompt:
149
150 nmake /f Makefile.vc mode=dll VC=10
151
152 The output directory will have a name similar to
153 `..\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel`.
154
155 The output directory contains subdirectories bin, lib and include. Those are
156 the directories to set in your Visual Studio project. You can either copy the
157 output directory to your project or leave it in place. Following the example,
158 let's assume you leave it in place and your curl top source directory is
159 `C:\curl-7.82.0`. You would set these options for configurations using the
160 x64 platform:
161
162~~~
163 - Configuration Properties > Debugging > Environment
164 PATH=C:\curl-7.82.0\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel\bin;%PATH%
165
166 - C/C++ > General > Additional Include Directories
167 C:\curl-7.82.0\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel\include;
168
169 - Linker > General > Additional Library Directories
170 C:\curl-7.82.0\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel\lib;
171
172 - Linker > Input > Additional Dependencies
173 libcurl.lib;
174~~~
175
176 For configurations using the x86 platform (aka Win32 platform) you would
177 need to make a separate x86 build of libcurl.
178
179 If you build libcurl static (`mode=static`) or debug (`DEBUG=yes`) then the
180 library name will vary and separate builds may be necessary for separate
181 configurations of your project within the same platform. This is discussed in
182 the next section.
183
184## Building your own application with a static libcurl
185
186 When building an application that uses the static libcurl library on Windows,
187 you must define `CURL_STATICLIB`. Otherwise the linker will look for dynamic
188 import symbols.
189
190 The static library name has an `_a` suffix in the basename and the debug
191 library name has a `_debug` suffix in the basename. For example,
192 `libcurl_a_debug.lib` is a static debug build of libcurl.
193
194 You may need a separate build of libcurl for each VC configuration combination
195 (for example: Debug|Win32, Debug|x64, Release|Win32, Release|x64).
196
197 You must specify any additional dependencies needed by your build of static
198 libcurl (for example:
199 `advapi32.lib;crypt32.lib;normaliz.lib;ws2_32.lib;wldap32.lib`).
200
201## Legacy Windows and SSL
202
203 When you build curl using the build files in this directory the default SSL
204 backend will be Schannel (Windows SSPI), the native SSL library that comes
205 with the Windows OS. Schannel in Windows 8 and earlier is not able to connect
206 to servers that no longer support the legacy handshakes and algorithms used by
207 those versions. If you will be using curl in one of those earlier versions of
208 Windows you should choose another SSL backend like OpenSSL.
209
