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