Java – Build and Version Numbering for Java Projects (ant, cvs, hudson)

buildbuild-processjavaversioning

What are current best-practices for systematic build numbering and version number management in Java projects? Specifically:

How to manage build numbers systematically in a distributed development environment
How to maintain version numbers in source / available to the runtime application
How to properly integrate with source repository
How to more automatically manage version numbers vs. repository tags
How to integrate with continuous build infrastructure

There are quite a number of tools available, and ant (the build system we're using) has a task that will maintain a build number, but it's not clear how to manage this with multiple, concurrent developers using CVS, svn, or similar.

[EDIT]

Several good and helpful partial or specific answers have appeared below, so I'll summarize a few of them. It sounds to me like there is not really a strong "best practice" on this, rather a collection of overlapping ideas. Below, find my summaries and some resulting questions that folks might try to answer as follow-ups. [New to stackoverflow… please provide comments if I'm doing this wrong.]

If you are using SVN, versioning of a specific checkout comes along for the ride. Build numbering can exploit this to create a unique build number that identifies the specific checkout/revision. [CVS, which we are using for legacy reasons, doesn't provide quite this level of insight… manual intervention with tags gets you part way there.]
If you are using maven as your build system, there is support for producing a version number from the SCM, as well as a release module for automatically producing releases. [We can't use maven, for a variety of reasons, but this helps those who can. [Thanks to marcelo-morales]]
If you are using ant as your build system, the following task description can help produce a Java .properties file capturing build information, which can then be folded into your build in a number of ways. [We expanded on this idea to include hudson-derived information, thanks marty-lamb].
Ant and maven (and hudson and cruise control) provide easy means for getting build numbers into a .properties file, or into a .txt/.html file. Is this "safe" enough to keep it from being tampered with intentionally or accidentally? Is it better to compile it into a "versioning" class at build time?
Assertion: Build numbering should be defined/enacted in a continuous integration system like hudson. [Thanks to marcelo-morales] We have taken this suggestion, but it does crack open the release engineering question: How does a release happen? Are there multiple buildnumbers in a release? Is there a meaningful relationship between buildnumbers from differing releases?
Question: What is the objective behind a build number? Is it used for QA? How? Is it used primarily by developers to disambiguate between multiple builds during development, or more for QA to determine what build an end-user got? If the goal is reproducibility, in theory this is what a release version number should provide — why doesn't it? (please answer this as a part of your answers below, it will help illuminate the choices you have made/suggested…)
Question: Is there a place for build numbers in manual builds? Is this so problematic that EVERYONE should be using a CI solution?
Question: Should build numbers be checked in to the SCM? If the goal is reliably and unambiguously identifying a particular build, how to cope with a variety of continuous or manual build systems that may crash/restart/etc…
Question: Should a build number be short and sweet (i.e., monotonically increasing integer) so that it's easy to stick into file names for archival, easy to refer to in communication, etc… or should it be long and full of usernames, datestamps, machine names, etc?
Question: Please provide details about how the assignment of build numbers fits into your larger automated release process. Yes, maven lovers, we know this is done and done, but not all of us have drunk the kool-aid quite yet…

I'd really like to flesh this out into a complete answer, at least for the concrete example of our cvs/ant/hudson setup, so someone could build a complete strategy based on this question. I'll mark as "The Answer" anyone who can give a soup-to-nuts description for this particular case (including cvs tagging scheme, relevant CI config items, and release procedure that folds the build number into the release such that it's programmatically accessible.) If you want to ask/answer for another particular configuration (say, svn/maven/cruise control) I'll link to the question from here. –JA

[EDIT 23 Oct 09]
I accepted the top-voted answer because I think it's a reasonable solution, while several of the other answers also include good ideas. If someone wants to take a crack at synthesizing some of these with marty-lamb's, I'll consider accepting a different one. The only concern I have with marty-lamb's is that it doesn't produce a reliably serialized build number — it depends on a local clock at the builder's system to provide unambiguous build numbers, which isn't great.

[Edit Jul 10]

We now include a class like the below. This allows the version numbers to be compiled into the final executable. Different forms of the version info are emitted in logging data, long-term archived output products, and used to trace our (sometimes years-later) analysis of output products to a specific build.

public final class AppVersion
{
   // SVN should fill this out with the latest tag when it's checked out.

   private static final String APP_SVNURL_RAW = 
     "$HeadURL: svn+ssh://user@host/svnroot/app/trunk/src/AppVersion.java $";
   private static final String APP_SVN_REVISION_RAW = "$Revision: 325 $";  

   private static final Pattern SVNBRANCH_PAT = 
     Pattern.compile("(branches|trunk|releases)\\/([\\w\\.\\-]+)\\/.*");
   private static final String APP_SVNTAIL = 
     APP_SVNURL_RAW.replaceFirst(".*\\/svnroot\\/app\\/", "");

  private static final String APP_BRANCHTAG;
  private static final String APP_BRANCHTAG_NAME;
  private static final String APP_SVNREVISION = 
    APP_SVN_REVISION_RAW.replaceAll("\\$Revision:\\s*","").replaceAll("\\s*\\$", "");


  static {
    Matcher m = SVNBRANCH_PAT.matcher(APP_SVNTAIL);
    if (!m.matches()) {
      APP_BRANCHTAG = "[Broken SVN Info]";
      APP_BRANCHTAG_NAME = "[Broken SVN Info]";
    } else {
      APP_BRANCHTAG = m.group(1);
      if (APP_BRANCHTAG.equals("trunk")) {
        // this isn't necessary in this SO example, but it 
        // is since we don't call it trunk in the real case
        APP_BRANCHTAG_NAME = "trunk";
      } else {
        APP_BRANCHTAG_NAME = m.group(2);
      }
    }
  }

  public static String tagOrBranchName()
  { return APP_BRANCHTAG_NAME; }

  /** Answers a formatter String descriptor for the app version.
   * @return version string */
  public static String longStringVersion()
  { return "app "+tagOrBranchName()+" ("+
    tagOrBranchName()+", svn revision="+svnRevision()+")"; }

  public static String shortStringVersion()
  { return tagOrBranchName(); }

  public static String svnVersion()
  { return APP_SVNURL_RAW; }

  public static String svnRevision()
  { return APP_SVNREVISION; }

  public static String svnBranchId()
  { return APP_BRANCHTAG + "/" + APP_BRANCHTAG_NAME; } 

  public static final String banner()
  {
    StringBuilder sb = new StringBuilder();
    sb.append("\n----------------------------------------------------------------");
    sb.append("\nApplication -- ");
    sb.append(longStringVersion());
    sb.append("\n----------------------------------------------------------------\n");
    return sb.toString();
  }
}

Leave comments if this deserves to become a wiki discussion.

Best Answer

For several of my projects I capture the subversion revision number, time, user who ran the build, and some system information, stuff them into a .properties file that gets included in the application jar, and read that jar at runtime.

The ant code looks like this:

<!-- software revision number -->
<property name="version" value="1.23"/>

<target name="buildinfo">
    <tstamp>
        <format property="builtat" pattern="MM/dd/yyyy hh:mm aa" timezone="America/New_York"/>
    </tstamp>        
    <exec executable="svnversion" outputproperty="svnversion"/>
    <exec executable="whoami" outputproperty="whoami"/>
    <exec executable="uname" outputproperty="buildsystem"><arg value="-a"/></exec>

    <propertyfile file="path/to/project.properties"
        comment="This file is automatically generated - DO NOT EDIT">        
        <entry key="buildtime" value="${builtat}"/>
        <entry key="build" value="${svnversion}"/>
        <entry key="builder" value="${whoami}"/>
        <entry key="version" value="${version}"/>
        <entry key="system" value="${buildsystem}"/>
    </propertyfile>
</target>

It's simple to extend this to include whatever information you might want to add.

Related Solutions

Javascript – How to force clients to refresh JavaScript files

As far as I know a common solution is to add a ?<version> to the script's src link.

For instance:

<script type="text/javascript" src="myfile.js?1500"></script>

I assume at this point that there isn't a better way than find-replace to increment these "version numbers" in all of the script tags?

You might have a version control system do that for you? Most version control systems have a way to automatically inject the revision number on check-in for instance.

It would look something like this:

<script type="text/javascript" src="myfile.js?$$REVISION$$"></script>

Of course, there are always better solutions like this one.

Java – Access Java class public member variable from Ant and use it in a build task

I don't think there are any built in Ant tasks that do what you want. However, you could roll your own, taking advantage of the extensible nature of Ant.

I've hacked up a really (and I do mean really) dirty example you can use as a spring board to a proper Task.

package q1015732;

import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;
import java.lang.reflect.Field;

import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;

/**
 * Custom ant task that binds a property name to a static member of a class file.
 * 
 * @author Montrose
 */
public class BindPropertyTask extends Task{
    private String _classFile = null;
    private String _fieldName = null;
    private String _propName = null;

    /**
     * Set the field name of the class.
     * 
     * @param fieldName
     */
    public void setFieldName(String fieldName){
        _fieldName = fieldName;
    }

    /**
     * The class file.
     * @param classFile
     */
    public void setClassFile(String classFile){
        _classFile = classFile;
    }

    /**
     * The property name to bind
     * @param propName
     */
    public void setProperty(String propName)
    {
        _propName = propName;
    }

    /**
     * Load the class file, and grab the value of the field.
     * 
     * Throws exceptions if classfile, fieldname, or property have not been set.
     * 
     * Throws more execeptions if classfile does not exist, the field does not exist, or the field is not static.
     */
    public void execute() throws BuildException{
        if(_classFile == null) throw new BuildException("ClassFile is a required attribute");
        if(_fieldName == null) throw new BuildException("FieldName is a required attribute");
        if(_propName == null)  throw new BuildException("Property is  required attribute");

        CustomLoader loader = new CustomLoader();
        Class toInspect = null;
        Field toBind = null;
        Object value = null;

        try {
            toInspect = loader.loadClass(new FileInputStream(_classFile));
        } catch (Exception e) {
            throw new BuildException("Couldn't load class ["+e.getMessage()+"], in ["+(new File(_classFile).getAbsolutePath())+"]");
        }

        try{
            toBind = toInspect.getField(_fieldName);
        }catch(NoSuchFieldException e){
            throw new BuildException("Couldn't find field, '"+_fieldName+"'");
        }

        //Let us bind to private/protected/package-private fields
        toBind.setAccessible(true);

        try{
            value = toBind.get(null);
        }catch(NullPointerException e){
            throw new BuildException("Field is not static");
        } catch (Exception e) {
            throw new BuildException("Unable to access field ["+e.getMessage()+"]");
        }

        if(value != null)
            this.getProject().setProperty(_propName, value.toString());
        else
            this.getProject().setProperty(_propName, null);
    }

    /**
     * Custom class loader, for loading a class directly from a file.
     * 
     * This is hacky and relies on deprecated methods, be wary.
     * 
     * @author Montrose
     */
    class CustomLoader extends ClassLoader{
        public CustomLoader(){
            super(ClassLoader.getSystemClassLoader());
        }

        /**
         * Warning, here be (deprecated) dragons.
         * @param in
         * @return
         * @throws Exception
         */
        @SuppressWarnings("deprecation")
        public Class loadClass(InputStream in) throws Exception{
            byte[] classData = loadData(in);
            return this.defineClass(classData, 0, classData.length);
        }

        private byte[] loadData(InputStream in) throws Exception{
            byte[] buffer = new byte[1024];
            ByteArrayOutputStream out = new ByteArrayOutputStream();
            int i;


            while((i = in.read(buffer)) != -1){
                out.write(buffer, 0, i);
            }

            return out.toByteArray();
        }
    }
}

An example build file using this task:

<project name="q1015732">

<target name="test">
<taskdef name="static_bind" classname="q1015732.BindPropertyTask" />

<static_bind fieldname="StringBind" classfile="C:\Users\Montrose\workspace\StackOverflow Questions\q1015732\test\DummyMain.class" property="string.value" />
<static_bind fieldname="IntBind"    classfile="C:\Users\Montrose\workspace\StackOverflow Questions\q1015732\test\DummyMain.class" property="int.value" />
<static_bind fieldname="DoubleBind" classfile="C:\Users\Montrose\workspace\StackOverflow Questions\q1015732\test\DummyMain.class" property="double.value" />

<echo message="StringBind: ${string.value}" />
<echo message="IntBind:    ${int.value}" />
<echo message="DoubleBind: ${double.value}" />

</target>

</project>

DummyMain.java:

package q1015732.test;

public class DummyMain {
    public static String StringBind = "I'm a String!";
    public static int    IntBind    = 1024;
    public static double DoubleBind = 3.14159;
}

The result of a build using the Ant file:

test:
[echo] StringBind: I'm a String!
[echo] IntBind: 1024
[echo] DoubleBind: 3.14159
BUILD SUCCESSFUL

There are a number of random problems with this task: it relies on deprecated methods, it takes files instead of class names, and the error reporting leaves a bit to be desired. However, you should get the gist of what is needed for a custom task that solves your problem.

Best Answer

Related Solutions

Javascript – How to force clients to refresh JavaScript files

Java – Access Java class public member variable from Ant and use it in a build task

Related Topic