winbuild: convert the instruction text to README.md

Closes #5861

winbuild/README.md

@@ -0,0 +1,127 @@
+# Building curl with Visual C++
+
+ This document describes how to compile, build and install curl and libcurl
+ from sources using the Visual C++ build tool. To build with VC++, you will of
+ course have to first install VC++. The minimum required version of VC is 6
+ (part of Visual Studio 6). However using a more recent version is strongly
+ recommended.
+
+ VC++ is also part of the Windows Platform SDK. You do not have to install the
+ full Visual Studio or Visual C++ if all you want is to build curl.
+
+ The latest Platform SDK can be downloaded freely from [Windows SDK and
+ emulator
+ archive](https://developer.microsoft.com/en-us/windows/downloads/sdk-archive)
+
+## Prerequisites
+
+ If you wish to support zlib, openssl, c-ares, ssh2, you will have to download
+ them separately and copy them to the deps directory as shown below:
+
+    somedirectory\
+     |_curl-src
+     | |_winbuild
+     |
+     |_deps
+       |_ lib
+       |_ include
+       |_ bin
+
+ It is also possible to create the deps directory in some other random places
+ and tell the Makefile its location using the WITH_DEVEL option.
+
+## Building straight from git
+
+ When you check out code git and build it, as opposed from a released source
+ code archive, you need to first run the `buildconf.bat` batch file (present
+ in the source code root directory) to set things up.
+
+## Open a command prompt
+
+Open a Visual Studio Command prompt:
+
+ Using the **'Developer Command Prompt for VS [version]'** menu entry: where
+ [version} is the Visual Studio version. The developer prompt at default uses
+ the x86 mode. It is required to call `Vcvarsall.bat` to setup the prompt for
+ the machine type you want. This type of command prompt may not exist in all
+ Visual Studio versions.
+
+ See also: [Developer Command Prompt for Visual
+ Studio](https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs)
+ and [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)
+
+ Using the **'VS [version] [platform] [type] Command Prompt'** menu entry:
+ where [version] is the Visual Studio version, [platform] is e.g. x64 and
+ [type] Native of Cross platform build.  This type of command prompt may not
+ exist in all Visual Studio versions.
+
+ See also: [Set the Path and Environment Variables for Command-Line Builds](https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx)
+
+## Build in the console
+
+ Once you are in the console, go to the winbuild directory in the Curl
+ sources:
+
+    cd curl-src\winbuild
+
+ Then you can call `nmake /f Makefile.vc` with the desired options (see
+ below). The builds will be in the top src directory, `builds\` directory, in
+ a directory named using the options given to the nmake call.
+
+    nmake /f Makefile.vc mode=<static or dll> <options>
+
+where <options> is one or many of:
+
+ - `VC=<6,7,8,9,10,11,12,14,15>` - VC version
+ - `WITH_DEVEL=<path>`           - Paths for the development files (SSL, zlib, etc.)
+                                   Defaults to sibbling directory deps: ../deps
+                                   Libraries can be fetched at https://windows.php.net/downloads/php-sdk/deps/
+                                   Uncompress them into the deps folder.
+ - `WITH_SSL=<dll/static>`       - Enable OpenSSL support, DLL or static
+ - `WITH_NGHTTP2=<dll/static>`   - Enable HTTP/2 support, DLL or static
+ - `WITH_MBEDTLS=<dll/static>`   - Enable mbedTLS support, DLL or static
+ - `WITH_CARES=<dll/static>`     - Enable c-ares support, DLL or static
+ - `WITH_ZLIB=<dll/static>`      - Enable zlib support, DLL or static
+ - `WITH_SSH2=<dll/static>`      - Enable libSSH2 support, DLL or static
+ - `WITH_PREFIX=<dir>`           - Where to install the build
+ - `ENABLE_SSPI=<yes/no>`        - Enable SSPI support, defaults to yes
+ - `ENABLE_IPV6=<yes/no>`        - Enable IPv6, defaults to yes
+ - `ENABLE_IDN=<yes or no>`      - Enable use of Windows IDN APIs, defaults to yes
+                                   Requires Windows Vista or later
+ - `ENABLE_SCHANNEL=<yes/no>`    - Enable native Windows SSL support, defaults to yes
+ - `GEN_PDB=<yes/no>`            - Generate Program Database (debug symbols for release build)
+ - `DEBUG=<yes/no>`              - Debug builds
+ - `MACHINE=<x86/x64>`           - Target architecture (default is x86)
+ - `CARES_PATH=<path>`           - Custom path for c-ares
+ - `MBEDTLS_PATH=<path>`         - Custom path for mbedTLS
+ - `NGHTTP2_PATH=<path>`         - Custom path for nghttp2
+ - `SSH2_PATH=<path>`            - Custom path for libSSH2
+ - `SSL_PATH=<path>`             - Custom path for OpenSSL
+ - `ZLIB_PATH=<path>`            - Custom path for zlib
+
+## Static linking of Microsoft's C RunTime (CRT):
+
+ If you are using mode=static nmake will create and link to the static build
+ of libcurl but *not* the static CRT. If you must you can force nmake to link
+ in the static CRT by passing RTLIBCFG=static. Typically you shouldn't use
+ that option, and nmake will default to the DLL CRT. RTLIBCFG is rarely used
+ and therefore rarely tested. When passing RTLIBCFG for a configuration that
+ was already built but not with that option, or if the option was specified
+ differently, you must destroy the build directory containing the
+ configuration so that nmake can build it from scratch.
+
+## Building your own application with a static libcurl
+
+ When building an application that uses the static libcurl library on Windows,
+ you must define CURL_STATICLIB. Otherwise the linker will look for dynamic
+ import symbols.
+
+## Legacy Windows and SSL
+
+ When you build curl using the build files in this directory the default SSL
+ backend will be Schannel (Windows SSPI), the native SSL library that comes
+ with the Windows OS. Schannel in Windows <= XP is not able to connect to
+ servers that no longer support the legacy handshakes and algorithms used by
+ those versions. If you will be using curl in one of those earlier versions of
+ Windows you should choose another SSL backend like OpenSSL.