README.md
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. 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
513. 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
1364. Running the build
137--------------------
138
139Change the current directory to the root of the Heimdal source tree
140and run:
141
142 nmake /f NTMakefile
143
144This should build the binaries, assemblies and the installers.
145
146The build can also be invoked from any subdirectory that contains an
147`NTMakefile` using the same command. Keep in mind that there are
148inter-dependencies between directories and therefore it is recommended
149that a full build be invoked from the root of the source tree.
150
151Tests can be invoked, after a full build, by executing:
152
153 nmake /f NTMakefile test
154
155The build tree can be cleaned with:
156
157 nmake /f NTMakefile clean
158
159It is recommended that both AMD64 and X86 builds take place on the
160same machine. This permits a multi-platform installer package to
161be built. First build for X86 and then build AMD64
162
163 nmake /f NTMakefile MULTIPLATFORM_INSTALLER=1
164
165The build must be executed under cmd.exe.
166