windows/README.md

   1 Building Heimdal for Windows
   2 ===================
   3
   4 1. Introduction
   5 ---------------
   6
   7 Heimdal can be built and run on Windows XP or later.  Older OSs may
   8 work, but have not been tested.
   9
  10 2. Prerequisites
  11 ----------------
  12
  13 * __Microsoft Visual C++ Compiler__: Heimdal has been tested with
  14   Microsoft Visual C/C++ compiler version 15.x.  This corresponds to
  15   Microsoft Visual Studio version 2008.  The compiler and tools that
  16   are included with Microsoft Windows SDK versions 6.1 and later can
  17   also be used for building Heimdal.  If you have a recent Windows
  18   SDK, then you already have a compatible compiler.
  19
  20 * __Microsoft Windows SDK__: Heimdal has been tested with Microsoft
  21   Windows SDK version 6.1 and 7.0.
  22
  23 * __Microsoft HTML Help Compiler__: Needed for building documentation.
  24
  25 * __Perl__: A recent version of Perl.  Tested with ActiveState
  26   ActivePerl.
  27
  28 * __Python__: Tested with Python 2.5 and 2.6.
  29
  30 * __WiX__: The Windows [Installer XML toolkit (WiX)][1] Version 3.x is
  31   used to build the installers.
  32
  33 * __Cygwin__: The Heimdal build system requires a number of additional
  34   tools: `awk`, `yacc`, `lex`, `cmp`, `sed`, `makeinfo`, `sh`
  35   (Required for running tests).  These can be found in the Cygwin
  36   distribution.  MinGW or GnuWin32 may also be used instead of Cygwin.
  37   However, a recent build of `makeinfo` is required for building the
  38   documentation. Cygwin makeinfo 4.7 is known to work.
  39
  40 * __Certificate for code-signing__: The Heimdal build produces a
  41   number of Assemblies that should be signed if they are to be
  42   installed via Windows Installer.  In addition, all executable
  43   binaries produced by the build including installers can be signed
  44   and timestamped if a code-signing certificate is available.
  45   As of 1 January 2016 Windows 7 and above require the use of sha256
  46   signatures.  The signtool.exe provided with Windows SDK 8.1 or
  47   later must be used.
  48
  49 [1]: http://wix.sourceforge.net/
  50
  51 3. Setting up the build environment
  52 -----------------------------------
  53
  54 * Start with a Windows SDK or Visual Studio build environment.  The
  55   target platform, OS and build type (debug / release) is determined
  56   by the build environment.
  57
  58   E.g.: If you are using the Windows SDK, you can use the `SetEnv.Cmd`
  59   script to set up a build environment targetting 64-bit Windows XP or
  60   later with:
  61
  62       SetEnv.Cmd /xp /x64 /Debug
  63
  64   The build will produce debug binaries.  If you specify
  65
  66       SetEnv.Cmd /xp /x64 /Release
  67
  68   the build will produce release binaries.
  69
  70 * Add any directories to `PATH` as necessary for tools required by
  71   the build to be found.  The build scripts will check for build
  72   tools at the start of the build and will indicate which ones are
  73   missing.  In general, adding Perl, Python, WiX, HTML Help Compiler and
  74   Cygwin binary directories to the path should be sufficient.
  75
  76 * Set up environment variables for code signing.  This can be done in
  77   one of two ways.  By specifying options for `signtool` or by
  78   specifying the code-signing command directly.  To use `signtool`,
  79   define `SIGNTOOL_C` and optionally, `SIGNTOOL_O` and `SIGNTOOL_T`.
  80
  81   - `SIGNTOOL_C`: Certificate selection and private key selection
  82     options for `signtool`.
  83
  84     E.g.:
  85
  86         set SIGNTOOL_C=/f c:\mycerts\codesign.pfx
  87
  88         set SIGNTOOL_C=/n "Certificate Subject Name" /a
  89
  90   - `SIGNTOOL_O`: Signing parameter options for `signtool`. Optional.
  91
  92     E.g.:
  93
  94         set SIGNTOOL_O=/du http://example.com/myheimdal
  95
  96   - `SIGNTOOL_T`: SHA1 Timestamp URL for `signtool`.  If not specified,
  97     defaults to `http://timestamp.verisign.com/scripts/timstamp.dll`.
  98
  99   - `SIGNTOOL_T_SHA256`: SHA256 Timestamp URL for `signtool`.  If not
 100     specified, defaults to `http://timestamp.geotrust.com/tsa`.
 101
 102   - `CODESIGN`: SHA1 Code signer command.  This environment variable, if
 103     defined, overrides the `SIGNTOOL_*` variables.  It should be
 104     defined to be a command that takes one parameter: the binary to be
 105     signed.
 106
 107   - `CODESIGN_SHA256`: SHA256 Code signer command.  This environment variable, if
 108     defined, applies a second SHA256 signature to the parameter.  It should be
 109     defined to be a command that takes one parameter: the binary to be
 110     signed.
 111
 112     E.g.:
 113
 114         set CODESIGN=c:\scripts\mycodesigner.cmd
 115         set CODESIGN_SHA256=c:\scripts\mycodesigner256.cmd
 116
 117 * Define the code sign public key token.  This is contained in the
 118   environment variable `CODESIGN_PKT` and is needed to build the
 119   Heimdal assemblies.  If you are not using a code-sign certificate,
 120   set this to `0000000000000000`.
 121
 122   You can use the `pktextract` tool to determine the public key token
 123   corresponding to your code signing certificate as follows (assuming
 124   your code signing certificate is in `c:\mycerts\codesign.cer`:
 125
 126       pktextract c:\mycerts\codesign.cer
 127
 128   The above command will output the certificate name, key size and the
 129   public key token.  Set the `CODESIGN_PKT` variable to the
 130   `publicKeyToken` value (excluding quotes).
 131
 132   E.g.:
 133
 134       set CODESIGN_PKT=abcdef0123456789
 135
 136 4. Running the build
 137 --------------------
 138
 139 Change the current directory to the root of the Heimdal source tree
 140 and run:
 141
 142     nmake /f NTMakefile
 143
 144 This should build the binaries, assemblies and the installers.
 145
 146 The build can also be invoked from any subdirectory that contains an
 147 `NTMakefile` using the same command.  Keep in mind that there are
 148 inter-dependencies between directories and therefore it is recommended
 149 that a full build be invoked from the root of the source tree.
 150
 151 Tests can be invoked, after a full build, by executing:
 152
 153     nmake /f NTMakefile test
 154
 155 The build tree can be cleaned with:
 156
 157     nmake /f NTMakefile clean
 158
 159 It is recommended that both AMD64 and X86 builds take place on the
 160 same machine.  This permits a multi-platform installer package to
 161 be built.  First build for X86 and then build AMD64
 162
 163     nmake /f NTMakefile MULTIPLATFORM_INSTALLER=1
 164
 165 The build must be executed under cmd.exe.