Configuring Parasoft Build Monitor with Ant (Deprecated)

This topic covers how to configure the previous generation of Parasoft build monitoring with Ant. It is still supported for backwards compatibility, but the plugin described in Parasoft Test Ant Plugin is now the recommended method of build monitoring with Ant.

Sections include:

•	Setting Properties

•	Running Ant

•	Configuring CruiseControl (Optional)

•	Configuring Eclipse AntRunner (Optional)

•	Command Line Options

Setting Properties

Set all properties in the ANT_OPT environment variable so that the Ant script can detect all properties.

For Bash:

ANT_OPTS="-Dbuildmonitor.server.name=grsserver.example.com"

For Windows:

SET ANT_OPTS="-Dbuildmonitor.server.name=grsserver.example.com"

Build Monitor Logger

The Build Monitor Logger automatically detects the project name and project root from the Ant script.

Project Name

The project name must be set in the <project> node. If the project name is not defined in the option file or buildmonitor.projectroot, the application obtains the project name from the Ant script.

Build Monitor requires a name attribute from Ant. If Ant’s <project> node does not have a name, it will be set to "Default Project".

Although Ant allows for this, it is not a recommended practice. All Ant project nodes require a set name attribute, for example

<project name="XXXX" basedir=".">

...

</project>

Project Root

When Ant contains multiple javac build tasks, it is difficult to set the project root. If this is the case, do not set the project root in the option file or -Dbuildmonitor.projectname. javac tasks contain a src attribute and Build Monitor will use the src value to set the project root.

Running Ant

You can run Ant with the following command, which overrides the default logger for Ant and triggers Build Monitor to generate the build:

ant <user options> -logger proserve.tools.buildmon.BuildMonLogger

Configuring CruiseControl (Optional)

A logger is available in Build Monitor, which Ant builds within CruiseControl. Here’s how it works:

The CruiseControl Ant builder overrides the default Ant logger and uses an XML logger to save output from Ant. Next, CruiseControl reads the XML output, and then displays it on the dashboard. By design, CruiseControl always expects log.xml to be in the Ant execution directory. Further configuration is needed for Build Monitor integration:

Important for Continuum users! Continuum continuous build system created by Apache uses standard DefaultLogger for Ant. Normal proserve.tools.buildmon.BuildMonLogger would work just fine with Continuum.

Note: Build Monitor for Ant has been tested with CruiseControl 2.7.2 and above. Therefore, it is not recommended to use with previous versions of CruiseControl.

To integrate Ant projects under CruiseControl with Build Monitor:

1.	Modify the project configuration scheduler in config.xml from this:

</schedule>

To this:

<cruisecontrol>

...

  <project name="j2ssh">

    <schedule showprogress="true">

      <ant uselogger="true" target="clean build"

              loggerclassname="proserve.tools.buildmon.BuildMonLogger"

              buildfile="jtest-build.xml"

              showprogress="true"

              antworkingdir="projects/${project.name}"

              showantoutput="false"

              anthome="${CC_HOME}\apache-ant-1.7.0"

              usedebug="false" />

    </schedule>

</cruisecontrol>

2.	Set the showantoutput attribute to false to disable it when you are using Build Monitor.

It is important to do this because the showantoutput (AntOutputLogger from CruiseControl) option triggers a failure when you use Build Monitor with it.

3.	Turn ON the showprogress option.

This option triggers CruiseControl to include antProgressXmlLogger. AntProgressXmlLogger will log the project build status for CruiseControl while BuildMonLogger performs its tasks.

Note: CruiseControl 2.7.1 and older do not support the showAntOutput attribute. ShowProgress is optional for CruiseControl 2.7.1.

4.	(Optional) Open and review the cruisecontrol.log file to check Build Monitor output.

Tip! It is good practice to start your Ant project under your project directory so that any log files can use your project root directory instead of the CruiseControl home directory. Be sure to set the jvmarg node to optional and reflective of how to pass any property options for Build Monitor.

Configuring Eclipse AntRunner (Optional)

You can integrate Build Monitor with Eclipse AntRunner.

To integrate Eclipse AntRunner with Build Monitor:

1.	Copy the proserve-base.jar and proserve-plugin.jar files from the $PROSERVE_HOME/jar directory to:

	<eclipse install directory>/plugins/org.apache.ant_<version>/lib

2.	Add Build Monitor -logger argument to the target after the AntRunner application:

	<arg value="-logger" />

	<arg value="proserve.tools.buildmon.BuildMonLogger" />

3.	Add Build Monitor JVMArgs to specify Concerto Report Center properties:

	<jvmarg value="-Dbuildmonitor.grs.server=leech" />

	<jvmarg value="-Dbuildmonitor.grs.port=32323" />

	<jvmarg value="-Dbuildmonitor.attributes=\"ProjectName=samplePDE\"

For details about Build Monitor command line options available to use in Ant, see Command Line Options.

Example

Following is a usage example that includes the steps above—showing how to integrate Eclipse AntRunner with Build Monitor:

<project name="Build Monitor Example" default="-build.internal">

  <target name="-build.internal">

    <java jar="C:\Program Files\eclipse-all-in-one-SDK-3.3.0\plugins\org.eclipse.equinox.launcher_1.0.0.v20070606.jar"

