Saturday, March 14, 2015

An easy guide to installing using WIX

This tutorial is for everyone who just wants to build a simple installer using the WIX toolkit to generate a standard .MSI file. The sample has a couple of files; they get installed. A shortcut is added to the desktop. That’s it. You can read my sample, and be done in fifteen minutes, or you can wrestle your way through the maze of arcania that is the official documentation.

The first step is to install WIX; luckily it’s not hard. Go to the http://wixtoolset.org site and pick a published stable release. I used v3.9 R2 (stable). The second step is to make a directory, and dump my project files there. I used c:\temp\2015\wix, but you can use anything.

The project files is a dummy EXE, a really dummy DLL (it’s just some text), a dummy license file and a dummy help file.  There is also a .WXS WIX installer file and the BAT file that will generate a .MSI installer file. 

Edit the MyApp.msi file and make the following changes. They are detailed below, but here’s the general rule: everything with ‘myapp’ needs to be changed.

  1. Change all the GUIDs! Search for MYAPP-GUID and replace the guid. Seriously, this is critical. Note that every guid is different. There are three of them.
  2. Once you change the GUIDs, you can try the MakeInstall.bat file to make a .MSI installer file.
  3. Everywhere that there’s a MyApp in CamelCase, the string is visible to the user. This includes:
    • Product Name and manufacturer
    • Package description, comments and manufacturer
    • Property for the disk prompt (I don’t know when this will ever show up)
    • Directory to install to (which is always in the program files directory)
    • Shortcut name (the shortcut is installed on the desktop)
  4. Everywhere there’s a myapp in lowercase, it’s something that isn’t visible to the end-user
    • Media cab file (I don’t know where this is ever used)
    • File name and source for the myapp.exe, myapp.dll and more
    • The icon reference the app name
  5. Everywhere there’s a MYAPP that is all uppercase, it’s an ‘ID’. The WIX idea is that some IDs are actually chosen so that different parts of the system can refer to one another. Other ids are not like that, and have specific requirement (e.g., the icon id MUST end in .exe, which violates every principle of naming things that ever existed.

Run the MakeInstaller.bat file to make a .MSI file. There are two programs that get run, ‘candle’ and ‘light’. The BAT file will also clean up the useless intermediary files.

And like magic, you have a working installer!  Start by just using my files and just update the GUIDs in the MyApp.msi file and generate an MSI.  Then once you have a working installer and a workflow to make it, you can get fancy and install your programs and files into your preferred directories.

All my sample files are in this ZIP file.

Good luck!