In the course of helping a client look for tools to support their development process I recalled that a couple of years ago I looked briefly at JIRA when building a change control system for another client. So, I suggested we look at JIRA as a possible tool for this new system.

Having looked around the JIRA site I noticed that Atlassian had also taken FishEye (a tool I had used before for providing viewing and analysis tools on repositories) into their stable. And they also support a whole suite of integrated tools that can be used individually or together.

I suggested we take a closer look. So, we set about creating a very simple demonstration of the tools.

I have to say, ‘I’m impressed’.

These are great looking, well integrated, easy to use, easy to set up and very competitively priced tools. Based on a couple of months playing around with them, I’d have absolutely no difficulty recommending them to organisations of almost any size—certainly they should be on your list of tools to look at.

Not only are the tools themselves very flexible and easy to configure but the company seems very keen to hear from their customers. They have open beta programmes and actively encourage users to take part in product development (they really do want to know what their customers want). They also provide really low cost licenses; up to 90 days evaluation licenses and then for small teams (or individuals) they offer 10 user licenses for $10. Seriously! This is a brilliant move. It means freelance consultants (such as your’s truly) can actually use their tools and develop for them, without needing to remortgage the house to obtain licenses. (The tools also don’t require a massive hardware commitment—in fact I’m running a system on a Linux virtual machine on my Mac Pro  and it works great for development and creating documentation/training material.)

Oh, and if you’re a non-profit or open source organisation they will let you have unlimited licenses for free! Genius.

Can’t be bothered with all that setup? Atlassian offer a hosted solution for many of their tools too. (Although I can’t comment on these as I have not tried them, but if they’re anything like as good as what I have seen so far, they’re probably worth looking at if you want a hosted solution.)

The price apart, the tools really are very good. And if they don’t do exactly what you want you can always write your own extensions. Atlassian publish comprehensive developer information and the tools all communicate through open web interfaces and all support a plugin architecture (which I understand Atlassian are working hard to make simpler to use).

Another promising sign is that Atlassian ‘eat their own dog food’. They user all their own tools internally and pride themselves on being the guinea pigs for all their product development. Their own website and online documentation is all run through their own products.

Even better! Atlassian let their product speak for itself. No annoying salespeople calling, no pressure to come along and ‘do a demo’. They just provide you with a really simple way to download their product, get an evaluation license, and then let the product do the selling (no kidding I had downloaded, installed and licensed JIRA in about ten minutes—it took about a day to install, license and integrate the entire suite). Brilliant! [Note to all vendors: if you're product is good then let it speak for you. If you're product needs to be explained, then make it better, provide good online documentation, and provide help when it's requested. I understand that some customer like a demo, but many just want to try out your product for themselves. After all, if it can't be setup and used by their own staff, what hope is there for the future? They just end up being highly dependent on your consulting services. Oh. I think I get it now.]

If, as seems likely, the client goes ahead with this solution I’ll be sure to report back on how these products perform under real life conditions, but for now, go take a look.

One often sees, in ANT scripts, something like this at the head of the build.xml file.

<project name="myproj">
    <property name="buildroot.dir" location="${basedir}/.."/>
    <property name="source.dir" location="${buildroot.dir}/src"/>
    <property name="bin.dir" location="${buildroot.dir}/bin"/>

    <property name="bld.package" value="true">

So far, so good. The author of this ANT script has thought to define properties that control the script’s behaviour at the start of the script. This means that, should circumstances change, it is relatively easy to change the script’s behaviour. So, should it be decided that the bin directory should be moved to another location, we simply change the definition of the bin.dir property and no other changes are necessary in the script.

Another, not so obvious, advantage of this approach is that these properties can be easily changed by defining the properties outside the script (passed on the command line, e.g. ant -Dbin.dir=special/bin or by some client script, e.g. a call from CruiseControl), either way, the property defined will not be overridden by the script because <property> never redefines a property once it is set. Neat.

The problem with putting properties in the build.xml file itself makes them more difficult to access from other ANT scripts.