fork="true" >

      <arg value="-application" />

      <arg value="org.eclipse.ant.core.antRunner" />

      <arg value="-logger" />

              <arg value="proserve.tools.buildmon.BuildMonLogger" />

      <arg value="-data"/>

      <arg value="C:\Documents and Settings\wes\workspace1"/>

      <arg value="-buildfile" />

      <arg value="C:\Documents and Settings\wes\workspace1\samplePDE\build.xml"/>

      <arg value="clean" />

      <arg value="build" />

      <jvmarg value="-Dbuilder=C:\Documents and Settings\wes\workspace1\samplePDE" />

      <jvmarg value="-Dbuildmonitor.grs.server=leech" />

              <jvmarg value="-Dbuildmonitor.grs.port=32323" />

              <jvmarg value="-Dbuildmonitor.attributes=\"ProjectName=samplePDE\"" />

    </java>

  </target>

</project>

Command Line Options

The following table lists and explains command line Build Monitor options that you can execute in Ant, if necessary:


Command	Task
buildmonitor.grs.server	(Required) Sets Report Center server name.
buildmonitor.grs.port	(Required) Sets Report Center server port. The default is set to 32323.
buildmonitor.alternatelogger	(Optional) Use to specify an alternate Ant BuildLogger for Build Monitor to use, such as MailLogger. By default, Build Monitor uses org.apache.tools.ant.DefaultLogger. Users can define their own loggers via typical passing of the -logger option to Ant, which is why Build Monitor supports loggers aside from its own. By adding this property to the Ant command line, Build Monitor loads the specified logger and uses it rather than the default logger; for example: buildmonitor.alternatelogger=org.apache.tools.ant.listener.MailLogger <with other options for MailLogger>
buildmonitor.attributes	(Optional) Sets Concerto Report Center user attributes. The format should be as follows: name:value,name2:value2... For example: buildmonitor.attributes:ProjectName:buildmon,ver-sion:1.1 buildmonitor.attributes:TestAttribute:test
buildmonitor.compiler	(Optional) Name of the compile task. The javac Ant edition begins logging compile information during the task that is matched to the compiler. The default value for this option is javac.
buildmonitor.nightly	(Optional) If set to true, "Nightly" is added as an attribute to the Test Group Properties Filter in Concerto Report Center. If left blank or set to false, it is not included as an attribute.
buildmonitor.projectname	(Optional) Name of the project, which is used for the Concerto Report Center project attribute. If property is not defined, Build Monitor will pull the value from Ant’s ${ant.project.name} property setting.
buildmonitor.projectroot	(Optional) Root path of the project. If the property is not defined, Build Monitor will pull the value from Ant’s ${basedir} property setting.
buildmonitor.verbose	(Optional) true means verbosity is on. false means verbosity is off. This command is only useful for debugging Build Monitor issues. It provides more verbose output to the console so that you can see what is going on when Build Monitor is executed.
eclipse.running	(Optional) Set this system property if running Eclipse’s JAVAC compiler for javac task. Eclipse’s javac compiler prints warning and error messages in a different format—bypassing eclipse.running=true as the JVM argument (ANT_OPTS is the environment variable for the Ant script).

Example

Following is a usage example that includes the command line options listed in the table above.

Important! The buildmonitor.attributes option format has been changed beginning with Build Monitor 3.0.1:

•	Commas (,) replace semi-colons (;) to separate attributes when multiple attributes are listed for Parasoft Concerto.

•	Colons (:) replace equal signs (=) for key and value assignments.

Although the previous format style (semi-colons and equal signs) will still work, the new format style (commas and colons) is recommended. Mixing these format styles will NOT work!

Note: The compiler should be set as your compile task (by default, it is javac).

<?xml version:"1.0"?>

<project name:"master project" basedir:"." default:"do-all">

    <property name:"src.dir" value:"."/>

    <property name:"buildmonitor.grs.server" value:"leech.parasoft.com"/>

         <property name:"buildmonitor.grs.port" value:"32323"/>

         <property name:"buildmonitor.verbose" value:"true"/>

         <property name:"buildmonitor.compiler" value:"javac"/>

    <target name:"clean">

        <delete dir:"j2ssh"/>

        <delete dir:"jEdit-4.3pre2"/>

        <delete dir:"WebApp"/>

    </target>

    <target name:"shadow">

        <exec dir:"${src.dir}" executable:"svn" failonerror:"true">

            <arg value:"checkout"/>

            <arg

value:"https://svn.parasoft.com/svn/proserve/demo/branches/aep/DummyCode/java/j2ssh/"/>

            <arg value:"j2ssh"/>

        </exec>

        <exec dir:"${src.dir}" executable:"svn" failonerror:"true">

            <arg value:"checkout"/>

            <arg

value:"https://svn.parasoft.com/svn/proserve/demo/trunk/DummyCode/java/jEdit-4.3pre2/"/>

            <arg value:"jEdit-4.3pre2"/>

        </exec>

    </target>

    <target name:"build-all">

        <ant antfile:"build.xml" dir:"j2ssh" target:"clean"/>

        <ant antfile:"build.xml" dir:"j2ssh" target:"build">

            <property name:"buildmonitor.attributes" value:"Test:BMTest,ProjectName:j2ssh"/>

        </ant>

        <ant antfile:"build.xml" dir:"jEdit-4.3pre2" target:"clean"/>

        <ant antfile:"build.xml" dir:"jEdit-4.3pre2" target:"compile">

            <property name:"buildmonitor.attributes"

value:"Test:BMTest,ProjectName:jEdit-4.3pre2"/>

        </ant>

    </target>

    <target name:"do-all" depends:"clean,shadow,build-all">

        <delete dir:"j2ssh"/>

        <delete dir:"jEdit-4.3pre2"/>

    </target>

</project>

Ant Plugin Details

Maven Plugin Details

Additional Documentation

Project Documentation