Skip to content

Commit

Permalink
Update Windows build instructions
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@greghudson
greghudson committed May 13, 2018
1 parent ebaa598 commit ba250f7
Showing 1 changed file with 98 additions and 67 deletions.
165 changes: 98 additions & 67 deletions src/windows/README
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
-----------------------
Expand Down

0 comments on commit ba250f7

Please sign in to comment.