Creating the Ant build script

Edit online

The Dependency Build requires a user-supplied Ant build script to invoke to build the HFS artifact when HFS content changes have been detected.

The Ant build script must be in a separate file that is accessible to the build through the path specified in the z/OS translator described later. The build script will be invoked by the Dependency Build through the Ant-Contrib Antfetch task. Detailed information about the Antfetch task is available in AntFetch.

The Ant build script must specify all inputs and outputs, as well as, all tasks that are required to build the HFS artifact.

The following sections provide information to consider when creating the build script. A sample build script is provided in the last of the following sections.

Properties

The Ant build script has access to all Dependency Build properties, including all standard Engineering Workflow Management, EE, and user-defined properties that are available during the build.

Additional properties can be created in the Ant build script to pass information back to the EE build environment, for instance, to conditionally indicate the presence or absence of build outputs. These properties are returned to the EE build environment by specifying a comma-separated list of property names in the Build return properties ﬁeld of the z/OS translator for the build script.

Specifying a property name in the Build return properties field of the translator editor is necessary to pass a property from the build script to the EE build environment, and subsequently, to another translator within the language deﬁnition.

Note: As the build script is outside of the Ant macro context of the Dependency Build, some macrodef attributes available to translators are available to the build script as properties. For example, the @{source.member.name} attribute is available to the build script as the ${source.member.name} property.

Source properties

The Ant build script can use EE built-in source properties such as the following ones:

${source.folder.name}
${source.folder.scm.location}
${source.component}
${source.project}

Return codes

The Ant build script can specify an explicit return code for the translator by invoking the antz:setrc task that is provided by EE.

Note: The antz namespace is defined within the <project> specification, which makes this task accessible; the provided sample has an example of this. The user-supplied build script will also need this definition for the setrc task to be accessible.

The return code that is speciﬁed in the build script is used in several ways:

It is compared to the Maximum Return Code ﬁeld in the translator definition to determine whether this step of the build was successful.
If it exceeds the Maximum Return Code specified, the execution of translators for the language stops and a build failure is reported. If the build definition speciﬁes a conditional build, the build stops.
It is shown in the build report.

Logging

The Ant build file can use the logPublisher task to publish the log files to the Logs tab of the build result.

Downloads

The Ant build script can use the artifactFilePublisher task to publish a file or another artifact that is produced by the build to the Downloads tab of the build result.

Sample

The following code is a sample Ant build script.

<!-- this is how you run a build file loaded from SCM -->
<project
    name="build"
    default="main"
    xmlns:antz="antlib:com.ibm.team.enterprise.zos.build.ant">
<taskdef classname="com.ibm.team.build.ant.task.ArtifactFilePublisherTask" name="artifactFilePublisher"/>
<taskdef classname="com.ibm.team.build.ant.task.LogPublisherTask" name="logPublisher"/>
<target name="main">
<!-- run the build, e.g. kick off 'make', 'javac', etc -->
<exec executable="make" failonerror="true" dir="${source.folder.scm.location}">
<arg line="-f src/Makefile"/>
</exec>
<!--
  This is how you set the return code to be compared against the maxrc.
  This only needs to be done if you're providing a non-zero return code.
  You could capture the rc from the exec process you invoked and set that.
-->
<antz:setrc rc="8">
<!--
       Alternatively you can specifically fail with a message instead of just
       setting a 'bad rc'
     -->
<fail message="I just don't want to keep building anymore"/>
<!-- 
       Outputs should be moved outside this directory since the load directory
       can be deleted
     -->
<move todir="${team.enterprise.hfs.outputdir}" overwrite="true">
  <fileset dir="${source.folder.scm.location}">
                  <include name="**/*.zip"/>
</fileset>
</move>

<move
    file="${source.folder.scm.location}/javaProject/foo.jar"
    todir="${team.enterprise.hfs.outputdir}/javaProject/"
    overwrite="true">

<!-- Publish a file to the Logs tab -->
<logPublisher
    filePath="${logFile}"
    buildResultUUID="${buildResultUUID}"
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    passwordfile="${passwordFile}"
    label="Some log"/>

<!-- Publish a file to the Downloads tab -->
<artifactFilePublisher
    filePath="${fileToPublish}"
    buildResultUUID="${buildResultUUID}"
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    passwordfile="${passwordFile}"
    label="Some download"/>

</target>
</project>