README
1Building via IDE Project Files
2==============================
3
4 This document describes how to compile, build and install curl and libcurl
5 from sources using an IDE based development tool such as Visual Studio.
6
7 Project files are currently available for Visual C++ v6.0 to v14.0. The
8 following directory structure has been used to cater for this:
9
10 somedirectory\
11 |_curl
12 |_projects
13 |_<platform>
14 |_<ide>
15 |_lib
16 |_src
17
18 This structure allows for side-by-side compilation of curl on the same
19 machine using different versions of a given compiler (for example VC8, VC9
20 and VC10) and allows for your own application or product to be compiled
21 against those variants of libcurl for example.
22
23 Note: Typically this side-by-side compilation is generally only required
24 when a library is being compiled against dynamic runtime libraries.
25
26Dependencies
27============
28
29 The projects files also support build configurations that require third
30 party dependencies such as OpenSSL, wolfSSL and SSH2. If you wish to support
31 these, you will also need to download and compile those libraries as well.
32
33 To support compilation of these libraries using different versions of
34 compilers, the following directory structure has been used for both the
35 output of curl and libcurl as well as these dependencies.
36
37 somedirectory\
38 |_curl
39 | |_ build
40 | |_<architecture>
41 | |_<ide>
42 | |_<configuration>
43 | |_lib
44 | |_src
45 |
46 |_openssl
47 | |_ build
48 | |_<architecture>
49 | |_VC <version>
50 | |_<configuration>
51 |
52 |_libssh2
53 |_ build
54 |_<architecture>
55 |_VC <version>
56 |_<configuration>
57
58 As OpenSSL and wolfSSL don't support side-by-side compilation when using
59 different versions of Visual Studio, build helper batch files have been
60 provided to assist with this. Please run "build-openssl -help" and/or
61 "build-wolfssl -help" for usage details.
62
63Building with Visual C++
64========================
65
66 To build with VC++, you will of course have to first install VC++ which is
67 part of Visual Studio.
68
69 If you are building with VC6 then you will also need the February 2003
70 Edition of the Windows Platform SDK which can be downloaded from:
71
72 https://www.microsoft.com/en-us/download/details.aspx?id=12261
73
74 If you require support for Internationalized Domain Names via Windows IDN
75 then you will need either:
76
77 * Microsoft Internationalized Domain Name (IDN) Mitigation APIs:
78 https://www.microsoft.com/en-us/download/details.aspx?id=734
79
80 * Microsoft Windows SDK Update for Windows Vista:
81 https://www.microsoft.com/en-us/download/details.aspx?id=23719
82
83 * Microsoft Visual Studio 2010 or above
84
85 Once you have VC++ installed you should launch the application and open one
86 of the solution or workspace files.
87
88 Whilst files are provided for both libcurl and the curl command line tool as
89 well as a configuration that includes both, it is recommend that you use the
90 all-in-one configuration.
91
92Running DLL based configurations
93================================
94
95 If you are a developer and plan to run the curl tool from Visual Studio (eg
96 you are debugging) with any third-party libraries (such as OpenSSL, wolfSSL
97 or LibSSH2) then you will need to add the search path of these DLLs to the
98 configuration's PATH environment. To do that:
99
100 * Open the 'curl-all.sln' or 'curl.sln' solutions
101
102 * Right-click on the 'curl' project and select Properties
103
104 * Navigate to 'Configuration Properties > Debugging > Environment'
105
106 * Add PATH='Path to DLL';C:\Windows\system32;C:\Windows;
107 C:\Windows\System32\Wbem
108
109 ... where 'Path to DLL` is the configuration specific path. For example the
110 following configurations in Visual Studio 2010 might be:
111
112 DLL Debug - DLL OpenSSL (Win32):
113 PATH=..\..\..\..\..\openssl\build\Win32\VC10\DLL Debug;C:\Windows\system32;
114 C:\Windows;C:\Windows\System32\Wbem
115
116 DLL Debug - DLL OpenSSL (x64):
117 PATH=..\..\..\..\..\openssl\build\Win64\VC10\DLL Debug;C:\Windows\system32;
118 C:\Windows;C:\Windows\System32\Wbem
119
120 DLL Debug - DLL wolfSSL (Win32):
121 PATH=..\..\..\..\..\wolfssl\build\Win32\VC10\DLL Debug;C:\Windows\system32;
122 C:\Windows;C:\Windows\System32\Wbem
123
124 DLL Debug - DLL wolfSSL (x64):
125 PATH=..\..\..\..\..\wolfssl\build\Win64\VC10\DLL Debug;C:\Windows\system32;
126 C:\Windows;C:\Windows\System32\Wbem
127
128 If you are using a configuration that uses multiple third-party library DLLs
129 (such as DLL Debug - DLL OpenSSL - DLL LibSSH2) then 'Path to DLL' will need
130 to contain the path to both of these.
131
132Notes
133=====
134
135 The following keywords have been used in the directory hierarchy:
136
137 <platform> - The platform (For example: Windows)
138 <ide> - The IDE (For example: VC6, VC10, BCC5)
139 <architecture> - The platform architecture (For example: Win32, Win64)
140 <configuration> - The target configuration (For example: DLL Debug,
141 LIB Release - LIB OpenSSL)
142
143 If you are using the source code from the git repository, rather than a
144 release archive or nightly build, you will need to generate the project
145 files. Please run "generate -help" for usage details.
146
147 Should you wish to help out with some of the items on the TODO list, or
148 find bugs in the project files that need correcting, and would like to
149 submit updated files back then please note that, whilst the solution files
150 can be edited directly, the templates for the project files (which are
151 stored in the git repositoty) will need to be modified rather than the
152 generated project files that Visual Studio uses.
153
154Legacy Windows and SSL
155======================
156
157 Some of the project configurations allow the use of WinSSL (specifically
158 SChannel from Windows SSPI), the native SSL library in Windows. However,
159 WinSSL in Windows <= XP is unable to connect to servers that no longer
160 support the legacy handshakes and algorithms used by those versions. If
161 you will be using curl in one of those earlier versions of Windows you
162 should choose another SSL backend such as OpenSSL.
163