From: Jay Satiro <raysatiro@yahoo.com>
Date: Sun, 13 Mar 2022 22:45:39 +0000 (-0400)
Subject: winbuild: Add a Visual Studio example to the README
X-Git-Tag: curl-7_83_0~113
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ccea32984892aeb5b2a153581be0615e8efea44b;p=thirdparty%2Fcurl.git

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