Apache Ant Comments and echo Task: Write Clear build.xml Files and Control Log Output

Originally published on 2010-07-22; fully revised and updated.

If you maintain Ant build files, comments and logging are essential for readability and troubleshooting. This guide explains how to use XML comments in build.xml, how the echo task behaves at different log levels, and how to choose the right approach for documentation versus runtime diagnostics.

Commenting in Ant build files (build.xml)

Ant build files are XML, so comments use standard XML comment syntax: <!-- ... -->. These comments are for humans reading the file and are not shown during normal build output.

<?xml version="1.0" encoding="UTF-8"?>
<project name="demo" default="compile">
    <!-- Compile Java sources into build/classes -->
    <target name="compile">
        <javac srcdir="src" destdir="build/classes"/>
    </target>
</project>Code language: HTML, XML (xml)

Keep comments short and intention-focused (why a target exists, assumptions, non-obvious behavior). As with XML generally, avoid malformed comment syntax and avoid nesting comments.

XML comments vs echo messages: choose the right mechanism

Using the echo task effectively

The Ant echo task writes messages to Ant loggers/listeners (typically console output unless logging is redirected). You can pass text with the message attribute or as nested text, and you can also write output to a file.

Key echo attributes

Common echo styles

<echo message="Hello, world"/>

<echo message="Embed a line break:${line.separator}"/>

<echo>This is a longer message
across multiple lines.</echo>

<echo message="Deleting drive C:" level="debug"/>

<echo level="error">
Imminent failure in the antimatter containment facility.
Please withdraw to a safe location.
</echo>

<echo file="runner.csh" append="false">#!/bin/tcsh
java -mx1024m ${project.entrypoint} $$*
</echo>Code language: PHP (php)

How Ant decides whether an echo message is shown

Console visibility depends on both the echo level and how Ant is started (-q, default, -v, -d). Higher-verbosity modes show more messages.

flowchart TD
    A[Ant runs target] --> B[Echo task executes]
    B --> C{File attribute set}
    C -- yes --> D[Write message to file]
    C -- no --> E{Current log mode allows this level}
    E -- yes --> F[Show in console output]
    E -- no --> G[Suppress from console]

ant -q
ant
ant -v
ant -d

Practical build.xml example: comments plus actionable logging

<project name="sample-app" default="package">

    <!-- Central output directory used by all targets -->
    <property name="build.dir" value="build"/>

    <target name="clean">
        <echo level="info" message="Cleaning ${build.dir}"/>
        <delete dir="${build.dir}"/>
    </target>

    <target name="package" depends="clean">
        <!-- This warning is important for operators in standard runs -->
        <echo level="warning" message="Packaging started"/>

        <mkdir dir="${build.dir}"/>

        <echo file="${build.dir}/build-meta.txt" append="false">
project=sample-app
build.timestamp=${DSTAMP}-${TSTAMP}
        </echo>

        <echo level="debug" message="Wrote ${build.dir}/build-meta.txt"/>
    </target>

</project>Code language: HTML, XML (xml)

Best practices

• Use XML comments for maintainers and echo for runtime visibility.
• Choose log levels intentionally: warning/error for important messages, debug for deep diagnostics.
• Avoid excessive echo noise in frequently executed targets.
• When generating files with echo file=, be explicit about append to prevent accidental overwrites.
• Run builds in multiple log modes (-q, default, -v, -d) to confirm message visibility is what you expect.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.