<terp.exec> - an alternative <exec> task

The <terp.exec> task

Using the <terp.exec> task requires that the ant-terp.jar file be available to ant and that the task be registered via a <taskdef> statement:

<taskdef name="terp.exec" classname="com.codemesh.terp.ant.TerpExec"/>

Please note that you could use any value for the name attribute that you wish; you are not limited to terp.exec. All our examples and documentation use the terp.exec name and use a name prefix of terp. to signal that they originate with and rely on the terp framework.

The <terp.exec> task is not an extension of the ANT <exec> task. It extends the abstract TerpAwareTask type, which is a plain ANT task type providing support for the if and unless attributes available to all tasks in the terp framework:

terp.exec attributes

Name	Type	Description
expression	String	Required. A terp expression resolving to an executor result, usually an ^exec()() or ^shell()() invocation.
failonerror	boolean	Optional. A boolean terp expression that determines whether a BuildException is raised if the exit code of the invoked process is not zero. The default value is true (exception is raised).
if	String	Optional attribute specifying a boolean terp expression. The expression represents a condition that must be satisfied for the task to be executed.
result	String	Optional attribute specifying a terp property name to which the process result will be bound.
unless	String	Optional attribute specifying a boolean terp expression. The expression represents a condition that must not be satisfied for the task to be executed.

Purpose

The <terp.exec> task is an <exec> alternative that allows the execution of any ProcessExecutor-derived type and the subsequent use of the process invocation's results (exit code, output, error output). You can observe its usage in the C++ compiler unit tests. Please also see the section on executors.

Example

The following example invokes a shell command to list all files in the current directory. It also illustrates how the result can be used in later build steps.

<terp.exec expression="^shell()('ls -la .')"
           result="listing"
           failonerror="false"
           if="os.family!='windows'"
/>
<terp.echo if="listing!=null &amp;&amp; listing.exitcode==0"></terp.echo>

The <terp.exec> task is extremely useful inside <terp.foreach> loops and, together with the <terp.fail> task, in ANT unit tests.