Ant Build Templates: Why Two Files?

This is the fourth in a series of posts meant to outline my Ant build script template. If you’re interested, it may be helpful to read the first three:

  1. Prelude
  2. Environment
  3. Process

If you’ve been reading this series (or any of my other Ant-related content), you may have noticed that I occasionally reference my build scripts. Plural. It’s kind of involuntary, but you may have wondered exactly how many there are. Although there’s really only one build script (per project), I have, and recommend to anyone else, an accompanying properties file. Two files that I occasionally, and inconsistently, mind you, lump together into a plural use of the word “script”.

So there it is. Two files. One is the actual Ant build script, traditionally build.xml and the other, build.properties, an external set of property definitions. I do this for exactly the same reason that I – and most other developers I know – maintain a configuration file of some sort for my applications; it’s nice to know where to go when something needs to be changed. Moreover, it’s nice to know that it’s the only place that those changes need to be made.

Build operations, especially when deployment is part of that build operation, typically require an awful lot of information – file paths, for example – about the build or deployment environments, information – think usernames – about the user running the build, sensitive information like authentication credentials or simply information about the build itself. The latter might include the project name and version or the source control revision number.

All of this information is usually, or at least could be, variable. I deploy to multiple environments and I’m not the only person in my group that can run builds. Additionally, I want developers themselves to test their own build scripts. Finally, I want build scripts to be versioned and I sure as hell don’t want to be dropping my authentication credentials into a build file and then committing those credentials to a revision all their own until the end of days. That would be bad.

Given all of this variable and/or sensitive information, I could still just throw everything directly in the build script. I have to manage and update it no matter where it goes, so the where doesn’t really matter. Um, in theory. Maybe it’ll be easier to understand when you see the file, but the build script (build.xml is much more verbose. There’s a lot of stuff going on in there. Remembering what needs to change, finding it and then changing it isn’t a trivial effort and it would have to be done for every build. No thanks.

Instead, I move the variable data out to build.properties. In addition, I store a generic version named build.properties.sample in source control. That generic version contains dummy values for most of the properties. I copy that file to build.properties in my working copy, set my source control configuration to ignore the copied file and then I can merrily go about including sensitive data without fear of an accidental commit. There are also other benefits to having a separate properties file:

  1. It contains nothing but variable values. If a property is in this file then it either is or could be variable. There’s no other stuff to wade through.
  2. Likewise, the build script itself is fixed. Nothing in there should need to be changed (unless, of course, the fundamental nature of the build changes).
  3. It’s much, much smaller than the executable script so specific properties can be found much quicker that they would be in the larger build script.
  4. Specific properties will only exist once in the properties file. They may be used any number of times in the script itself.
  5. Risk mitigation. At build time, I don’t have to touch the executable that’s actually doing all of the work. All I have to do is update the properties file and run the build.

The moral of the story: use a properties file. You’ll be glad you did. Your sanity is important so preserve it. In this case, less is not more. Two is better than one.

Subscribe4 Comments on Ant Build Templates: Why Two Files?

  1. Julian Simpson said...

    Right on. I think of it like string literals in code; your build.properties file is really runtime configuration for your build. It tends to lead to flexible builds as you can drop in a new config file. Nice post!

  2. Rob Wilkerson said...

    The perfect analogy. Thanks, Julian. Having a separate properties file is useful when I’m running my own builds, but it’s been invaluable when running the builds of other developers where I’m less familiar with the details project and its code. The separate build file very precisely specifies what I need to change before the build can be run successfully. I never have to touch the build script itself.

  3. Jim Priest said...

    I’ve got several property files and have been thinking of condensing them down…

    build.properties – generic stuff related to project
    ${server}.properties – info related to each server we deploy to
    ${user}.properties – info specific to my local machine
    auth.properties – username/passwords

    But I’ve also seen single property files that are difficult to wade through.

  4. Rob Wilkerson said...

    @jim –

    Yeah, for my needs 1 is sufficient if it’s organized decently. Any more than that just feels cumbersome. If I had more “sections”, I might break them down into separate files, but I find one just works better for me and is easier to keep up with.