lh | 9ed821d | 2023-04-07 01:36:19 -0700 | [diff] [blame] | 1 | Building 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 | |
| 26 | Dependencies |
| 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 | |
| 63 | Building 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 | |
| 92 | Running 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 | |
| 132 | Notes |
| 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 | |
| 154 | Legacy 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. |