Suppose I have another ANT script that I want to interact with the same build system. I want to ensure that the script can pick up the configuration information (things like the directories the build system is using or settings that dictate build behaviour like the bld.package property). If these are defined in the build.xml then accessing them is tricky. If, however, they are defined in their own file I can simply load that ‘configuration’ file separate to the build.xml but be confident that the settings are the same as were used by the build itself.

There are two approaches to isolating configuration from the scripts that use them; use another ANT file and <include> or <import> it, or I can use a property file, e.g. build.properies and <property file="build.properties"> or <loadproperties srcfile="build.properties"> it into a script. The approach you take will depend upon the sort of information you want in your configuration, where you are likely to use it, and how much flexibility you need.

Personally I prefer <loadproperties srcfile="build.properties"> for most purposes and I use <include> as a wrapper when I need special configuration that is not accessible through the more direct build.properies format.

So, I might have the following in my main build.xml.

<project name="myproj">
    <include file="config.xml"/>

And then, in the config.xml I might have the following.

<project name="myproj.config">
    <loadproperties srcfile="build.properties"/>

    <defaultexcludes add="**/*.bak">
</project>

The defaultexcludes would me more difficult to set using a properties file, so I use the config.xml here. I am using <loadproperties> here, but could have used <properties file="">. <loadproperties> provides some extra flexibility because it supports filterchains, but that’s a topic for another post. I just feel that <loadproperties> describes better what the script is doing, but as I say, in this case, it’s a matter of personal preference.

And finally, in the build.properties I might have the following.

buildroot.dir=${basedir}/..
source.dir=${buildroot.dir}/src
bin.dir=${buildroot.dir}/bin

bld.package=true

Now the build.properties are available in a simple form to be loaded into any script that needs this project’s main configuration. The config.xml provides additional configuration that I may want to load but is not available in the property file format, and is often not relevant to basic configuration information such as locations. I can also use the config.xml to perform more advanced scripting of configuration if needed.

I find that this approach of breaking out configuration into separate files according to both its function and how I think it will be accessed has saved me a lot of work over the years. It also disciplines me into thinking about how my builds should be configured and encourages me to keep all the configuration information in one place (if I find myself tempted to use a <property> to define a location or simple string in my main build.xml I ask myself, would this be better in the build.properties? It generally is.)

Keeping configuration separate also makes the main build.xml much easier to reuse. Just copy the build system into the new project, change the build.properties and, assuming you’ve written your build.xml well, everything should work without further change.

Let’s put this into concrete terms.

Suppose the original change request is something like, “correct the spelling mistakes in the poem” and the poem is held in two files.

file1.txt contains the following text.

Mary hard a litl lamb,
It's fles was wite as snow,

And file2.txt contains the following text.

And everywere that Mary went,
That lam was sure to go.

We correct these two file to the following using a change record CR1.

Mary hard a little lamb.
It's fleece was white as snow

And everywhere that Mary went,
That lamb was sure to go.

Here then is my first build (build1).

Initial build: conceptual and literal change equivalent

So, not bad, but the still have “hard” instead of “had” in the first line of file1.txt. This does not change the integrity of build1, but does make another build (build2) necessary to include a correction to the erroneous work submitted into build1.

There are different ways we might choose to track the correction of the defect arising from build1.

Each approach has its own merits but, from the perspective of build integrity, they share an the important feature; when dealing with the conceptual change “correct the spelling mistakes in the poem”, they are semantically equivalent. For build2 to have integrity it must include both the revisions associated with the original change and all new revisions associated with the correction to the change, regardless of how that correction is controlled.

We correct the defect in build1 with an additional change to file1.txt to produce the following.

Mary had a little lamb,
It's fleece was white as snow,

The following illustration shows build2 (in this case I have re-used CR1 to correct the defect). I should be obvious that missing any revision associated with CR1 has the potential to break the build’s integrity (we may have only part of CR1 in the build).

Fix Build: Conceptual change implemented with reworked literal change

Fix build: Conceptual change now implemented with two literal changes

And this is the point. Yes, the literal changes CR1 and D1 are, in one sense, changes. In practical terms though each on its own fails to achieve the objective of the original change request and consequently they are little more than sets of revisions. The two literal changes controlled by records CR1 and D1, taken together, achieve the original goal of the change request “correct spelling mistakes in the poem”. It is this latter type of change (what I have called conceptual change) that is more interesting to configuration management and build integrity is maintained through these conceptual changes rather than the less significant literal changes.

