README.md
1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3
4SPDX-License-Identifier: curl
5-->
6
7Building via IDE Project Files
8==============================
9
10This document describes how to compile, build and install curl and libcurl
11from sources using legacy versions of Visual Studio 2010 - 2013.
12
13You will need to generate the project files before using them. Please run
14"generate -help" for usage details.
15
16To generate project files for recent versions of Visual Studio instead, use
17cmake. Refer to INSTALL-CMAKE in the docs directory.
18
19## Directory Structure
20
21The following directory structure is used for the legacy project files:
22
23 somedirectory\
24 |_curl
25 |_projects
26 |_<platform>
27 |_<ide>
28 |_lib
29 |_src
30
31This structure allows for side-by-side compilation of curl on the same machine
32using different versions of a given compiler (for example VC10 and VC12) and
33allows for your own application or product to be compiled against those
34variants of libcurl for example.
35
36Note: Typically this side-by-side compilation is generally only required when
37a library is being compiled against dynamic runtime libraries.
38
39## Dependencies
40
41The projects files also support build configurations that require third party
42dependencies such as OpenSSL, wolfSSL and libssh2. If you wish to support
43these, you will also need to download and compile those libraries as well.
44
45To support compilation of these libraries using different versions of
46compilers, the following directory structure has been used for both the output
47of curl and libcurl as well as these dependencies.
48
49 somedirectory\
50 |_curl
51 | |_ build
52 | |_<architecture>
53 | |_<ide>
54 | |_<configuration>
55 | |_lib
56 | |_src
57 |
58 |_openssl
59 | |_ build
60 | |_<architecture>
61 | |_VC <version>
62 | |_<configuration>
63 |
64 |_libssh2
65 |_ build
66 |_<architecture>
67 |_VC <version>
68 |_<configuration>
69
70As OpenSSL and wolfSSL don't support side-by-side compilation when using
71different versions of Visual Studio, build helper batch files have been
72provided to assist with this. Please run `build-openssl -help` and/or
73`build-wolfssl -help` for usage details.
74
75## Building with Visual C++
76
77To build with VC++, you will of course have to first install VC++ which is
78part of Visual Studio.
79
80Once you have VC++ installed you should launch the application and open one of
81the solution or workspace files. The VC directory names are based on the
82version of Visual C++ that you will be using. Each version of Visual Studio
83has a default version of Visual C++. We offer these versions:
84
85 - VC10 (Visual Studio 2010 Version 10.0)
86 - VC11 (Visual Studio 2012 Version 11.0)
87 - VC12 (Visual Studio 2013 Version 12.0)
88
89Separate solutions are provided for both libcurl and the curl command line
90tool as well as a solution that includes both projects. libcurl.sln, curl.sln
91and curl-all.sln, respectively. We recommend using curl-all.sln to build both
92projects.
93
94For example, if you are using Visual Studio 2010 then you should be able to
95use `VC10\curl-all.sln` to build curl and libcurl.
96
97## Running DLL based configurations
98
99If you are a developer and plan to run the curl tool from Visual Studio with
100any third-party libraries (such as OpenSSL, wolfSSL or libssh2) then you will
101need to add the search path of these DLLs to the configuration's PATH
102environment. To do that:
103
104 1. Open the 'curl-all.sln' or 'curl.sln' solutions
105 2. Right-click on the 'curl' project and select Properties
106 3. Navigate to 'Configuration Properties > Debugging > Environment'
107 4. Add `PATH='Path to DLL';C:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem`
108
109... where 'Path to DLL` is the configuration specific path. For example the
110following configurations in Visual Studio 2010 might be:
111
112DLL Debug - DLL OpenSSL (Win32):
113
114 PATH=..\..\..\..\..\openssl\build\Win32\VC10\DLL Debug;C:\Windows\System32;
115 C:\Windows;C:\Windows\System32\Wbem
116
117DLL Debug - DLL OpenSSL (x64):
118
119 PATH=..\..\..\..\..\openssl\build\Win64\VC10\DLL Debug;C:\Windows\System32;
120 C:\Windows;C:\Windows\System32\Wbem
121
122DLL Debug - DLL wolfSSL (Win32):
123
124 PATH=..\..\..\..\..\wolfssl\build\Win32\VC10\DLL Debug;C:\Windows\System32;
125 C:\Windows;C:\Windows\System32\Wbem
126
127DLL Debug - DLL wolfSSL (x64):
128
129 PATH=..\..\..\..\..\wolfssl\build\Win64\VC10\DLL Debug;C:\Windows\System32;
130 C:\Windows;C:\Windows\System32\Wbem
131
132If you are using a configuration that uses multiple third-party library DLLs
133(such as DLL Debug - DLL OpenSSL - DLL libssh2) then 'Path to DLL' will need
134to contain the path to both of these.
135
136## Notes
137
138The following keywords have been used in the directory hierarchy:
139
140 - `<platform>` - The platform (For example: Windows)
141 - `<ide>` - The IDE (For example: VC10)
142 - `<architecture>` - The platform architecture (For example: Win32, Win64)
143 - `<configuration>` - The target configuration (For example: DLL Debug, LIB
144 Release - LIB OpenSSL)
145
146Should you wish to help out with some of the items on the TODO list, or find
147bugs in the project files that need correcting, and would like to submit
148updated files back then please note that, whilst the solution files can be
149edited directly, the templates for the project files (which are stored in the
150git repository) will need to be modified rather than the generated project
151files that Visual Studio uses.
152
153## Legacy Windows and SSL
154
155Some of the project configurations allow the use of Schannel, the native SSL
156library in Windows which forms part of Windows SSPI. However, Schannel in
157Windows <= XP is unable to connect to servers that no longer support the
158legacy handshakes and algorithms used by those versions. If you will be using
159curl in one of those earlier versions of Windows you should choose another SSL
160backend such as OpenSSL.
161
