Wednesday, 22 October 2008

How To Create a WiX build machine

After quite a bit of struggling to build WiX I have finally succeeded, so I thought I would share the process. The WiX help file and the make.bat file outline what is required but it misses a lot of the detail, in particular there are quite a few files that are not in the WiX source zip file but they are in CVS.

Update: I have revised this following recent changes to WiX, this now applies to WiX v3.0.4707.0 or later.

These notes should be read in conjunction with the WiX help file topic "Building WiX".

  1. Operating system: Windows 2008 Standard (Full Installation), installed with default options in a Virtual Machine.
    - I chose Windows 2008 but the following instructions should also apply to other OS's.
    - There is quite a lot to install and so I setup a 32Gb drive, the OS and all the tools took up about 20Gb of disk space, to build the source you will need about 2Gb.
  2. .Net Framework 3.5 SP1
    - This is required to build WiX but only .Net Framework 2.0 is required to run WiX.
  3. NAnt (build 2008-02-10-0.86 or later) with the modification to the SDK path shown in the WiX help file.
  4. Sandcastle May 2008 Release (Version 2.4.10520) and Sandcastle Help File Builder The DTF help builder looks for them in an "external" directory parallel to the WiX "src" directory:
    - Sandcastle: "external\Sandcastle"
    - Sandcastle Help File Builder: "external\SandcastleBuilder"
    NOTE: Don't get Sandcastle Help File Builder v1.8.0.0 or newer as they've removed the console version that DTF uses.
  5. Visual Studio 2005 plus Service Pack 1 (SP1 isn't required but I thought it made sense).
    NOTE: It is necessary to install "C++ | x64 Compilers and Tools" if you want to build the Visual Studio 2005 version of Votive even if you don't want the x64 components.
  6. Visual Studio 2008 plus Service Pack 1 (SP1 isn't required but I thought it made sense).
  7. Visual Studio 2005 SDK Version 4.0 (February 2007) -
  8. Visual Studio 2008 SDK Version 1.0 -
  9. Optional - Microsoft HTML Help 1.4 SDK
    - I didn't install this as it is not required if you have installed all the previous items (check for "C:\Program Files\HTML Help Workshop").
  10. Optional - Windows SDK for Windows Server 2008 and .NET Framework 3.5
    - I only installed the "Developer Tools" excluding the "Mobile Tools".
    - This is only required to build the optimized IA64 binaries (see comment below).
  11. Optional - TortoiseCVS - a version of CVS is required if you want to get the source.

Code Signing

By default when you build the WiX source it is delay signed with the Microsoft Public WiX key. This means that the code will only run on the machine that it is built on or any machine that trusts the public key. You can check this by running "sn -Vl" - if it returns "*,36e4ce08b8ecfb17" the code is trusted. If you want to trust it you can run "sn -Vr *,36e4ce08b8ecfb17".

If you want to run the code on any other machine it is necessary to create your own signing key, e.g.: "sn -k wixkey.snk". You then need to set the environment variable OFFICIAL_WIX_BUILD to the path to this file, e.g.: "set OFFICIAL_WIX_BUILD=<path>\wixkey.snk". See "Helper batch file" below.

If you want to build Votive you also need to modify the sconce project to allow it to trust your key as follows:
1. Extract the public key from your key with "sn -p wixkey.snk wixkeypublic.snk"
2. Run "sn -tp wixkeypublic.snk" this will display the public key (the long string of bytes is the one you want, the key is displayed on several lines, remove the line breaks from the public keybefore you use it)
3. Now edit "src\Votive\sconce\Properties\AssemblyInfo.cs" and add your key to the ones that are already there, e.g.: 
              [assembly: InternalsVisibleTo("votive2005, PublicKey=YOUR_KEY_HERE")]
              [assembly: InternalsVisibleTo("votive2008, PublicKey=YOUR_KEY_HERE")]

WiX Source

  1. Download and extract the WiX source zip file or download from CVS. (I prefer to use the source zip file.)
  2. If you are building from the source zip file you will need the following files from CVS as they are not in the zip file (or you may already have them on your machine in one of the Visual Studio or SDK folders).


  3. On Windows 2008 and Windows Vista you will need to run the "make.bat" as an Administrator.

If all goes well you should now be able to build the full WiX release (I do this through the batch file shown below). When the build is complete the files will be copied to "build\ship\x86\wix3\3.0.xxxx.0" or "build\debug\x86\wix3\3.0.xxxx.0"


  1. Error: "src\dtf\tools\sfxca\precomp.h(32) : fatal error C1083: Cannot open type library file: 'mscorlib.tlb': No such file or directory."
    - If you run the "Visual Studio 2008 Command Prompt" you will probably find that "C:\Windows\Microsoft.NET\Framework\v2.0.50727" is not in the path, either add it manually or run "%VS90COMNTOOLS%\vsvars32.bat" (see batch file below).
  2. If you do want to install "Microsoft HTML Help 1.4 SDK" the link in the WiX help file takes you to an MSDN page but the link in there to the download is broken. The file can be downloaded from here: When you install this it is titled "HTML Help 1.3" but this is the correct install.
  3. If you get an error saying "DTFAPI.chm" cannot be found then it probably hasn't been built because the build cannot find the Sandcastle files in the "external" folder.

Accessing WiX CVS

If you have CVS installed (I use TortoiseCVS which also installs CVSNT) then the following commands will retrieve all the source:

cvs.exe login -p ""
cvs.exe -z3 co -P wix

Helper batch file

Because I am lazy and can never remember command lines I created a helper batch file to call make.bat. This batch file sets up the environment and allows you to run a few make scenarios.

@echo off
REM *****************************************************************
REM Menu to run the WiX build
REM *****************************************************************

cd /d %~dp0

echo *****************************************************************
echo WiX Build
echo *****************************************************************
echo 1. Full build - debug
echo 2. Incremental - debug
echo 3. Full build - ship
echo 4. Incremental - ship
echo 5. Clean all
echo x. Exit

set /p opt=Select option and press enter:

REM Check for exit
if "%opt%"=="x" goto :EOF

REM Setup environment
call "%VS90COMNTOOLS%\vsvars32.bat"
path=C:\Program Files\NAnt\bin;%path%

set OFFICIAL_WIX_BUILD=%~dp0bin\wixkey.snk

REM Run selected action
if "%opt%"=="1" Call make debug build -l make.log
if "%opt%"=="2" Call make debug inc-l make.log
if "%opt%"=="3" Call make ship build-l make.log
if "%opt%"=="4" Call make ship inc-l make.log
if "%opt%"=="5" (
Call make debug clean
Call make ship clean
goto :START

Edit: 23/10/08 - based on feedback I have updated the instructions.
Edit: 07/11/08 - updated for WiX v3.0.4707.0.
Edit: 29/12/08 - updated to include note about VS2005.
Edit: 07/01/09 - updated to include code signing.
Edit: 09/05/09 - updated Sandcastle references.


Bob Arnson said...

Note that VS2005 and both VS SDKs are required only to build Votive.

And .NET 3.5 is required to build WiX, though only .NET 2.0 is required to run it.

The Windows SDK is also optional; it's used to build optimized IA64 binaries, for the three people in the world who care. 8-)

Neil Sleightholm said...

Bob, thanks for your comments I have updated the blog to reflect them. I will try removing the Windows SDK and check it still builds. Although VS2005 and the SDKs are optional, if you don't want to see build errors and want to create the WiX installer they aren't.

Bob Arnson said...

The build process has hooks to skip parts of the build that aren't supported, like Votive when VS2005/SDKs aren't installed.

Mostly, it depends on what you're hoping to do with a WiX build. Being able to build an installer requires building every bit. Building just the toolset is much lighter.

We can keep the necessary bits checked in to source control, but obviously we'd get a talking to if we started checking VS in to CVS. 8-)

Neil Sleightholm said...

Fair point, my goal was to build a full install - there is a reason for this but you wouldn't believe it if I told you.

I think most of the VS bits are already in CVS just not in the zip file.

Christopher Karper said...

Just some updates for you...

1.) The Sandcastle Help File Builder doesn't have the specified release available anymore. Don't get v1.8.0.0 or newer, as they've removed the Console version that DTF uses. Get until DTF updates to use the new native MDBuild method.

2.) The newer version of Help File Builder needs the current Sandcastle release. (v2.4.10520 at the time of this comment)

3.) I also ran into a problem building DTF embedded UI with the WinFX targets file. The fix is detailed at this link:

