My philsophical musings about building setup for software.

I have some philosophies about how to build software and setup for software that I've never posted here. So, I thought I'd share those philosophies today.

Mike Gunderloy, who has written a couple articles about the WiX toolset, posted a comment on a previous blog entry. In the comment, he suggests that splitting a setup project into fragments only moves the problem but doesn’t solve it. Thus, he argued that adding a tool to generate the fragments has value. I still didn’t agree. Then I realized that I disagreed because I have some philosophies about how to build software and setup for software that I’ve never posted here. So, I thought I’d share those philosophies today. Please note that these are guidelines that I use when discussing setup build processes with other people not hard rules.

The developer that wrote the feature knows best what needs to be authored into setup.

This part of my philosophy is based on the fact that the person that knows the most about a particular resource is the developer that wrote the resource. Seriously, if the developer who wrote the code doesn’t know where his or her files need to be installed or doesn’t know what registry keys are necessary to make the feature work (or whatever other resources are necessary) who does?

Yes, there have been (too many) cases in my career where the developer who wrote the code said, “Uhh, I don’t know what my code depends on.” However, in those cases it was pretty easy to look at him or her (or his or her manager) and ask, “Well, uhh, shouldn’t you?” In every case, they went off and figured out what was necessary to get their software “in the box”.

Fundamentally, if developers don’t know what their dependencies are there is very little chance their project will have a solid security, performance, or deployment story. Area experts may be necessary to help developers work through complicated issues but, in general, developers must be aware of what their software is doing.

Setup authoring is a part of the development process.

Every team I have interacted with (the grand majority of Microsoft and some smaller companies), the developers on the team are expected to add their source files to the makefile before checking in new files to the project. Yet, many of those teams have people who are solely responsible for adding new files to the setup project. In many cases, one set of developers write registry keys into the code for SelfReg (this is evil, and I’ll explain why one day) and the setup developers have to reverse engineer the registry keys out of the built executables to author setup. Why didn’t the original developer just author the registry key into setup in the first place?

There was a point in time where it was arguably difficult to distribute the authoring to all developers when you had to buy custom tools that didn’t fit well into the development process. However, today there are a few alternatives out there (like the WiX toolset) that allow setup to be treated like source code. Now there are no excuses I’ve heard that hold water why setup authoring for the majority of the resources in setup cannot be distributed across the developers in the organization. Doing that distribution leaves only the “look and feel” and integration between the individual pieces of setup to the core setup developers. All other excuses have always been just whinging (as Peter might say).

This part of my philosophy and the one above are the reasons I disagree when Mike says that “breaking up the package into multiple source fragments pushes the problem back one level, but doesn’t necessarily solve it.” Breaking up your setup in to multiple text files enables developers to maintain setup authoring the same way they maintain all the other code that is part of a project. And that brings me to my final point.

Text files should be the only inputs into the build process.

Over the years, developers have created fairly significant processes for tracking, merging, and reverting changes to text files. For example, Concurrent Version System (better known as CVS) is used heavily by SourceForge.net can show you the individual lines changed in a text file over time. For a demonstration, take a look at Compiler.cs from v1.6 to v1.7 in CVS at SourceForge.net for WiX. It is not generally possible to visualize the differences between two revisions of a binary file.

Every input into the build process that is manipulated by a human will eventually hose the process at least once. Being able to text search (using even the simplest tools like grep) for the exact change that caused the problem significantly improves build throughput. Binary files usually hide the information by requiring custom tools to be opened and queried to find the break.

Of course, once you find the break it is really nice to be able to fix the problem by launching your favorite text editor and tweaking the line(s) of code with the fault. Requiring a tool to be installed on the build machines increases your impedance to fixing the issue.

Ultimately, keeping binary files out of your build process simplifies your life. That fact is why I disagree with Mike when he suggests it makes sense to “put one more tool into the chain, something with a friendly interface that could spit out the source fragments as needed? I could see doing that with Access/Excel, among other things.”

Note I do think it is reasonable for developers to use tools that help generate text files. Those text files then can get checked into source control and built as part of the standard process. However, the tools need to generate human friendly text files. Text files that can only be modified with a custom tool are only half a step better than raw binary files.

This is the philosophy that I developed during my tenure in Office and have promoted across the company for a couple years now. Many teams have had an incredible amount of success with their setup processes when following these guidelines. There have been many cases where I was asked by other teams to talk about the philosophy. At the end of my talk I always left them with, “If you have someone resisting change, have them contact me. I’ll be happy to talk to him or her to discuss how successful other teams have been with this process and see if there isn’t some way to address their concerns.” I’d be happy to do the same for you.

PS: This philosophy has worked out extremely well for me, but if you have a unique situation that you think wouldn’t work using these guidelines, I’d be very interested to hear about them. I’m always looking for alternative views (as long as people aren’t just whinging <smile/>).