The value of setup scripts for your development and build machines has come up before. Creating these scripts can save your organization hundreds or thousands of hours of work over the course of a year. But what should they include?
Install VCS
The very first thing your setup scripts should do is install (or verify the installation of) the VCS client you use. This will be used for all of the other steps that follow, primarily as a source for getting the scripts, code, and other files needed to do all of the other things. You may need multiple VCS clients if your product uses code from open source projects, or uses a CVCS for large binaries and DVCS for code.
Common build tools repository
A minimal setup script would just install the VCS and checkout the code for the product. A more complex one would checkout the common build tools, which includes a more complete dev machine setup script, that it would then run. This script could be run in existing dev machines to verify that everything needed is available, and to setup new tools as they become needed by product development. The build tools repository could also include any internal tools used across products, copies of external build tools that don’t require any installation, and meta-information about products and repositories.
Checkout source code
After getting the VCS client, the script should automatically checkout the source code. If you have one product that is contained in a single repository, that will make this easy. If, on the other hand, the are multiple products, lots of shared code, and developers only want to work on the subset of the code they’re assigned to, it makes sense to allow them to only checkout the code they care about.
Checkout any dependent source code
The build tools should have a way of defining dependencies between the repositories used to build your products, and use this knowledge to checkout any other code needed for builds to work without any additional setup by the developer.
Install all build tools and frameworks
And I mean all of them. Install compilers, frameworks, and everything else necessary to build. Install all of these tools at standard locations. As much as possible use silent installers that don’t require any interaction. If user interaction is required, run those installers first. Of course, you should only do this for tools that cannot be provided via your VCS.
Configure OS to make development possible/easy
If your build scripts require administrator access to run in non-interactive mode, turn off UAC on windows machines. If you need to make sure any OS features are installed (IIS, anyone?), make sure that happens also.
Setup any hard dependencies (environment, path, DBs, registry, etc.)
After getting the OS into the correct state, it’s time to take care of hard dependencies that your build scripts still need (you’ve tried to eliminate most of those, right?). Create databases, set registry values, add directories to the PATH, and set other environment variables. This is the time to do it all, and once it’s done, a new developer should be able to run any build script and have it succeed.
Convenience items
There are other things that your setup script can do that add convenience but aren’t required for building the product. For example, it could setup shared folders on the dev box, to make it easier to share files between developers. If there are dev tools that most developers at your organization use, but that aren’t required to build the code, it’s worth adding them as an optional item in the dev machine setup script. If pair programming is a key part of your culture, this may be more important, approaching the level of a requirement, a common machine setup that is interchangeable. Another useful addition would be setting up virtual machines that the developers can use for sandboxed testing.
To be complete, I’ll mention a couple things that would otherwise go without saying. This setup script should be smart about any of these steps that have already been done, and skip those steps both in order to run faster and also to avoid breaking something. Developers will want the ability to rerun this script when it changes, so it should work well in that case. If necessary, break it up into smaller, more focused scripts, or add command line parameters to do a subset of the work. As you create this script, start small, build incrementally. Trying to get every situation and configuration right the first time through is a sure path to never finishing it. But make sure that when you first release it to your team that it actually saves some work, at least enough to be worth the hassle of remembering to use the new tool. Once it’s available, the developers on your team will become contributors to this script.