What are .wixlibs and why would you use them?
One of the cool contributions Visual Studio is making to the WiX toolset is the attention of a technical writer, Martin. Improving the WiX documentation is a constant request so any help someone is willing to provide is much appreciated. Of course, when there is very little information about a particular feature then technical writers have nothing to work their word-smithing magic on. Martin pointed out one such area recently: .wixlibs.
What is a .wixlib?
At its most basic level a .wixlib is simply a collection of .wixobjs. That hopefully isn’t surprising since the input to the tool that creates .wixlib files, lit.exe, is a bunch of .wixobj files. If you look into a normal .wixlib, you’ll see that it is just a <wixLibrary/> element wrapping a bunch of <section/> elements which is exactly what the <wixObject/> element does.
The difference is that a .wixobj contains only the sections from a compiled .wxs file while a .wixlib contains the sections from all of the .wixobj combined together by lit.exe. Another difference is that lit.exe can create a “binary .wixlib” which also combines all of the files referenced by the .wixobj files into the .wixlib. The “binary .wixlib” is a feature that was added in WiX v3 and is not available in WiX v2.
Ultimately, .wixobj and .wixlib files are passed to the linker, light.exe, to be processed into an .MSI or .MSM file.
Why would you use a .wixlib?
Since .wixobj and .wixlib files can be used interchangeably, you might wonder why bother with .wixlibs. There are a few reasons to consider.
-
Fewer files to link. If you product is very large and has lots and lots of .wixobj files then the linker may spend more time reading the many small .wixobj files than it would reading fewer but larger .wixlib files. If your build system allowed you to build .wixlibs in parallel then you may get better overall build throughput.
-
Fewer files to share. If you need to share setup logic with people who are using the WiX toolset, you can combine several of your .wixobj files into a .wixlib file or two. One or two files are certainly easier to consume than a directory full of .wixobj files.
-
Abstracts the source file organization. Similar to #2 but a little different. Since you get one .wixobj per .wxs file any changes to the organization of your source code mean that downstream consumers must also change, even if it is just to add another .wixobj file name to the light.exe command-line. If you share .wixlibs then you abstract away the number of .wixobj flies from the consumers of the .wixlib, simplifying their life. And who doesn’t want to make their customer’s lives better?
-
Binary .wixlibs are a better Merge Module. If you are sharing setup logic with people who are using the WiX toolset then binary .wixlibs are far superior to Merge Modules. The linker can introspect into binary .wixlibs better than Merge Modules providing better linking and error reporting. The linker can also access the embedded files more efficiently than the files in Merge Modules. Finally, .wixlibs provide infinitely better information than Merge Modules for patching.
Why wouldn’t you use a .wixlib?
If your build isn’t huge and highly parallelized and you don’t share any setup logic with other WiX users then .wixlibs are probably just overhead. Also, if you need to share your setup authoring with customers who are not using the WiX toolset then you’ll need to use Merge Modules not .wixlib files.
How about a bit of history?
Sure, I love to talk about the history of features. As you might guess, the history of .wixlibs starts with Merge Modules. I wrote the Merge Module spec back in 1998 when I was an intern on the Windows Installer team. The goal was to create a mechanism for developers to share setup logic and the respective files.
When I later joined Microsoft full time in 1999 and started working on WiX v1 I had the idea that Merge Modules could be used as the building blocks to create large complicated setups. To make a long story short, that design was flawed because the Module Id appended to all of the primary keys made things difficult to integrate and Merge Modules did not provide quite the right granularity for all pieces of a product.
So, in WiX v2 I introduced the concept of symbols/references, sections and library files. Unfortunately, in WiX v2 there were no binary .wixlibs so you had to distribute any referenced files along with the .wixlib. That was a pain. Derek fixed that issue in WiX v3.
One of the first big changes to WiX v3 was to add the ability for lit.exe to create “binary .wixlib” files which contained the referenced files in a cabinet file prepended to the .wixlib’s XML blob. This gave us the best features of both of .wixlib files and Merge Modules, as long as you are using the WiX v3 toolset everywhere.
These days I always recommend that if you are sharing setup logic and files with people also using WiX v3, skip Merge Modules and just use binary .wixlibs.