John is an experienced consultant specialising in Enterprise Java, Web Development, and Open Source technologies, currently based in Sydney, Australia. Well known in the Java community for his many published articles, and as author of Java Power Tools and Jenkins: The Definitive Guide, and founder of the open source Thucydides Automated Acceptance Test Library project, John helps organisations to optimize their Java development processes and infrastructures and provides training and mentoring in agile development, automated testing practices, continuous integration and delivery, and open source technologies in general. John is the CEO of Wakaleo Consulting, and runs several Training Courses on open source Java development tools and best practices. John is a DZone MVB and is not an employee of DZone and has posted 125 posts at DZone. You can read more from them at their website. View Full User Profile

5 Rules to Writing Portable Build Scripts

  • submit to reddit

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 ;-).


Your rating: None Average: 3 (4 votes)
Published at DZone with permission of John Ferguson Smart, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)


Gagandeep Singh replied on Tue, 2009/10/20 - 3:13am

I hope people read this post and follow what you have said. Home rolled solutions have made life hell for many like me on more than one occasion.

Ingo Richter replied on Thu, 2009/11/19 - 5:56am

Hi John,

Great post about portable build scripts. This really should help a lot of people to get it right the first time.

What we did for our build environment was to check in every needed resource into our VCS to make it really easy for everyone on the team to get the stuff working on their machine. This was 10 years ago. But I'm still puzzled by the question how to satisfy the minimum requirement of installed tools on every developer machine? The first incarnation of this build ecosystem required only java. The JDK/JRE was available in the VCS and the everything was fine after syncing the whole stuff. But the current requirement is to have Python, Java, maven, Flex and Visual Studio/XCode installed. The bootstrapping is much more time intense for this kind of system setup. I haven't find a simple solution to this yet. But the hurdle seems to be too high for a lot of peopleon the team and they are reluctant to do all the necessary steps to get the minimal required set of tools installed on their machine. I was already thinking of creating a "simple" installer to get all the pieces onto the machine in very convinient manner. But there is not enough time (as usual). So I'm still figuring out what to do for such a system. I'd like to get back easy bootstrap process where everything is checked into the VCS. That was so easy and beautiful. But I consider this no longer an option. Having a mechanism to download all the requirements onto the machine would be a great timesaver and pain reliever.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.