Skip to main content

5 Rules to writing portable build scripts

Posted by johnsmart on October 15, 2009 at 3:58 PM PDT

A good build script should be self-contained, self-booting and portable. You should be able to check it out of source control and run it. No buts. Period. The rules (or tips) that follow should be self-evident and applied everywhere. Unfortunately, they are not. The following "rules" are based on issues I've encountered in existing real-world build scripts.

Rule 1 - No hard-coded paths. Hard-coded paths are the bane of the portable build script. Just say no.

Rule 2 - avoid OS-specific scripts. Avoid scripts in general for lifecycle-related tasks. If you must use scripts, make them portable (see Rule 1), for example by writing them in Groovy. But be careful: arbitrary scripts in build processes are things that have a high risk of becoming maintenance liabilities later on down the track.

Rule 3 - don't rely on custom tool installations. If you must install your own versions of tools for the build job, do it in a portable manner. Personnally, I'd rather make this declarative - the Maven Enforcer Plugin, for example, lets you do this. Or a Ant script that tests the version of Ant being run. I don't mind ensuring that Maven, Ant or Groovy are installed on a new build server - I'll even install multiple versions if you really need this. But don't use your own home-rolled tool installation scripts that don't work anywere other than the original machine they were written on!

Rule 4 - Don't home-role your dependency management solution. I've seen many places that use shared directories, or even just an arbitrary local directory, to store libraries. There are good existing solutions for this, such as Maven, Maven Ant Tasks and Ivy. Don't force newcomers to learn your home-rolled version from scatch when they join the maintenance team!

Rule 5- keep it simple and easy to understand.
That's what I dislike about Ant build scripts - they can so easily degenerate into uncontrollable monsters. But I've also seen build scripts that put layer upon layer of shell scripts before they get round to calling an Ant script! Build scripts are like code - if you want to be able to maintain it later on, you need to keep it tidy, find the simplest possible solution that works, and refactor from time to time.

Also, make it clear how it works and what it does. With Maven, the standard lifecycle makes it pretty clear how to compile, how to test, and how to package a project. This is generally not the case with other build scripts, where you need to study the script itself to understand how to compile the code. This should not be so. Ant, for example, supports target documentation - it's just that not a lot of people use it.

These are just a few rules that can help make your builds more portable and generally easier to maintain. There are of course plenty of others, and applying these rules does not mean you don't have to use your brain as well ;-).

Related Topics >>


where to store the passwords?

I agree we should avoi hard-coded paths, but then it come to my mind the very old question:

where to store the passwords?

In my scripts I decided to store it in ~/.passwords (with a similar path on windows)

other observations:

#2 - To write the scripts with Groovy is a good idea. I got "Groovyphobic" after one of my last projects in the office, but I should give it a second try some day... for now I continue using the very old shell script and bat files :)

#3 - my project depends on Glassfish and MySql.. I can use the script itself to install it, but it needs the admin password to work.. and I don't believe anyone in the world will trust on my script if it ask the guy "what is your computer master password?" :) But, yes, for some tools it should be ok.. specially the ones you can download and unpack without intrusive operationes on the OS. To test the versions and to abort in case of incompatibility is ok, but hard to maintain and eventually unecessary since the script will fail anyway (unelegant, but with the same result).

nice list, widely applicable

It's so easy for developers to write code that's specific to their own local development environment. This is a great list; also, well ordered (I don't know how many times I've said "no hard-coded paths" to junior developers in my career!).