Update Windows build instructions

Modify windows/README for Visual Studio 2017, which has separate
32-bit and 64-bit command prompts (and which seems to omit uicc from
the 64-bit path).  Mention the need for MFC if building leash, and
describe how to build without leash.

ticket: 8662

1 files changed, 98 insertions, 67 deletions

diff --git a/src/windows/README b/src/windows/README
index 02f149c..c79a178 100644
--- a/src/windows/README
+++ b/src/windows/README
@@ -6,61 +6,70 @@ The MIT Kerberos for Windows distribution contains additional components
 not present in the Unix krb5 distribution, most notably the
 MIT Kerberos Ticket Manager application.
 
-To build Kerberos 5 on Windows, you will need the Windows SDK (XP SP3
-or later), VisualStudio (2010 Professional SP1), a version of Perl, and some
-common Unix utilities such as sed/awk/cp/cat installed in the
-command-line path.  To build an MSI installer, you will additionally
-need the Windows Installer XML (WiX) toolkit, and to ensure that
-the HTML Help Compiler (hhc.exe) and the WiX tools are in your command-line
-path.  WiX version 3.5 is verified to work with this codebase; WiX 3.7
-and newer are incompatible with this codebase.  Visual Studio 2012 and
-the Windows SDK 8 introduce some changes which alter the Kerberos build
-procedure slightly (noted where appropriate).
-
-The Unix utilities can be obtained via the Utilities and SDK for UNIX-based
-Aplications, which may be enabled as a Windows feature and then the
-components installed.  Note that the Windows nmake will not find the
-SUA awk utility in the path unless it is named awk.exe; the permissions
-on the utility may need correcting if awk.exe is created as a copy of
-the original awk.
-
-There is a version of perl available through the SUA, but it is not
-sufficient to build krb5.  An external perl such as Strawberry Perl
-or ActiveState Perl is necessary.
+To build Kerberos 5 on Windows, you will need the following:
+
+* A version of Visual Studio which includes the Microsoft Foundation
+  Classes libraries.  These instructions will work for Visual Studio
+  2017 Community or Professional, both of which include the MFC
+  libraries if the "Visual C++ MFC" checkbox is selected after
+  enabling the "Desktop development with C++" workload.  If you do not
+  plan to build the graphical ticket manager application, the MFC
+  libraries are not required.
+
+* A version of Perl.
+
+* Some common Unix utilities such as sed/awk/cp/cat installed in the
+  command-line path.
+
+* To build an MSI installer, the Windows Installer XML (WiX) toolkit,
+  and to ensure that the HTML Help Compiler (hhc.exe) and the WiX
+  tools are in your command-line path.  WiX version 3.11.1 is verified
+  to work with this codebase.
+
+A simple way to get the necessary Unix utilities is to install Git
+BASH from https://gitforwindows.org and configure it to add the Unix
+utilities to the command-line path.  In some versions of Windows (not
+the most current versions), the Unix utilities can alternatively be
+obtained via the Utilities and SDK for UNIX-based Aplications, which
+may be enabled as a Windows feature and then the components installed.
+Note that the Windows nmake will not find the SUA awk utility in the
+path unless it is named awk.exe; the permissions on the utility may
+need correcting if awk.exe is created as a copy of the original awk.
+
+Git BASH contains a version of Perl, which will work to build krb5 if
+the newlines in the source tree are not translated to native newlines.
+Strawberry Perl will work regardless of whether newlines are
+translated.  If both Git BASH and Strawberry Perl are installed, you
+may need to adjust the command line path to ensure that the preferred
+Perl appears first.
 
 The krb5 source tree may be obtained either directly on the Windows
-machine with a native git client cloning the krb5 public mirror
-at https://github.com/krb5/krb5.git or on a separate (Unix) machine
-and copied over, such as from a VM host onto a Windows VM.
-The kerbsrc.zip method is no longer supported.
-
-After the Windows SDK is installed, you should be able to invoke an
-SDK command prompt via the start menu (All Programs -> Microsoft
-Windows SDK vX.Y -> Windows SDK X.Y Command Prompt).  Within this
-window, you can change the build target using the setenv command; run
-"setenv /?" or see the Windows SDK documentation for details.  At the
-current time, Kerberos 5 can only be built for the x64 target if the
-host platform is also 64-bit, because it compiles and runs programs
-during the build.  The Windows SDK version 8 does not provide an SDK
-command prompt; the "Developer Command Prompt for VS2012" or "Visual Studio
-Command Prompt" must be used instead.  Accordingly, there is no setenv script
-to configure the build environment for different target architectures; the
-"vcvarsall.bat" script provided by Visual Studio serves this function.
+machine with a native git client cloning the krb5 public mirror at
+https://github.com/krb5/krb5.git or on a separate (Unix) machine and
+copied over, such as from a VM host onto a Windows VM.  If you are
+checking out the sources with git and are using the Git BASH Perl,
+make sure to set git's core.autocrlf variable to "input" or "false" to
+avoid translating newlines.
+
+After Visual Studio is installed, you should be able to invoke 32-bit
+and 64-bit command prompts via the start menu (Visual Studio 2017 ->
+x86 Native Tools Command Prompt and x64 Native Tools Command Prompt).
+At the current time, Kerberos 5 can only be built for the x64 target
+if the host platform is also 64-bit, because it compiles and runs
+programs during the build.
 
 IMPORTANT NOTE: By default, the sources are built with debug
 information and linked against the debug version of the Microsoft C
 Runtime library, which is not found on most Windows systems unless
