Windows: Build instructions

windows/README

@@ -0,0 +1,136 @@
+Building Heimdal for Windows
+===================
+
+1. Introduction
+---------------
+
+Heimdal can be built and run on Windows XP or later.  Older OSs may
+work, but have not been tested.
+
+2. Prerequisites
+----------------
+
+* __Microsoft Visual C++ Compiler__: Heimdal has been tested with
+  Microsoft Visual C/C++ compiler version 15.x.  This corresponds to
+  Microsoft Visual Studio version 2008.  The compiler and tools that
+  are included with Microsoft Windows SDK versions 6.1 and later can
+  also be used for building Heimdal.  If you have a recent Windows
+  SDK, then you already have a compatible compiler.
+
+* __Microsoft Windows SDK__: Heimdal has been tested with Microsoft
+  Windows SDK version 6.1 and 7.0.
+
+* __Microsoft HTML Help Compiler__: Needed for building documentation.
+
+* __Perl__: A recent version of Perl.  Tested with ActiveState
+  ActivePerl.
+
+* __Python__: Tested with Python 2.5 and 2.6.
+
+* __WiX__: The Windows [Installer XML toolkit (WiX)][1] Version 3.x is
+  used to build the installers.
+
+* __Cygwin__: The Heimdal build system requires a number of additional
+  tools: `awk`, `yacc`, `lex`, `cmp`, `sed`, `makeinfo`, `sh`
+  (Required for running tests).  These can be found in the Cygwin
+  distribution.  MinGW or GnuWin32 may also be used instead of Cygwin.
+  However, a recent build of `makeinfo` is required for building the
+  documentation.
+
+* __Certificate for code-signing__: The Heimdal build produces a
+  number of Assemblies that should be signed if they are to be
+  installed via Windows Installer.  In addition, all executable
+  binaries produced by the build including installers can be signed
+  and timestamped if a code-signing certificate is available.
+
+[1]: http://wix.sourceforge.net/
+
+3. Setting up the build environment
+-----------------------------------
+
+* Start with a Windows SDK or Visual Studio build environment.  The
+  target platform, OS and build type (debug / release) is determined
+  by the build environment.
+
+  E.g.: If you are using the Windows SDK, you can use the `SetEnv.Cmd`
+  script to set up a build environment targetting 64-bit Windows XP or
+  later with:
+
+      SetEnv.Cmd /xp /x64 /Debug
+
+  The build will produce debug binaries.
+
+* Add any directories to `PATH` as necessary so that tools required by
+  the build can be found.  The build scripts will check for build
+  tools at the start of the build and will indicate which ones are
+  missing.  In general, adding Perl, Python, WiX, HTML Help Compiler and
+  Cygwin binary directories to the path should be sufficient.
+
+* Set up environment variables for code signing.  This can be done in
+  one of two ways.  By specifying options for `signtool` or by
+  specifying the code-signing command directly.  To use `signtool`,
+  define `SIGNTOOL_C` and optionally, `SIGNTOOL_O` and `SIGNTOOL_T`.
+
+  - `SIGNTOOL_C`: Certificate selection and private key selection
+    options for `signtool`.
+
+    E.g.:
+        set SIGNTOOL_C=/f c:\mycerts\codesign.pfx
+
+  - `SIGNTOOL_O`: Signing parameter options for `signtool`. Optional.
+
+    E.g.:
+        set SIGNTOOL_O=/du http://example.com/myheimdal
+
+  - `SIGNTOOL_T`: Timestamp options for `signtool`.  If not specified,
+    defaults to `/t http://timestamp.verisign.com/scripts/timstamp.dll`.
+
+  - `CODESIGN`: Code signer command.  This environment variable, if
+    defined, overrides the `SIGNTOOL_*` variables.  It should be
+    defined to be a command that takes one parameter: the binary to be
+    signed.
+
+    E.g.:
+        set CODESIGN=c:\scripts\mycodesigner.cmd
+
+* Define the code sign public key token.  This is contained in the
+  environment variable `CODESIGN_PKT` and is needed to build the
+  Heimdal assemblies.  If you are not using a code-sign certificate,
+  set this to `0000000000000000`.
+
+  You can use the `pktextract` tool to determine the public key token
+  corresponding to your code signing certificate as follows (assuming
+  your code signing certificate is in `c:\mycerts\codesign.cer`:
+
+      pktextract c:\mycerts\codesign.cer
+
+  The above command will output the certificate name, key size and the
+  public key token.  Set the `CODESIGN_PKT` variable to the
+  `publicKeyToken` value (excluding quotes).
+
+  E.g.:
+      set CODESIGN_PKT=abcdef0123456789
+
+4. Running the build
+--------------------
+
+Change the current directory to the root of the Heimdal source tree
+and run:
+
+    nmake /f NTMakefile
+
+This should build the binaries, assemblies and the installers.
+
+The build can also be invoked from any subdirectory that contains an
+`NTMakefile` using the same command.  Keep in mind that there are
+inter-dependencies between directories and therefore it is recommended
+that a full build be invoked from the root of the source tree.
+
+Tests can be invoked as:
+
+    nmake /f NTMakefile test
+
+The build tree can be cleaned with:
+
+    nmake /f NTMakefile clean
+