winbuild: convert the instruction text to README.md

Closes #5861

2 files changed, 127 insertions, 130 deletions

diff --git a/winbuild/BUILD.WINDOWS.txt b/winbuild/BUILD.WINDOWS.txt
deleted file mode 100644
index 5b63bdcd7..000000000
--- a/winbuild/BUILD.WINDOWS.txt
+++ /dev/null
@@ -1,130 +0,0 @@
-Building with Visual C++, prerequisites

-=======================================

-

-   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:

-

-    https://developer.microsoft.com/en-us/windows/downloads/sdk-archive

-

-   If you are building with VC6 then you will also need the February 2003

-   Edition of the Platform SDK which can be downloaded from:

-

-    https://www.microsoft.com/en-us/download/details.aspx?id=12261

-

-   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.

-

-Building with Visual C++

-========================

-

-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, using Vcvarsall.bat.

-       This type of command prompt may not exist in all Visual Studio versions.

-

-       For more information, check:

-         https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs

-         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:

-         https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx

-

-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 versions

-  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 or static>       - Enable OpenSSL support, DLL or static

-  WITH_NGHTTP2=<dll or static>   - Enable HTTP/2 support, DLL or static

-  WITH_MBEDTLS=<dll or static>   - Enable mbedTLS support, DLL or static

-  WITH_CARES=<dll or static>     - Enable c-ares support, DLL or static

-  WITH_ZLIB=<dll or static>      - Enable zlib support, DLL or static

-  WITH_SSH2=<dll or static>      - Enable libSSH2 support, DLL or static

-  WITH_PREFIX=<dir>              - Where to install the build

-  ENABLE_SSPI=<yes or no>        - Enable SSPI support, defaults to yes

-  ENABLE_IPV6=<yes or 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 or no>      - Enable native Windows SSL support, defaults to yes

-  GEN_PDB=<yes or no>            - Generate Program Database (debug symbols for release build)

-  DEBUG=<yes or no>              - Debug builds

-  MACHINE=<x86 or x64>           - Target architecture (default is x86)

-  CARES_PATH=<path to cares>     - Custom path for c-ares

-  MBEDTLS_PATH=<path to mbedTLS> - Custom path for mbedTLS

-  NGHTTP2_PATH=<path to HTTP/2>  - Custom path for nghttp2

-  SSH2_PATH=<path to libSSH2>    - Custom path for libSSH2

-  SSL_PATH=<path to OpenSSL>     - Custom path for OpenSSL

-  ZLIB_PATH=<path to zlib>       - 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.

diff --git a/winbuild/README.md b/winbuild/README.md
new file mode 100644
index 000000000..a57303832
--- /dev/null
+++ b/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.