projects/README

   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.