Create Windows installer with Wix

To create a new Windows installer using Wix Toolset is relatively easy. The toolset has several tools to aid in that process, but we will use candle and light here. To see all available tools and more explanation on how to use them check Wix documentation.

To use candle a Windows Installer XML Source file (wxs) is required. This file contains all the information about the package contents, like what files it contains and where they should be stored upon installation. Some information on what each tag represents and expects is given below and a full wxs file is here.

Almost every tag in the file needs a GUID, that is a unique number in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. It is composed of hexadecimal numbers and it's how Windows handles what is installed/uninstalled. Any place that has YOUR-GUID in this document requires a valid and unique GUID to work properly.

1. Product tag describes name, language, version and whoever is responsible for this package.

<Product Name="templateTest 1.0.1" Id="YOUR-GUID" UpgradeCode="YOUR-GUID" Language='1046' Codepage='1252' Version="1.0.1" Manufacturer='UnB Games'>

2. A Directory tag simply has an unique ID and a Name. If that folder doesn't exist in the system, it will be created upon installation. If the Directory has to referenced anywhere in the document, its ID must be used, hence the need for it to be unique. Windows pattern on new packages is to install them under Program Files (or Program Files (x64) if the package is 64 bit). The contents of the package should go under a folder with its name inside a folder with the maintainer's name. (Eg: The game Wenova should be found in C:/Program Files/UnB Games/Wenova/). The TARGETDIR directory should always be used and the other folders should be described inside this one (check here for more details).

<Directory Id='TARGETDIR' Name='SourceDir'>
    <Directory Id='ProgramFilesFolder' Name='PFiles'>
        <Directory Id='UnBGames' Name='UnB Games'>
            <Directory Id='INSTALLDIR' Name="templateTest 1.0.1">

3. The Component tag is the smallest piece of information an installer knows, and have an Id and a GUID. It also has to have a KeyPath (or the file it holds if it's only one). It is comprised of one or many files, but it's not recommended to add all files to one single component. A component should hold the files that are required together (see Components on the Wix tutorial).

<Component Id='MainExecutable' Guid="5BCBBD55-C5FD-479F-B38E-66232500DAB0">
    <File Id="templateTest" Name="templateTest.exe" DiskId='1' Vital='yes' Source="templateTest.exe" KeyPath='yes'></File>
    <Shortcut Id="ProgramMenuDirtemplateTest" Directory="ProgramMenuDir" Name="templateTest 1.0.1" WorkingDirectory='INSTALLDIR' Icon="icon.ico" IconIndex="0" Advertise="yes"/>
    <Shortcut Id="DESKTOPFOLDERDIRtemplateTest" Directory="DESKTOPFOLDERDIR" Name="templateTest 1.0.1" WorkingDirectory='INSTALLDIR' Icon="icon.ico" IconIndex="0" Advertise="yes"/>
</Component>

4. The File tag represents a file that will be installed on the system. It should always come inside a component tag and it has an ID, to uniquely identify that file; a name, the actual file name; and a source, that contains the location of the file relative to the root folder of the project.

<Component Id="logo.png" Guid="964DD0E4-E1AD-46D1-AD94-F9916EDBE75E" KeyPath='yes'>
    <File Id="_RESOURCES_IMAGES_LOGO.PNG" Name="logo.png" DiskId='1' Source="resources/images/logo.png"/>
</Component>

5. A Feature tag tells the installer what exactly will be installed and uninstalled. It specifically useful for when there are documentation, tutorials and different parts of the program the user wishes or not to install. Inside this tag, we use a ComponentRef to refer to the components being installed.

<Feature Id="Complete" Title='templateTest%% 1.0.1%%' Description='Game short description' Display='expand' Level='1' ConfigurableDirectory='INSTALLDIR'>
    <Feature Id="MainExecutable" Title='templateTest%% 1.0.1%%' Description='Game short description' Display='expand' Level='1' ConfigurableDirectory='INSTALLDIR'>
        <ComponentRef Id="MainExecutable" />
        <ComponentRef Id="SDL" />
        <ComponentRef Id="icon.ico" />
        <ComponentRef Id="logo.png" />
        <ComponentRef Id="ProgramMenuDir" />
    </Feature>
</Feature>

After the wxs file is ready, it's pretty simple to create the msi file. One just have to run:

candle.exe my_package.wxs
light.exe -ext WixUIExtension my_package.wixobj

WixUIExtension is used to tell light to assemble the files using an UI installer.