build.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- 

VERSION 1.0

ChangeLog
===================
* Fixed test compiling/locations
* Added a build-update task to re-download this gist.
* Added an example source location

Overview:
====================
This is a java build, dependency resolving, testing, packaging, and deployment system.
It is intended to be cross platform, but I only actively test linux.

Requirements:
====================
To run the script, you only need ant (http://ant.apache.org/bindownload.cgi).

If you want your project to be built/tested by this script, you need to provide a build.properties file and an ivy.xml file. These will define how your project should be packaged, where your source/res/test/dist/build directories are, and what dependencies should be pulled in with ivy. There are sensible defaults, and you can generate stubs by running 
    ant init

If you intend to deploy your project on a remote server, you will need to have a ssh client with sshkeys setup, and rsync. Windows users should look into Cygwin (http://cygwin.com/install.html) for providing these requirements.

Installation:
====================
To install this build system, simply download/copy the build.xml file into your project root and treat it as a regualar ant build file.

  curl https://raw.github.com/gist/1401567/build.xml > build.xml

Usage:
====================
Usage is fairly basic. If you want to generate a basic structure of what the system deals with, run this command:

  ant init

This will print out a summary of what directories and files are looked at and used by the build system.

The core tasks that you would want to use would probably be:

  ant ivy-resolve # This downloads all dependencies defined in your ivy.xml file
  ant test # This compiles your source code, then compiles your test source code and then runs the tests and shows the output
  ant dist # This compiles your code, copies your ivy.xml and your libs to your dist dir, as well as jaring up your sources, and resources.
  ant deploy # If configured, this runs dist and test and then rsyncs the dist folder to a server and then runs a command.

Since deploy does almost everything, you could get away with only using ant deploy - It will not actually deploy unless you've setup deployment.

Getting Started:
====================
When creating a new project, you can run:

  ant init # This creates a skeleton of a project based around this build.xml

This will create some empty folders and files along with messages about what they are used fore.

Several empty files are created and need to be filled out before the build system can considered to be functional. 
These files include the build.properties, ivy.xml, and optionally local.build.properties.
Below is a collection of examples of these files' contents.

Example of a basic build.properties file:
==========================================
module=MyProject # The name of my project
version=0.1      # The current version of my project
org=com.nthalk   # The entity that produced the project
jar.class=com.nthalk.MyProject.Application # The class that the jar runs the main method off of during java -jar {module}.jar

Example of a basic ivy.xml file: (http://ant.apache.org/ivy/history/trunk/tutorial/conf.html)
NOTE: The @var@ tokens are replaced by similar settings in the build.properties file so that you do not have to edit them in two places. 
==========================================
<ivy-module version="2.0">
  <info module="@MODULE@" organisation="@ORG@" revision="@VERSION@" />
  <configurations>
    <conf name="compile" visibility="public" />
    <conf name="test" visibility="public" extends="compile" />
  </configurations>
  <dependencies>
    <dependency org="com.google.guava" name="guava" rev="r09"
      conf="compile" />
    <dependency org="junit" name="junit" rev="4.10" conf="test->compile" />
  </dependencies>
</ivy-module>

Example ivysettings.xml file: (http://ant.apache.org/ivy/history/latest-milestone/settings.html)
NOTE: I use this, it includes my company's public repository.
==========================================
<ivysettings version="1.0" xmlns:e="http://ant.apache.org/ivy/extra">
  <settings defaultResolver="chain" />
  <resolvers>
    <chain name="chain" returnFirst="true">
      <filesystem name="local.repo"  changingPattern=".*" checkmodified="true">
        <artifact pattern="${repo.dir}/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
        <ivy pattern="${repo.dir}/[organisation]/[module]/[revision]/ivy.xml"/>
      </filesystem>
      <url name="com.anteambulo" checksums="">
        <artifact pattern="http://www.anteambulo.com:2912/files/repo/[organisation]/[module]/[revision]/[module]-[revision].jar" />
        <ivy pattern="http://www.anteambulo.com:2912/files/repo/[organisation]/[module]/[revision]/ivy.xml" />
      </url>
      <ibiblio name="central" m2compatible="true" />
      <ibiblio name="couchbase" m2compatible="true" root="http://files.couchbase.com/maven2/" />
    </chain>
  </resolvers>
</ivysettings>


Example of a local.build.properties:
==========================================
deploy.user=nthalk         # This is the user that will be used - It is important to have your sshkeys setup before using this.
deploy.host=nthalk.com     # This is the host that will be used via ssh.
deploy.dir=/opt/MyProject/ # This directory will have the dist of my project rsynced into it (you will need to have rsync installed).
deploy.cmd=sh -c 'cd /opt/MyProject;export DISPLAY=:0 && nohup java -jar MyProject.jar > /opt/MyPorject/last.deploy.log 2>&1 &' # This is a complex command, it sets the display (I'm using Xvfb), nohup's the jar (so it does not terminate on logout), and drops immediate input into the last.deploy log so I can see what went wrong. Usually, I configure outside logging, so that last.deploy.log only contains errors up until the actuallogging is configured.

-->
<project xmlns:ivy="antlib:org.apache.ivy.ant" default="dist" basedir=".">
  <!-- Property files -->
  <property name="build.properties.file" location="build.properties" />
  <property file="${build.properties.file}" />
  <property name="local.build.properties.file" location="local.build.properties" />
  <property file="${local.build.properties.file}" />

  <!-- Properties -->
  <property name="repo.dir" location="${user.home}/.ant/cache" />
  <property name="src.dir" location="src" />
  <property name="test.dir" location="test" />
  <property name="gen.dir" location="gen" />
  <property name="example.dir" location="example" />
  <property name="res.dir" location="res" />
  <property name="lib.dir" location="lib" />
  <property name="build.dir" location="build" />
  <property name="dist.dir" location="dist" />

  <!-- Plugins -->

  <!-- BEGIN IVY plugin -->
  <property name="ivy.dep.file" value="ivy.xml" />
  <property name="ivy.lib.dir" value="${lib.dir}" />
  <property name="ivy.install.version" value="2.2.0" />
  <property name="ivy.settings.file" location="ivysettings.xml" />
  <condition property="ivy.home" value="${env.IVY_HOME}">
    <isset property="env.IVY_HOME" />
  </condition>
  <property name="ivy.home" value="${user.home}/.ant" />
  <property name="ivy.jar.dir" value="${ivy.home}/lib" />
  <property name="ivy.jar.file" value="${ivy.jar.dir}/ivy.jar" />
  <available file="${ivy.jar.file}" property="ivy-exists" />
  
  <target name="ivy-download" unless="ivy-exists">
    <mkdir dir="${ivy.jar.dir}" />
    <!-- download Ivy from web site so that it can be used even without any special installation -->
    <get src="http://repo2.maven.org/maven2/org/apache/ivy/ivy/${ivy.install.version}/ivy-${ivy.install.version}.jar" dest="${ivy.jar.file}" usetimestamp="true" />
    <get src="http://repo1.maven.org/maven2/commons-httpclient/commons-httpclient/3.0/commons-httpclient-3.0.jar" dest="${ivy.jar.dir}" usetimestamp="true" />
    <get src="http://repo1.maven.org/maven2/commons-codec/commons-codec/1.2/commons-codec-1.2.jar" dest="${ivy.jar.dir}" usetimestamp="true" />
  </target>
  
  <target name="ivy-init" depends="ivy-download">
    <!-- try to load ivy here from ivy home, in case the user has not already dropped
                it into ant's lib dir (note that the latter copy will always take precedence).
                We will not fail as long as local lib dir exists (it may be empty) and
                ivy is in at least one of ant's lib dir or the local lib dir. -->
    <path id="ivy.lib.path">
      <fileset dir="${ivy.jar.dir}" includes="*.jar" />
    </path>
    
    <taskdef resource="org/apache/ivy/ant/antlib.xml" uri="antlib:org.apache.ivy.ant" classpathref="ivy.lib.path" />
    <ivy:settings/>
  </target>
  
  <target name="ivy-resolve" depends="ivy-init, ant-contrib-init">
    <ivy:resolve file="${ivy.dep.file}" conf="${ivy.configurations}" />
    <ivy:retrieve />
  </target>
  
  <target name="ivy-install" depends="jar">
    <mkdir dir="${repo.dir}/${org}/${module}/jars" />
    <copy file="${dist.dir}/ivy.xml" tofile="${repo.dir}/${org}/${module}/ivy-${version}.xml" />
    <copy file="${dist.dir}/${module}.jar" tofile="${repo.dir}/${org}/${module}/jars/${module}-${version}.jar" />
  </target>
  <!-- END IVY plugin -->


  <!-- BEGIN JUNIT plugin -->
  <property name="junit.install.version" value="4.10" />
  <target name="junit-init" depends="ivy-init">
    <ivy:cachepath organisation="junit" module="junit" revision="${junit.install.version}" pathid="junit.lib.path" inline="true" log="quiet" />
    <taskdef name="junit" classname="org.apache.tools.ant.taskdefs.optional.junit.JUnitTask" classpathref="junit.lib.path"/>
  </target>
  <!-- END JUNIT plugin -->

  <!-- BEGIN ANT-CONTRIB plugin -->
  <property name="ant-contrib.install.version" value="1.0b3" />
  <target name="ant-contrib-init" depends="ivy-init">
    <ivy:cachepath organisation="ant-contrib" module="ant-contrib" revision="${ant-contrib.install.version}" pathid="ant-contrib.lib.path" inline="true" log="quiet" />
    <taskdef resource="net/sf/antcontrib/antcontrib.properties" classpathref="ant-contrib.lib.path"/>
  </target>
  <!-- END ANT-CONTRIB plugin -->

  <!-- Deletes the existing build, docs and dist directory -->
  <target name="clean">
    <mkdir dir="${build.dir}" />
    <mkdir dir="${dist.dir}" />
    <mkdir dir="${lib.dir}" />

    <delete dir="${build.dir}" includes="**/*" />
    <delete dir="${dist.dir}" includes="**/*" />
  </target>

  <!-- Creates the build, docs and dist directory -->
  <target name="init">
    <echo message="Creating ivy.xml file -- This is where you define your project's dependency configuration." />
    <touch file="${ivy.dep.file}" />
    <echo message="Creating src directory -- this is where your application code goes." />
    <mkdir dir="${src.dir}" />
    <echo message="Creating res directory -- this is where any non-java resources that will be present in the distribution jar will go." />
    <mkdir dir="${res.dir}" />
    <echo message="Creating test directory -- this is where your junit tests should go." />
    <mkdir dir="${test.dir}" />
    <echo message="Creating build.properties file -- this is where you should define your module's version, company name, and jar properties." />
    <touch file="${build.properties.file}" />
    <echo message="Creating local.build.properties file -- this is where you should define your envirnoment's build properties, like your deployment command, user, host, and dir." />
    <touch file="${local.build.properties.file}" />
    <echo message="Creating build directory -- this is where class files are compiled into." />
    <mkdir dir="${build.dir}" />
    <echo message="Creating dist directory -- this is where the project, ivy descriptor, and dependencies are copied into for distribution." />
    <mkdir dir="${dist.dir}" />
    <echo message="Creating lib directory -- this is where the ivy gathers the build dependencies." />
    <mkdir dir="${lib.dir}" />
    <echo message="Creating gen directory -- this is where any generated code goes." />
    <mkdir dir="${gen.dir}" />
  </target>

  <!-- Provieds a project the option to define precompilation tasks -->
  <target name="precompile" depends="clean, ivy-resolve, ant-contrib-init">
    <if>
      <available file="precompile.xml" />
      <then>
        <ant antfile="precompile.xml" />
      </then>
    </if>
  </target>

  <!-- Compiles the java code -->
  <target name="compile" depends="precompile">
    <path id="build.classpath">
      <fileset dir="${lib.dir}">
        <include name="**/*.jar" />
      </fileset>
    </path>

    <var name="srcs" value="${src.dir}" />

    <!-- Include gen if it is here -->
    <if>
      <available file="${gen.dir}" type="dir" />
      <then>
        <var name="srcs" value="${srcs};${gen.dir}" />
      </then>
    </if>

    <!-- Include example if it is here -->
    <if>
      <available file="${example.dir}" type="dir" />
      <then>
        <var name="srcs" value="${srcs};${example.dir}" />
      </then>
    </if>

    <javac srcdir="${srcs}" destdir="${build.dir}" target="1.6" source="1.6" debug="true" classpathref="build.classpath" includeantruntime="false" />
  </target>

  <!-- Copies the non sources/docs jars alongside the the release jar -->
  <target name="jar-libs">
    <mkdir dir="${dist.dir}/lib" />
    <copy todir="${dist.dir}/lib">
      <fileset dir="${lib.dir}" includes="*.jar" excludes="*-sources.jar,*-javadoc.jar" />
    </copy>
  </target>

  <!--Creates the deployable jar file -->
  <target name="jar" depends="compile,jar-libs">
    <path id="build.classpath">
      <fileset dir="${lib.dir}">
        <include name="**/*.jar" />
      </fileset>
    </path>
    <!-- We have to include the libs for the jar -->
    <manifestclasspath property="lib.list" jarfile="${dist.dir}">
      <classpath refid="build.classpath" />
    </manifestclasspath>
    <!-- Jar the resources -->
    <jar destfile="${dist.dir}/${module}.jar">
      <manifest>
        <attribute name="Main-Class" value="${jar.class}" />
        <attribute name="Class-Path" value="${lib.list}" />
      </manifest>
      <fileset dir="${src.dir}" />
      <fileset dir="${build.dir}" />
      <fileset dir="${gen.dir}" erroronmissingdir="false" />
      <fileset dir="${res.dir}" erroronmissingdir="false" />
    </jar>
    <!-- Copy the ivy file next to the jar -->
    <copy file="ivy.xml" todir="${dist.dir}">
      <filterset>
        <filter token="VERSION" value="${version}" />
        <filter token="MODULE" value="${module}" />
        <filter token="ORG" value="${org}" />
      </filterset>
    </copy>
  </target>

  <!-- Distribution -->
  <target name="dist" depends="jar,ivy-install">
    <if>
      <available file="dist.xml" />
      <then>
        <ant antfile="dist.xml" />
      </then>
    </if>
  </target>

  <!-- Testing -->
  <target name="test" depends="jar,junit-init,ant-contrib-init">
    <if>
      <available file="${test.dir}" property="tests-exist" />
      <then>
        <path id="build.classpath">
          <fileset dir="${dist.dir}">
            <include name="**/*.jar" />
          </fileset>
        </path>
        <javac srcdir="${test.dir};" destdir="${build.dir}" target="1.6" source="1.6" debug="true" classpathref="build.classpath" includeantruntime="false" />
        <echo message="Running tests..." />
        <junit showoutput="true">
          <classpath>
            <path refid="build.classpath" />
            <path location="${build.dir}" />
          </classpath>
          <formatter type="plain" usefile="false" />
          <batchtest>
            <fileset dir="${test.dir}" includes="**/*.java" />
          </batchtest>
        </junit>
      </then>
    </if>
  </target>

  <!-- Deploys the project -->
  <target name="deploy" depends="dist,test">
    <if>
      <!-- Run an external deploy.xml file if it exists -->
      <available file="deploy.xml" />
      <then>
        <ant antfile="deploy.xml" />
      </then>
      <elseif>
        <!-- Run internal deploy scripts if configured -->
        <and>
          <isset property="deploy.host" />
          <isset property="deploy.dir" />
          <isset property="deploy.user" />
          <isset property="deploy.cmd" />
        </and>
        <then>
          <echo message="Deploying files..." />
          <exec dir="." executable="rsync" failonerror="true">
            <arg line="-rlDv -e ssh ${dist.dir}/ ${deploy.user}@${deploy.host}:${deploy.dir}" />
          </exec>
          <echo message="Running service..." />
          <exec dir="." executable="ssh" failonerror="true">
            <arg line="-n -f ${deploy.user}@${deploy.host} &quot;${deploy.cmd}&quot;" />
          </exec>
        </then>
      </elseif>
      <else>
        <echo message="Deployment not configured through deploy.xml or deploy properties: deploy.user, deploy.host, deploy.dir, deploy.cmd" />
      </else>
    </if>
  </target>

  <!-- Updates the build file from the repository whence it came! -->
  <target name="build-update">
    <get src="https://raw.github.com/gist/1401567/build.xml" dest="build.xml" />
  </target>
</project>