heat.exe - making setup easier
Today is April 5, 2006 – the 2 year anniversary of the WiX Open Source Project!
What better way to celebrate the anniversary of the WiX Toolset than by releasing a new tool? Today, I'm proud to announce the availability of Heat in WiX 3.0. Heat is very similar in functionality to Tallow or the engine inside of ClickThrough: it has the capability to quickly capture files and directories from a computer and turn them into WiX authoring. However, the functionality of heat goes well beyond what either of these tools could provide for capturing WiX authoring. A big thanks goes to Reid for helping me make Heat a reality - he came up with a lot of the original ideas for this project and was a huge help with the harder design and naming issues.
Heat is our attempt to create an entire ecosystem of what we're calling "harvesters" and "mutators" (more on the mutators later). Harvesters are essentially WiX extensions which enable a developer to "harvest" any information into WiX authoring. For example, we've just released a new WiX extension called the WixUtilExtension. This extension contains a harvester that enables you to very quickly harvest an entire directory of files and any self-registration inside of those files. So if you have an entire directory of DLL files which each use self-reg for their COM registration, you no longer need to run Tallow on each individual file. You can now just run "heat.exe dir C:\directory -out sourceFile.wxs" and do this all automatically.
Unlike Tallow, Heat is optimized for working with WiX 3.0. This means that it does not create Id attributes on Registry elements and doesn't set short file names. Instead it relies on the auto-generation capabilities of Candle wherever possible. When Heat cannot rely on Candle to generate an identifier, it does its best to create a unique one based on the name of the file or directory that is being harvested. So if you harvest a file called "foo.dll", unless there is a collision with other files captured at the same time, its File/@Id will be "foo.dll" and the name of the component containing that file will be "foo.dll". This should make it much, much easier to capture individual parts of your setup and paste them together into your product with minimal identifier collisions.
Heat makes creating simple setup authoring faster than ever before with a templating capability. In the past, each time you create a new setup, you also had to create new Product, Package, etc... elements. Or if you're like me, I'm guessing you just copied another WiX source file and tweaked it to make your setup. With Heat, this is no longer necessary. Just run Heat with the "template" command line option like this: "heat.exe dir C:\directory -out sourceFile.wxs -template:product". This will do the normal harvesting, but then wrap the output up in a Product element. Additionally, it will hook up your root directories under TARGETDIR and put your components under a default feature. All you need to do is replace a few placeholders like "PUT-PRODUCT-NAME-HERE" with the actual values for your product and compiler/link. It's literally that easy. Just in case you are wondering, we still support auto-generation of guids - just use the -gg option. It will even generate the ProductCode. Of course, if you'd like to create a merge module quickly, you can just run with the -template:module option.
If you've read this far, there's a very good chance that you're either excited by all the new functionality in Heat or a bit disappointed because nothing in there seems to be ground-breaking. Well of course, I've saved the best part for last. Heat is not a super-tallow or command line version of ClickThrough. It's an engine for harvesting information into WiX authoring. Although all my examples so far have dealt with files and directories, there's nothing about how Heat works that prevents it from capturing more interesting things. Although its a bit under construction, Heat has the capability, today, to capture IIS web sites. Simply run 'heat.exe website "My WebSite Name" -out sourceFile.wxs' to harvest a web site and all its files. You can then compile and link with the WixIIsExtension to create an entire web site setup in minutes! Please note: there are currently a few missing bits for this feature, like it doesn't set all the Id attributes yet (I'll try to get this done for next week). Once this feature is completely finished, since Heat can set all the identifiers for you uniquely, generate all the guids, and wrap everything in a Product element with the nececessary ComponentRef elements, all you have to do is fill in a few placeholders like "PUT-PRODUCT-NAME-HERE"
I mentioned the idea of mutators earlier but didn't really go into what it meant. Mutators are a new class of functionality within WiX similar to the compiler or linker. A mutator is simply a class which takes a WiX CodeDOM object as its input and mutates it. Mutating is essentially like running a transform on XML, but since its a WiX CodeDOM, its strongly-typed and much easier to work with versus XML transforms. Mutators are the secret behind why Heat is so simple and powerful. In the past, if a harvesting tool (like Tallow) had options for tweaking its output by using fragments or wrapping the output in a Product element, the code doing the actual harvesting needed to be aware of those settings. This made adding new functionality very cumbersome because each new extension had to be aware of all the options it should be support. Even in Tallow, you may notice that depending upon how registry keys are harvested (from a .reg file or a self-reg capture), the output may differ. In Heat this is not a problem - harvesters just capture the very simplest information possible, then rely upon the mutators to mutate the output to reflect the specific options the user wants.
In later posts, I'll go into the details about how Heat works and how you can very easily write your own extensions to harvest whatever you find interesting. As you might imagine, Heat can do much, much more than I'd want to talk about in this introductory post. I hope to more fully explain its capabilities in later posts.
How does this affect ClickThrough?
ClickThrough will be refactored to use the harvesters and mutators of Heat as its new engine for capturing files from your machine. There are currently a few issues with the internal WiX authoring created by ClickThrough - this will address those issues and ensure that future versions of ClickThrough remain more in-sync with any changes made to the WiX source schema.
How does this affect Tallow?
Tallow will no longer exist in WiX 3.0. Tallow will continue to be released as part of WiX 2.0. The code for Tallow in WiX 2.0 and 3.0 is identical, so if you prefer to use Tallow instead of Heat, you can simply grab it from WiX 2.0.
Why doesn't Heat allow me to specify the text for the placeholders on the command line so that I can generate my setup every time?
Heat is designed to allow a setup author to very quickly generate their setup authoring the first time. From then onward, the authoring should be maintained manually to ensure that guids and identifiers remain stable and component rules are not broken. In order to use Heat to generate setup every time, it would be necessary to create a database which tracks the components, their guids & identifiers, and their files for every release of your product. We call this a component catalog. Heat does not provide a component cataloging capability - however - it does expose the necessary functionality so that anyone could write a component catalog, hook it into heat as an extension, and generate their setup automatically without breaking component rules.
Where should I mail Heat bug reports or feature requests?
Please submit bug reports or feature requests to the WiX site on SourceForge. I've created new categories for Heat/harvester - please use them to ensure the bugs or feature requests are properly assigned.
Are there any other planned features for Heat right now?
Sure, I think it would be nice to harvest a SQL database. There have also been a lot of ideas floating around about working with Visual Studio projects. I'm sure people will come up with lots of cool new things to do with Heat.