• Subversion Best Practices

    Product:
    Subversion 1.4.x

    Component:

    Summary:

    This article provides example business use-cases to explain why you may want to use Subversion in your Ant build process and show you how to integrate Subversion into your Ant build process.



     

    Integrating Subversion into your Ant Build

    I have used Subversion and Ant for a number of years. When I worked for a previous employer, we had a few situations where we needed to interact with Subversion or get information from Subversion as part of our build cycle. Because our build cycle was used for release management and continuous integration, there were a number of places where we needed this information.

    In the beginning, there was no known way to do this, so we wrote our own scripts to call the Subversion command-line client and parse the output. Eventually I stumbled upon SVNAnt, which made integration Subversion into our Ant build process much easier.

    Before we get into examples and real-world scenarios that would merit integration Subversion into your Ant build cycle, let’s look at:

    • What SVNAnt is
    • What SVNAnt provides
    • How to install SVNAnt

    SVNAnt Use Cases

    SVNAnt is just a vessel you use to get Subversion information and to perform Subversion commands during your Ant build cycle. The following examples are use cases that I experienced during previous employment and in my open source development.

    Continuous Integration

    Continuous Integration (CI) is a multi-step process that usually involved building your application from the latest and greatest, performing some tests, documenting the results, and then alerting your team of the outcome. The key part of that sentence for this article is build. In many CI processes, your build tooling is responsible for facilitating the CI steps listed above. Without diving too deep into CI, here are the steps that usually occur during CI:

    1. Checkout the latest sources.
    2. Compile the main sources.
    3. Compile the test sources.
    4. Run your tests.
    5. Report on your test results.
    6. Report on any other things like code coverage.
    7. Tag the integration build.
    8. Publish build artifacts.
    9. Cleanup.

    Now I understand that these steps may differ and are probably very minimal, but that isn't the point. The point is to look at steps one, six, and seven. These three CI steps are all places where you need to interact with Subversion to facilitate the CI step properly. With SVNAnt, these steps are performed with ease. Without SVNAnt, you usually have to either write your own Ant tasks or have Ant call some external application and parse the data for use during the CI process.

    Let’s look at how Subversion could be used as part of the above CI process:

    1. Checkout the code (No other way to do this without Subversion interaction).
    2. Get repository information and set to Ant properties for use during documentation creation and artifact naming.
    3. Create a tag of the successful build with a name understandable via visual examination.
    4. Possibly commit some of the build artifacts.
    5. Optionally, set a property on some of the Subversion files/directories based on project needs.

    Continuous Integration is a perfect example as to why you need to interact with Subversion during your Ant build cycle. Without interacting with Subversion, it might be difficult to create a tag with your revision number in the tag name (which is usually done to create a tag that can be fully understood from ad-hoc examination). What about publishing your web application to your application server with a name that can be identified by visual examination of the war name? Yet another reason that Subversion interaction via SVNAnt makes your CI process more possible.

    Release Management

    Release Management is another place where Subversion interaction during the Ant build cycle was required. At one of my previous employers, we "cut a release" via Ant. As part of this release, we:

    • Built release documentation
    • Tagged our binaries with pertinent revision information from Subversion
    • Built release reports based on Subversion properties and log information
    • Set a property on the release tag with release information.

    None of this is possible within your Ant build cycle without Subversion interaction.

    There are many other ways that SVNAnt, as part of your Ant build cycle, provides useful--and in many times necessary--access to Subversion. Continuous Integration and Release Management are just two most common use cases that I ran into in many projects.

    What is SVNAnt?

    SVNAnt is an Ant task allowing you to interact with Subversion within the convenience of your Ant build script. No more writing custom scripts to get the revision of your repository to tag your release jars. Nor do you have to make command-line calls to checkout your latest and greatest as part of your continuous integration process. With SVNAnt, you have the familiarity of the Ant syntax and the flexibility you need for interacting with Subversion.

    Features

    SVNAnt is a full-featured Subversion client capable of using the native Java bindings or command-line wrappering, depending on which is available. Beyond how it works, SVNAnt allows you to use all svn subcommands on all but the following:

    blame cleanup help list
    lock log merge propedit
    proplist resolved unlocked  

    If the svn subcommand is not listed here, you can use it in your Ant build file. Before you start using SVNAnt, you have to install it and configure Ant to use it.

    Installation

    Now that you know what SVNAnt is and what its features are, the next step is to install SVNAnt so that you can begin to use SVNAnt to access Subversion within your Ant build cycle.

    Step 1. Download, compile, and extract
    This step downloads, compiles, and "installs" the latest version of SVNAnt.

    1.1 Using Subversion, checkout the SVNAnt project:
    http://subclipse.tigris.org/svn/subclipse/trunk/svnant

    1.2 From the command line, while inside the location where you checked out SVNAnt to, run "ant makeDistrib"1.3 Extract the .zip file created in the build directory of your SVNAnt source to a location of your choosing.

    Step 2. Modify your build.xml
    Tell Ant how to find your SVNAnt task by adding the following to your build.xml file:

    <path id= "svnant.classpath" >
    <fileset dir= "/PATH/TO/YOUR/EXTRACTED/SVNANT-ZIP" >
    	<include name= "*.jar" />
    </fileset>
    </path>
    <typedef resource="org/tigris/subversion/svnant/svnantlib.xml" classpathref="svnant.classpath" /> 
    

    That should be it. I know that it appears to be too good to be true, so let’s verify this.

    Step 3. Verify installation
    Building on Step 2, create a new Ant task that uses the wcVersion feature of SVNAnt to get some information about your repository from a local working copy:

    <target name="testSVNAnt">
         <svn>
             <wcVersion path= "PATH/TO/YOUR/WORKINGCOPY" />
         </svn>
    
         <echo message= "Subversion repository url: ${repository.url}" />
    </target>
    

    (Note: In the event that you need to pass credentials to Subversion, look here.)

    The output should be similar to this:

    $ ant testSVNAnt
    
    Buildfile: build.xml
    
    testSVNAnt:
          [svn]  started ...
          [svn]  finished.
          [echo] Subversion repository url: http://svn.apache.org/repos/asf/incubator/openejb/trunk
    
    BUILD SUCCESSFUL
    Total time: 43 seconds
    	

    Pat yourself on the back. You have successfully installed SVNAnt and are ready to implement Subversion into your Ant build cycle. For more information about the available features for SVNAnt, see the SVNAnt Documentation.

    Summary

    This concludes this article on integrating Subversion into your Ant build cycle. You saw two use cases for using Subversion in your Ant build cycle. You even installed SVNAnt and verified it works. The rest is up to you. Your next steps should be to review the SVNAnt documentation referenced in the Resources section and build upon what you've learned today.

    I hope this article brings SVNAnt to those of you using Ant but doing Subversion interaction the hard way. For those of you already using SVNAnt, I hope that this article backs up your usage and possibly gives you a few ideas for SVNAnt use in the future.

    Resources

    The following are resources used during this article:

      Resource       Description  
     
      Article with Source and SVNAnt binary       Single download with article HTML, sample Ant build.xml and an SVNAnt binary built from the trunk. Download, extract and run  
     
      Ant       Multi-platform and multi-language build tool  
     
      Subversion       Subversion version control system  
     
      SVNAnt       Subversion Ant task  
     
      SVNAnt Documentation       SVNAnt documentation complete with installation and usage