Thanks for the work and walkthrough!

Neil Sleightholm said...

Thanks for the info Christopher, I'll take a look and update the post appropriately.

Hegsie said...

This information has been superb, Its only taken me 2 days to build wix, and this post has been my bible... Cheers

Konstantin said...

Have upoaded 3 files BIN_File_* to src\ext\VSExtension\Redist but still get this error:
[exec] Microsoft (R) Build Engine Version 3.5.30729.1
[exec] [Microsoft .NET Framework, Version 2.0.50727.3082]
[exec] Copyright (C) Microsoft Corporation 2007. All rights reserved.
[exec] CopyFilesToOutputDirectory:
[exec] WixTasks -> C:\wix\wix3.0.5419.0-sources\build\debug\x86\WixTasks.dll
[exec] CopyFilesToOutputDirectory:
[exec] Wix -> C:\wix\wix3.0.5419.0-sources\build\debug\x86\wix.dll
[exec] lit.exe : error LIT0103: The system cannot find the file 'C:\wix\wix3.0.5419.0-sources\src\ext\VSExtension\wixlib\\Redist\BIN_File_46002' with type ''.

BUILD FAILED - 6 non-fatal error(s), 2 warning(s)

External Program Failed: c:\WINDOWS\Microsoft.NET\Framework\v3.5\msbuild.exe (return code was 1)

