From 348a03e48edc68f670608bc5f551f883d8fbebcb Mon Sep 17 00:00:00 2001 From: Rod Widdowson Date: Sun, 3 Apr 2022 11:43:43 +0100 Subject: [PATCH] Documentation changes for the Windows Build - Fix markup - Specific quoted command line for Visual Studio build - Caveat about line ending for gawk - Add comments about python versions - makeinfo.exe is no longer available from cygwin - Add some words about APPVER setting --- windows/README.md | 61 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 12 deletions(-) diff --git a/windows/README.md b/windows/README.md index 0c8614176..f58dbf777 100644 --- a/windows/README.md +++ b/windows/README.md @@ -1,14 +1,14 @@ Building Heimdal for Windows =================== -1. Introduction ---------------- +# 1. Introduction + Heimdal can be built and run on Windows XP or later. Older OSs may work, but have not been tested. -2. Prerequisites ----------------- +# 2. Prerequisites + * __Microsoft Visual C++ Compiler__: Heimdal has been tested with Microsoft Visual C/C++ compiler version 15.x. This corresponds to @@ -25,7 +25,8 @@ work, but have not been tested. * __Perl__: A recent version of Perl. Tested with ActiveState ActivePerl. -* __Python__: Tested with Python 2.5 and 2.6. +* __Python__: Tested with Python 2.5 and 2.6. Python 3.9 is known to not + work. * __WiX__: The Windows [Installer XML toolkit (WiX)][1] Version 3.x is used to build the installers. @@ -37,6 +38,8 @@ work, but have not been tested. However, a recent build of `makeinfo` is required for building the documentation. Cygwin makeinfo 4.7 is known to work. + - Native `makeinfo.exe` is no longer available from cygwin. + * __Certificate for code-signing__: The Heimdal build produces a number of Assemblies that should be signed if they are to be installed via Windows Installer. In addition, all executable @@ -48,14 +51,14 @@ work, but have not been tested. [1]: http://wix.sourceforge.net/ -3. Setting up the build environment ------------------------------------ +# 3. Setting up the build environment -* Start with a Windows SDK or Visual Studio build environment. The + +* Starting with a Windows SDK environment: The target platform, OS and build type (debug / release) is determined by the build environment. - E.g.: If you are using the Windows SDK, you can use the `SetEnv.Cmd` + E.g.: You can use the `SetEnv.Cmd` script to set up a build environment targetting 64-bit Windows XP or later with: @@ -67,6 +70,16 @@ work, but have not been tested. the build will produce release binaries. +* Starting with a Visual Studio build: The target platform and OS is determined + by the build environment. + + E.g.: You can use the `vcvarsall.bat` script to set up an environ,ent + script to set up a build environment targetting 64-bit Windows 10 with: + + vcvarsall.bat x64 10.0.19041.0 -vcvars_ver=14.29 -vcvars_spectre_libs=spectre + + The choice of Debug or Release is made on the `nmake` command line. + * Add any directories to `PATH` as necessary for tools required by the build to be found. The build scripts will check for build tools at the start of the build and will indicate which ones are @@ -114,6 +127,11 @@ work, but have not been tested. set CODESIGN=c:\scripts\mycodesigner.cmd set CODESIGN_SHA256=c:\scripts\mycodesigner256.cmd + - 'APPVER'. This environment variable controls the version passed to + the `-subsystem` qualifier for linker. Additionally it helps + locate the runtime library (or otherwise) associated with the + compiler (Not sure how to build for XP with VC2017) + * Define the code sign public key token. This is contained in the environment variable `CODESIGN_PKT` and is needed to build the Heimdal assemblies. If you are not using a code-sign certificate, @@ -133,15 +151,21 @@ work, but have not been tested. set CODESIGN_PKT=abcdef0123456789 -4. Running the build --------------------- +# 4. Running the build + +_If you checkout from git, you should ensure that and `awk` input files +retain unix (LF only) line endings._ Change the current directory to the root of the Heimdal source tree and run: nmake /f NTMakefile -This should build the binaries, assemblies and the installers. +This should build the binaries, assemblies and the installers. If you are +building with the Visual Studio tools you can build the release versions +by setting the NODEBUG variable + + nmake /f NTMakefile NODEBUG=TRUE The build can also be invoked from any subdirectory that contains an `NTMakefile` using the same command. Keep in mind that there are @@ -163,3 +187,16 @@ be built. First build for X86 and then build AMD64 nmake /f NTMakefile MULTIPLATFORM_INSTALLER=1 The build must be executed under cmd.exe. + +# 5. Makeinfo + +Makeinfo is no longer available from cygwin (see +[this mail thread][2]).The following appears to work +(added to NTMakefile.w32) + + MAKEINFO=$(PERL) C:\cygwin64\bin\texi2any + +You should expect a certain amount of debugging to ensure that all the required +Perl libraries are installed. + +[2]: https://sourceware.org/legacy-ml/cygwin/2015-03/msg00503.html \ No newline at end of file