winbuild: Add a Visual Studio example to the README

- Add an example that explains in detail how the user can add libcurl to
  their Visual Studio project.

Ref: https://github.com/curl/curl/issues/8591

Closes https://github.com/curl/curl/pull/8592

diff --git a/winbuild/README.md b/winbuild/README.md
index 831a62be3c1f8fcddf27034aed9f3196976b01be..4c33d4ff6f755469c893eefde29b7c112f1b13c8 100644 (file)
--- a/winbuild/README.md
+++ b/winbuild/README.md
@@ -118,12 +118,70 @@ where `<options>` is one or many of:
  differently, you must destroy the build directory containing the\r
  configuration so that nmake can build it from scratch.\r
 \r
+ This option is not recommended unless you have enough development experience\r
+ to know how to match the runtime library for linking (that is, the CRT).\r
+ If RTLIBCFG=static then release builds use /MT and debug builds use /MTd.\r
+\r
+## Building your own application with libcurl (Visual Studio example)\r
+\r
+ When you build curl and libcurl, nmake will show the relative path where the\r
+ output directory is. The output directory is named from the options nmake used\r
+ when building. You may also see temp directories of the same name but with\r
+ suffixes -obj-curl and -obj-lib.\r
+\r
+ For example let's say you've built curl.exe and libcurl.dll from the Visual\r
+ Studio 2010 x64 Win64 Command Prompt:\r
+\r
+ nmake /f Makefile.vc mode=dll VC=10\r
+\r
+ The output directory will have a name similar to\r
+ ..\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel.\r
+\r
+ The output directory contains subdirectories bin, lib and include. Those are\r
+ the directories to set in your Visual Studio project. You can either copy the\r
+ output directory to your project or leave it in place. Following the example,\r
+ let's assume you leave it in place and your curl top source directory is\r
+ C:\curl-7.82.0. You would set these options for configurations using the x64\r
+ platform:\r
+\r
+~~~\r
+ - Configuration Properties > Debugging > Environment\r
+    PATH=C:\curl-7.82.0\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel\bin;%PATH%\r
+\r
+ - C/C++ > General > Additional Include Directories\r
+    C:\curl-7.82.0\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel\include;\r
+\r
+ - Linker > General > Additional Library Directories\r
+    C:\curl-7.82.0\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel\lib;\r
+\r
+ - Linker > Input > Additional Dependencies\r
+    libcurl.lib;\r
+~~~\r
+\r
+ For configurations using the x86 platform (aka Win32 platform) you would\r
+ need to make a separate x86 build of libcurl.\r
+\r
+ If you build libcurl static (mode=static) or debug (DEBUG=yes) then the\r
+ library name will vary and separate builds may be necessary for separate\r
+ configurations of your project within the same platform. This is discussed\r
+ in the next section.\r
+\r
 ## Building your own application with a static libcurl\r
 \r
  When building an application that uses the static libcurl library on Windows,\r
  you must define CURL_STATICLIB. Otherwise the linker will look for dynamic\r
  import symbols.\r
 \r
+ The static library name has an '_a' suffix in the basename and the debug\r
+ library name has a '_debug' suffix in the basename. For example,\r
+ libcurl_a_debug.lib is a static debug build of libcurl.\r
+\r
+ You may need a separate build of libcurl for each VC configuration combination\r
+ (eg: Debug|Win32, Debug|x64, Release|Win32, Release|x64).\r
+\r
+ You must specify any additional dependencies needed by your build of static\r
+ libcurl (eg: advapi32.lib;crypt32.lib;normaliz.lib;ws2_32.lib;wldap32.lib).\r
+\r
 ## Legacy Windows and SSL\r
 \r
  When you build curl using the build files in this directory the default SSL\r