Konstantin said...

Sorry :) Please ignore my question.
Have placed Redist in the wrong place.

Anonymous said...


Do you have an updated description for WiX 3.6 so I can build a weekly update from the source control server myself?

Albert van Peppen

Neil Sleightholm said...

Afraid not, although the last time I tried I found it much simpler. IIRC you only need to call "bin\wixenv.bat" then run the make.bat file.

Nathan said...

I value this article more than WiX itself :) That's how frustrated I get when a project refuse to build. THANKS Neil !!!

Lee said...

Hi Neil,

I've been trying to build WIX on a windows7 box, but been unsucessful. I followed the instructions you posted (I hope correctly) and using also the bat file you created to build a WIX debug Full build.but keep running into this error.

Target framework: Microsoft .NET Framework 3.5
Target(s) specified: build

[property] Target framework changed to "Microsoft .NET Framework 2.0".
[property] Read-only property "dir.hhw" cannot be overwritten.
[property] Read-only property "hhw-found" cannot be overwritten.
[readregistry] Registry Path Not Found! - key='SOFTWARE\Microsoft\VisualStudio\1
[readregistry] Registry Path Not Found! - key='SOFTWARE\Microsoft\VisualStudio\1
[readregistry] Registry Path Not Found! - key='SOFTWARE\Microsoft\VisualStudio\1
[readregistry] Registry Path Not Found! - key='SOFTWARE\Microsoft\VisualStudio\1
[echo] Pre-requisite Check Passed: Visual Studio 10.0 Test Tools are instal
[echo] Pre-requisite Check Passed: .Net Framework 4.0 Full is installed.
[echo] Pre-requisite Check Failed: Microsoft.Web.Administration.dll is not
[echo] Pre-requisite Check Failed: Qtests directory was not found.


[readregistry] Registry Path Not Found! - key='SOFTWARE\Microsoft\VisualStudio\8
[readregistry] Registry Path Not Found! - key='SOFTWARE\Wow6432Node\Microsoft\Vi
[echo] Couldn't find the Visual Studio 2005 VC Directory. VS2005-compatible
versions of libraries will be excluded from the build.
[echo] Found Visual Studio 2010 VC Directory : c:\Program Files (x86)\Micro
soft Visual Studio 10.0\VC\
[echo] Found Visual Studio 2008 VC Directory : c:\Program Files (x86)\Micro
soft Visual Studio 9.0\VC\
[echo] Setting main VC directory to : c:\Program Files (x86)\Microsoft Visu
al Studio 9.0\VC\
[readregistry] Registry Path Not Found! - key='SOFTWARE\Microsoft\Microsoft SDKs
[readregistry] Registry Path Not Found! - key='SOFTWARE\Wow6432Node\Microsoft\Mi
crosoft SDKs\Windows\v7.1\';hive='Microsoft.Win32.RegistryHive[]';
[echo] Setting PlatformSDKDir directory to : c:\Program Files (x86)\Microso
ft SDKs\Windows\v7.0A\

BUILD FAILED - 8 non-fatal error(s), 2 warning(s)

Some x64 components necessary for compilation were not found. Ensure you have in
stalled the x64 components in the Windows Server 2008 and .NET Framework 3.5 SDK
or Visual Studio 2008.

Total time: 1 seconds.

An I missing something on my machine? Target definition or Other?
Thanks InAdvance

Neil Sleightholm said...

The instruction here are for build WiX 3.0 and I think it looks like you are building WiX 3.8 - there is some more up to date information here

Looking at the error you are getting it looks like you are missing some of the Windows SDK.

Lee said...

So I was able to fix my problem by installing the Windows Server 2008 and .NET Framework 3.5 SDK. You can download the package here Thanks for your help Neil. You point me in the right direction.