This distinction between the conceptual change and literal change becomes increasingly important as we consider configuration integrity, a subject I shall discuss in more detail in subsequent posts.

Stubs come in several flavours:

• non-functional stubs provide no functionality, they simply provide a template interface to allow client sub-systems to compile;
• static-function stubs allow client sub-systems to compile and also provide static responses when the interface is called;
• dynamic stubs provide more complex responses when called. Methods used to provide these dynamic stubs vary but some common approaches are:
  • record and playback,
  • static tables,
  • randomised response, and
  • minimal function.

A stub is a proxy for the final functionality to be offered by the sub-system. As such we want the stub references in the client code to use the same calling convention as the final product. In the build process we need some means to nominate the stub or the final product into our build.

There are two principal approaches to solving this latter problem. The first relies on the build itself to select the appropriate module (stub or final). In our build script we may have, for example, a simple path modifier that builds either the stub or final code into a library which is then used by clients. The second method relies upon the source control system to deliver either the stub or final source into the source configuration, this source is then built into the target library. In this post I begin looking at some of the issues involved in both build and configuration managing stubs.

Although the second approach has some appeal, the first offers more flexibility. Suppose We have module A that is to supply some functionality to a client system S. The normal build chain would be something like A-Ao-L-S (source A built to object Ao which is linked into a library L¹ and consumed by system S).

Simplified Build Chain

If we supply a stub A’ the chain becomes A’-Ao’-L-S.

Stub Build Chain

The L-S relationship remains the same whether we elect to build the stub or final product into system S. So far, so good. Our build system simply nominates the appropriate build into library L (A’-Ao’ or A-Ao). This allows us to build the entire system with or without the stub code in place.

Stub Variant Build Chains

Suppose the problem where a little more complex. Suppose that instead of L being used universally in S there were an intermediate set of sub-systems (S’ and S”). Now our build chain is: A-Ao-L-(S’|S”)-S

Build Chain with Intermediate Sub-systems

What if developers of S’ wish to use the stub code and S” wish to use the final code for testing? The build system that nominates Ao or Ao’ into L is not sufficient to accommodate this requirement. We need to add another step and provide a means to nominate the appropriate library.

Using Stub Libraries

But this opens up another problem. The libraries L and L’ currently contain either stub code or final code, but the sub-systems S’ and S” may each require different component to be stubbed out at different times and this will lead to a profusion of libraries, each with a unique combination of stubbed modules.

One we reach this situation we need to query our library architecture and our testing approach. There is no universal approach to building systems using arbitrary set of stubs like this. We could use some run-time configuration but this opens up a whole new set of issues around configuration management and ensuring delivered systems do not contain inappropriate stub code.

This post has offered a very light-weight introduction to build management of stubs. This is, of course, a large a complex issue for configuration management. The take-home message should be, make sure you design your build system with stubbing in mind and work with system architects, test managers and developers to ensure that your build system can accommodate appropriate configurations for stubbed testing.

Various solutions have been proposed to this conundrum, most of which involve tracking the complex relationships between source and derived objects. In recent years another somewhat simpler solution has presented itself. Instead of controlling all of the precondition factors individually, create one controlled environment and reuse this for each build. The potential flaw in this approach is that running a build will more often than not change the environment, and reconstructing the build environment is often difficult, time consuming and prone to error.

Virtual environments provide a perfect solution. Construct the build environment once as a virtual machine environment and then each build starts by restoring the virtual environment back to the initial condition. Source code (including the build scripts that direct the build) is stored in a separate repository and extracted to the build environment as normal. Derived objects (produced during a build) are held separate to the build environment so that they are not reset during the build.

There remains one potential problem when performing incremental builds. If your build relies on changes to the build environment to function properly, these changes will be discarded when the build environment is restored to its initial state. If, for example, your build registers objects with the Windows registry during the build, these items will not be registered at the start of the build so your build must be written to ensure these environmental changes are repeated even when the items themselves are not rebuilt.