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.  Python 3.9 is known to not
  29   work.
  30
  31 * __WiX__: The Windows [Installer XML toolkit (WiX)][1] Version 3.x is
  32   used to build the installers.
  33
  34 * __Cygwin__: The Heimdal build system requires a number of additional
  35   tools: `awk`, `yacc`, `lex`, `cmp`, `sed`, `makeinfo`, `sh`
  36   (Required for running tests).  These can be found in the Cygwin
  37   distribution.  MinGW or GnuWin32 may also be used instead of Cygwin.
  38   However, a recent build of `makeinfo` is required for building the
  39   documentation. Cygwin makeinfo 4.7 is known to work.
  40
  41   - Native `makeinfo.exe` is no longer available from cygwin.
  42
  43 * __Certificate for code-signing__: The Heimdal build produces a
  44   number of Assemblies that should be signed if they are to be
  45   installed via Windows Installer.  In addition, all executable
  46   binaries produced by the build including installers can be signed
  47   and timestamped if a code-signing certificate is available.
  48   As of 1 January 2016 Windows 7 and above require the use of sha256
  49   signatures.  The signtool.exe provided with Windows SDK 8.1 or
  50   later must be used.
  51
  52 [1]: http://wix.sourceforge.net/
  53
  54 # 3. Setting up the build environment
  55
  56
  57 * Starting with a Windows SDK environment:  The
  58   target platform, OS and build type (debug / release) is determined
  59   by the build environment.
  60
  61   E.g.: You can use the `SetEnv.Cmd`
  62   script to set up a build environment targetting 64-bit Windows XP or
  63   later with:
  64
  65       SetEnv.Cmd /xp /x64 /Debug
  66
  67   The build will produce debug binaries.  If you specify
  68
  69       SetEnv.Cmd /xp /x64 /Release
  70
  71   the build will produce release binaries.
  72
  73 *  Starting with a Visual Studio build: The target platform and OS is determined
  74    by the build environment.
  75
  76    E.g.: You can use the `vcvarsall.bat` script to set up an environ,ent
  77    script to set up a build environment targetting 64-bit Windows 10 with:
  78
  79        vcvarsall.bat x64 10.0.19041.0  -vcvars_ver=14.29 -vcvars_spectre_libs=spectre
  80
  81    The choice of Debug or Release is made on the `nmake` command line.
  82
  83 * Add any directories to `PATH` as necessary for tools required by
  84   the build to be found.  The build scripts will check for build
  85   tools at the start of the build and will indicate which ones are
  86   missing.  In general, adding Perl, Python, WiX, HTML Help Compiler and
  87   Cygwin binary directories to the path should be sufficient.
  88
  89 * Set up environment variables for code signing.  This can be done in
  90   one of two ways.  By specifying options for `signtool` or by
  91   specifying the code-signing command directly.  To use `signtool`,
  92   define `SIGNTOOL_C` and optionally, `SIGNTOOL_O` and `SIGNTOOL_T`.
  93
  94   - `SIGNTOOL_C`: Certificate selection and private key selection
  95     options for `signtool`.
  96
  97     E.g.:
  98
  99         set SIGNTOOL_C=/f c:\mycerts\codesign.pfx
 100
 101         set SIGNTOOL_C=/n "Certificate Subject Name" /a
 102
 103   - `SIGNTOOL_O`: Signing parameter options for `signtool`. Optional.
 104
 105     E.g.:
 106
 107         set SIGNTOOL_O=/du http://example.com/myheimdal
 108
 109   - `SIGNTOOL_T`: SHA1 Timestamp URL for `signtool`.  If not specified,
 110     defaults to `http://timestamp.digicert.com`.
 111
 112   - `SIGNTOOL_T_SHA256`: SHA256 Timestamp URL for `signtool`.  If not
 113     specified, defaults to `http://timestamp.digicert.com`.
 114
 115   - `CODESIGN`: SHA1 Code signer command.  This environment variable, if
 116     defined, overrides the `SIGNTOOL_*` variables.  It should be
 117     defined to be a command that takes one parameter: the binary to be
 118     signed.
 119
 120   - `CODESIGN_SHA256`: SHA256 Code signer command.  This environment variable, if
 121     defined, applies a second SHA256 signature to the parameter.  It should be
 122     defined to be a command that takes one parameter: the binary to be
 123     signed.
 124
 125     E.g.:
 126
 127         set CODESIGN=c:\scripts\mycodesigner.cmd
 128         set CODESIGN_SHA256=c:\scripts\mycodesigner256.cmd
 129
 130    - 'APPVER'.  This environment variable controls the version passed to
 131      the `-subsystem` qualifier for linker.  Additionally it helps
 132      locate the runtime library (or otherwise) associated with the
 133      compiler (Not sure how to build for XP with VC2017)
 134
 135 * Define the code sign public key token.  This is contained in the
 136   environment variable `CODESIGN_PKT` and is needed to build the
 137   Heimdal assemblies.  If you are not using a code-sign certificate,
 138   set this to `0000000000000000`.
 139
 140   You can use the `pktextract` tool to determine the public key token
 141   corresponding to your code signing certificate as follows (assuming
 142   your code signing certificate is in `c:\mycerts\codesign.cer`:
 143
 144       pktextract c:\mycerts\codesign.cer
 145
 146   The above command will output the certificate name, key size and the
 147   public key token.  Set the `CODESIGN_PKT` variable to the
 148   `publicKeyToken` value (excluding quotes).
 149
 150   E.g.:
 151
 152       set CODESIGN_PKT=abcdef0123456789
 153
 154 # 4. Running the build
 155
 156 _If you checkout from git, you should ensure that and `awk` input files
 157 retain unix (LF only) line endings._
 158
 159 Change the current directory to the root of the Heimdal source tree
 160 and run:
 161
 162     nmake /f NTMakefile
 163
 164 This should build the binaries, assemblies and the installers.  If you are
 165 building with the Visual Studio tools you can build the release versions
 166 by setting the NODEBUG variable
 167
 168     nmake /f NTMakefile NODEBUG=TRUE
 169
 170 The build can also be invoked from any subdirectory that contains an
 171 `NTMakefile` using the same command.  Keep in mind that there are
 172 inter-dependencies between directories and therefore it is recommended
 173 that a full build be invoked from the root of the source tree.
 174
 175 Tests can be invoked, after a full build, by executing:
 176
 177     nmake /f NTMakefile test
 178
 179 The build tree can be cleaned with:
 180
 181     nmake /f NTMakefile clean
 182
 183 It is recommended that both AMD64 and X86 builds take place on the
 184 same machine.  This permits a multi-platform installer package to
 185 be built.  First build for X86 and then build AMD64
 186
 187     nmake /f NTMakefile MULTIPLATFORM_INSTALLER=1
 188
 189 The build must be executed under cmd.exe.
 190
 191 # 5. Makeinfo
 192
 193 Makeinfo is no longer available from cygwin (see
 194 [this mail thread][2]).The following appears to work
 195 (added to NTMakefile.w32)
 196
 197     MAKEINFO=$(PERL) C:\cygwin64\bin\texi2any
 198
 199 You should expect a certain amount of debugging to ensure that all the required
 200 Perl libraries are installed.
 201
 202 [2]: https://sourceware.org/legacy-ml/cygwin/2015-03/msg00503.html