1Building Heimdal for Windows
2===================
3
41. Introduction
5---------------
6
7Heimdal can be built and run on Windows XP or later.  Older OSs may
8work, but have not been tested.
9
102. 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.
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
46[1]: http://wix.sourceforge.net/
47
483. Setting up the build environment
49-----------------------------------
50
51* Start with a Windows SDK or Visual Studio build environment.  The
52  target platform, OS and build type (debug / release) is determined
53  by the build environment.
54
55  E.g.: If you are using the Windows SDK, you can use the `SetEnv.Cmd`
56  script to set up a build environment targetting 64-bit Windows XP or
57  later with:
58
59      SetEnv.Cmd /xp /x64 /Debug
60
61  The build will produce debug binaries.
62
63* Add any directories to `PATH` as necessary so that tools required by
64  the build can be found.  The build scripts will check for build
65  tools at the start of the build and will indicate which ones are
66  missing.  In general, adding Perl, Python, WiX, HTML Help Compiler and
67  Cygwin binary directories to the path should be sufficient.
68
69* Set up environment variables for code signing.  This can be done in
70  one of two ways.  By specifying options for `signtool` or by
71  specifying the code-signing command directly.  To use `signtool`,
72  define `SIGNTOOL_C` and optionally, `SIGNTOOL_O` and `SIGNTOOL_T`.
73
74  - `SIGNTOOL_C`: Certificate selection and private key selection
75    options for `signtool`.
76
77    E.g.:
78        set SIGNTOOL_C=/f c:\mycerts\codesign.pfx
79
80  - `SIGNTOOL_O`: Signing parameter options for `signtool`. Optional.
81
82    E.g.:
83        set SIGNTOOL_O=/du http://example.com/myheimdal
84
85  - `SIGNTOOL_T`: Timestamp options for `signtool`.  If not specified,
86    defaults to `/t http://timestamp.verisign.com/scripts/timstamp.dll`.
87
88  - `CODESIGN`: Code signer command.  This environment variable, if
89    defined, overrides the `SIGNTOOL_*` variables.  It should be
90    defined to be a command that takes one parameter: the binary to be
91    signed.
92
93    E.g.:
94        set CODESIGN=c:\scripts\mycodesigner.cmd
95
96* Define the code sign public key token.  This is contained in the
97  environment variable `CODESIGN_PKT` and is needed to build the
98  Heimdal assemblies.  If you are not using a code-sign certificate,
99  set this to `0000000000000000`.
100
101  You can use the `pktextract` tool to determine the public key token
102  corresponding to your code signing certificate as follows (assuming
103  your code signing certificate is in `c:\mycerts\codesign.cer`:
104
105      pktextract c:\mycerts\codesign.cer
106
107  The above command will output the certificate name, key size and the
108  public key token.  Set the `CODESIGN_PKT` variable to the
109  `publicKeyToken` value (excluding quotes).
110
111  E.g.:
112      set CODESIGN_PKT=abcdef0123456789
113
1144. Running the build
115--------------------
116
117Change the current directory to the root of the Heimdal source tree
118and run:
119
120    nmake /f NTMakefile
121
122This should build the binaries, assemblies and the installers.
123
124The build can also be invoked from any subdirectory that contains an
125`NTMakefile` using the same command.  Keep in mind that there are
126inter-dependencies between directories and therefore it is recommended
127that a full build be invoked from the root of the source tree.
128
129Tests can be invoked as:
130
131    nmake /f NTMakefile test
132
133The build tree can be cleaned with:
134
135    nmake /f NTMakefile clean
136
137