Building a WiX installer from the command line

WiX has excellent integration with Visual Studio, but that shouldn't stop you from using it in other IDEs. We ought to be able to create an installer using only Notepad and the WiX compiler and linker if we wanted to. Luckily, WiX gives us the freedom to do this. In this recipe, we'll write a simple .wxs file and compile it into an MSI package using Candle, which is the WiX compiler, and Light, which is the WiX linker.

Getting ready

To prepare for this recipe, perform the following steps:

1. Using a text editor such as Notepad, create a file called Product.wxs and add the following markup to it:

   <?xml version="1.0" encoding="UTF-8"?>
   <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
     <Product Id="*" 
              Name="My Software"
              Language="1033"
              Manufacturer="My Company"
              Version="1.0.0.0" 
              UpgradeCode="8c7d85db-b0d1-4a9a-85ea-130836aeef67">
       
       <Package InstallerVersion="200" 
                  Compressed="yes" 
                  InstallScope="perMachine" />
   
       <MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already installed." />
       <MediaTemplate EmbedCab="yes" />
   
       <Feature Id="ProductFeature" 
                  Title="The main feature" 
                  Level="1">
         <ComponentGroupRef Id="ProductComponents" />
       </Feature>
     </Product>
   
     <Fragment>
       <Directory Id="TARGETDIR" Name="SourceDir">
         <Directory Id="ProgramFilesFolder">
           <Directory Id="INSTALLFOLDER" 
                          Name="My Software" />
         </Directory>
       </Directory>
     </Fragment>
   
     <Fragment>
       <ComponentGroup Id="ProductComponents" 
                         Directory="INSTALLFOLDER">
         <Component Id="cmpMyTextFileTXT" 
                       Guid="{A4540658-09B6-46DA-8880-0B1962E06642}">
           <File Source="MyTextFile.txt" />
         </Component>
       </ComponentGroup>
     </Fragment>
   </Wix>

2. This installs a text file called MyTextFile.txt. So, add a text file with this name to the same directory as Product.wxs. We will compile the two files from the command line to create an installer.

How to do it…

Open a command prompt and use candle.exe and light.exe to compile and link our WiX source file:

1. Open a command prompt by navigating to Run | cmd.
2. Change the directory to where the Product.wxs and MyTextFile.txt files are using the following command line:

   cd C:\MyProject
   

3. Use Candle to compile the .wxs file into a .wixobj file and then place it in an output folder called obj. Be sure to surround the path to Candle, %WIX%bin\candle, with quotes since it will contain spaces when it is expanded:

   "%WIX%bin\candle" *.wxs -o obj\
   

4. Use Light to link the text file and the .wixobj file together to form an MSI:

   "%WIX%bin\light" obj\*.wixobj -o bin\CommandLineInstaller.msi
   

How it works…

When we installed the WiX toolset, it gave us the WiX compiler, which is candle.exe, and linker, which is light.exe. These are the only tools we need to create an MSI from our WiX source file, Product.wxs. From the command line, we navigated to the directory where our source file was and then used Candle and Light to compile and link the file to create an MSI installer.

The first argument we passed to Candle was *.wxs. This selects all the .wxs files in the current directory and includes them in the compilation. Next, the -o argument tells Candle where to send the output of the compilation step. In this case, we sent it to a directory called obj. Note that the directory name ends in a backslash so that Candle knows that it's a directory. If it didn't exist before, it will be created.

The output of the Candle command was a file called Product.wixobj. This was an intermediate file that was picked up by light.exe in the next step. The first argument we passed to Light was the location of the .wixobj files: obj\*.wixobj. By using an asterisk, we select all the .wixobj files in the obj directory. The -o argument tells Light where to create the MSI file and what to name it. In this case, we create a file called CommandLineInstaller.msi.

Another file called CommandLineInstaller.wixpdb was also created. This can be used when building patch files. You can learn more by reading Peter Marcu's blog post WiX: Introducing the WixPdb at http://petermarcu.blogspot.com/2008/02/wix-introducing-wixpdb.html.

There are a number of arguments that can be passed to Candle and Light that you might want to get to know. Passing the -? flag to either will give you a list of all the available options:

"%WIX%bin\candle" -?

"%WIX%bin\light" -?

Note

We used the %WIX% system environment variable to resolve the path to the WiX bin directory, where candle.exe and light.exe are present. This variable is added when you install the WiX toolset and resolves to C:\Program Files (x86)\WiX Toolset v3.9. It will not be present if you are using the WiX binaries directly without installing the WiX toolset.