-they have development tools, and requires a separate license to distribute.
-To build a release version, you need to define NODEBUG either in the
-environment or the nmake command-line and use setenv to enter a release
-build environment with "setenv /release" (when using Windows SDK versions
-lower than 8).  Debug information in the compiled binaries and libraries
-may be retained by defining DEBUG_SYMBOL in the environment or on the nmake
-command line.
+they have development tools, and requires a separate license to
+distribute.  To build a release version, you need to define NODEBUG
+either in the environment or the nmake command-line.  Debug
+information in the compiled binaries and libraries may be retained by
+defining DEBUG_SYMBOL in the environment or on the nmake command line.
 
 
-Building the code and installer
-------------------------
+Building the code and installer:
+-------------------------------
 
 First, make sure you have sed, (g)awk, cat, and cp.
 You must also define KRB_INSTALL_DIR either in the environment or
@@ -70,29 +79,51 @@ near your build tree.  The directory must exist before nmake install
 is run.  The 64-bit installer provides 32-bit libraries, so a 32-bit build
 and install must be performed before the 64-bit build.
 
- 1) set CPU=i386                        # Get 32-bit target in environment
- 2) set KRB_INSTALL_DIR=\path\to\dir    # Where bin/include/lib lives
- 3) setenv /x86 [/release]              # Tell nmake to target 32-bit
-    (with Visual Studio 2012, use "vcvarsall.bat x86")
- 4) cd xxx/src                          # Go to where the source lives
- 5) nmake -f Makefile.in prep-windows   # Create Makefile for Windows
- 6) nmake [NODEBUG=1]                   # Build the sources
- 7) nmake install [NODEBUG=1]           # Copy headers, libs, executables
- 8) cd windows\installer\wix            # Go to where the installer source is
- 9) nmake                               # Build the installer
-10) rename kfw.msi kfw32.msi            # Save the 32-bit installer
-11) set CPU=AMD64                       # Proceed to the 64-bit build
-12) setenv /x64 [/release]              # Must set both CPU and nmake env
-    ("vcvarsall.bat amd64" for Visual Studio 2012)
-13) cd ..\..\..                         # Back to the sources
-14) nmake clean                         # Clean up the 32-bit objects
-15) nmake [NODEBUG=1]                   # Build the sources for 64-bit
-16) nmake install [NODEBUG=1]           # Copy 64-bit lib/executables
-17) cd windows\installer\wix            # Back to the installer source
+To skip building the graphical ticket manager, run "set NO_LEASH=1"
+before building, and do not build the installers.
+
+In a 32-bit command shell:
+
+ 1) set KRB_INSTALL_DIR=\path\to\dir    # Where bin/include/lib lives
+ 2) cd xxx\src                          # Go to where source lives
+ 3) nmake -f Makefile.in prep-windows   # Create Makefile for Windows
+ 4) nmake [NODEBUG=1]                   # Build the sources
+ 5) nmake install [NODEBUG=1]           # Copy headers, libs, executables
+ 6) cd windows\installer\wix            # Go to where the installer source is
+ 7) set CPU=i386                        # Specify 32-bit target
+ 8) nmake [NODEBUG=1]                   # Build the installer
+ 9) rename kfw.msi kfw32.msi            # Save the 32-bit installer
+
+In a 64-bit command shell:
+
+10) set PATH=%PATH%;"%WindowsSdkVerBinPath%"\x86  # To get uicc.exe
+11) set KRB_INSTALL_DIR=\path\to\dir    # Where bin/include/lib lives
+12) cd xxx\src                          # Go to where source lives
+13) nmake clean                         # Clean up the 32-bit objects
+14) nmake [NODEBUG=1]                   # Build the sources for 64-bit
+15) nmake install [NODEBUG=1]           # Copy 64-bit lib/executables
+16) cd windows\installer\wix            # Back to the installer source
+17) set CPU=AMD64                       # Specify 64-bit target
 18) nmake clean                         # Remove 32-bit leavings
-19) nmake                               # Build the 64-bit installer
+19) nmake [NODEBUG=1]                   # Build the 64-bit installer
 20) rename kfw.msi kfw64.msi            # And name it usefully
 
+Step 10 may be skipped if uicc is already in your command-line path
+(try running "uicc" to see if you get a usage message or a not-found
+error), or if you are not building the graphical ticket manager.
+
+Visual Studio 2012 provides only a single command prompt.  Within this
+prompt, use "vcvarsall.bat x86" and "vcvarsall.bat amd64" to switch to
+32-bit and 64-bit mode.
+
+With Visual Studio 2010, it is necessary to separately install the
+Windows SDK version 7.1 and use the Microsoft Windows SDK -> Windows
+SDK X.Y Command Prompt menu item.  Within this command prompt, run
+"setenv /x86" and "setenv /x64" to switch to 32-bit and 64-bit mode.
+Also include the "/release" option if building with NODEBUG.  If you
+are building with NO_LEASH=1, Visual Studio 2010 itself is not
+necessary; Windows SDK version 7.1 alone is sufficient.
+
 
 Running Kerberos 5 Apps:
 -----------------------