# Antelope

Author: Dale Anson
Version: 1.98

"This product includes software developed by the Apache Software Foundation (http://www.apache.org/)."

## Contents

Introduction
Requirements
Support
Running Antelope

- As a stand-alone application
- As a jEdit plugin

Running Ant Targets
Displaying Ant Properties
Editing the Build File
Tracing Ant Targets
The Built-in AntLogger
The 'Assert' Task
The 'If' Task
Ant Coding Style

## Introduction

Antelope is a graphical user interface for running Ant. It provides a set of buttons, one per target, which makes it easy to start a specific Ant operation.

Top

## Requirements

See the installation instructions below for the specific requirements for Antelope. Antelope does require Java 1.4 or later as it makes use of both java.util.logging and java.util.prefs APIs which were introduced in that version.

Top

## Support

Please visit the project web pages at http://antelope.sourceforge.net for reporting bugs, user mailing lists, and other technical resources.

Top

## Running Antelope

Antelope can be ran in two ways. Follow these links for installation and starting instructions for each mode.

- As a stand-alone application
- As a jEdit plugin

(Also see the section about running Antelope's AntLogger.)

Either way, Antelope is operated almost identically. To set up Antelope, click on the "Options" button. This will display the following:

When running Antelope as a stand-alone application, the options "Save all files before running targets" and "Use error parsing" are not available. This is the only difference between the stand-alone and the plugin.

The available options are as follows:

1. Ant build file The current build file name is displayed along with an option to choose a new build file. Antelope is basically useless without a build file, so this is the first step.
2. Save all files before running targets This is only available when running as a jEdit plugin. If checked, all files that are currently open for editing in jEdit will be saved before running the selected target.
3. Use error parsing This is only available when running as a jEdit plugin. If checked, output from the target will be passes through the Console plugin error parser and errors will be displayed in the ErrorList plugin. This is useful for tasks such as javac that produce standard error messages. Other tasks may not produce output suitable for error parsing, in which case, the output might be cleaner if this options is turned off.
4. Show subtargets There are two common methods of designating "primary" targets and "subtargets". Primary targets are those that are invoked directly, while subtargets are generally "helper" targets that are invoked from other targets. One method of distinguishing between primary and subtargets is only giving descriptions to primary targets. Unchecking the "Show targets without descriptions" will cause Antelope to display buttons only for targets that have a description. Another common method to designate subtargets is to use "dot" notation, for example, a "clean" target may have two helper targets, "clean.docs" and "clean.api.docs". Unchecking the "Show targets with dots" will cause Antelope to display a button for the "clean" target but not the "clean.docs" nor the "clean.api.docs" targets.
5. Set message level There are five message levels available and are in order of verbosity, "Error" being the lease verbose and "Debug" being the most. For general use, "Information" is about right.
6. Show message events Ant produces messages on various events as it runs a target. Generally, all Ant messages are useful, but these can be adjusted as necessary. Turning off 'Target events' and 'Task events' will generally show all the important information without too much excess output.

Top

## Running Ant Targets

Ant targets are ran by simply clicking the associated button. The button for a running target will show red text. Long running targets can be stopped by clicking any of the target buttons. If Antelope is being ran as a jEdit plugin, execution can also be stopped by clicking the "Stop" button on the Console plugin.

Top

## Displaying Ant Properties

The "Properties" button displays the current properties and references known to Ant from the current build file and the system environment. This is handy for determining exactly what Ant thinks a specific property value is. "Properties" and "References" are for viewing only, not for editing. The "Properties" shows all properties known to the Ant project: system properties, user properties, and global properties set in the build file. The "References" tab shows all global references known to the Ant project.

The "User" tab is for setting user properties. These are properties that would be passed to Ant on the command line. These properties are persistent for the build file, so each time the build file is opened, the user properties will be restored. To enter a new property, click the "New" button to create a blank row in the table. Be sure to "enter" the name and value, that is press the 'Tab' or 'Enter' key or click out of the cell to make sure the name and/or value are stored. To remove a property, empty the corresponding value.

Top

## Editing the Build File

Clicking the "Edit" button puts Antelope in 'edit' mode. Antelope will turn green to indicate edit mode. In this mode, the target buttons don't execute Ant targets, instead, they cause the edit area to scroll to the start of the target. To turn off 'edit' mode, click the "Edit" button again.

As a jEdit plugin, clicking the "Edit" button will open the build file in a jEdit buffer.

As a stand-alone application, clicking the "Edit" button opens the "Edit" tab to edit the build file.

When the file is saved (either by saving the buffer in jEdit or by using the File - Save Build File menu item in stand-alone mode), Antelope will immediately pick up any changes in the build file and recreate the button panel to reflect those changes.

Here is Antelope in edit mode:

Top

## Tracing Target Execution

Antelope is put into 'tracing mode' when the "Trace" button is clicked. When in tracing mode, the background of the button panel will be blue. When in tracing mode, the target buttons do not actually execute the target. Instead, the output will show the specific order of execution of tasks performed by the target and targets that the selected target depends on. This is useful for figuring out exactly what a specific target does and the order of operations. To turn off tracing mode, click the "Trace" button a second time.

In general, targets are not parsed below task level, that is, nested task attributes are not displayed. However, two tasks are treated specially as they have a direct bearing on how a target executes. These two tasks are `ant` and `antcall`. If the trace encounters the `ant` task, the `buildfile` and `target` attributes will be displayed, the build file loaded, and the target traced in that build file. If the trace encounters an `antcall` task, the `target` attribute will be parsed and the target will be traced.

Here is a sample trace:

`Tracing target: deploy-all
Legend: <target>[task]
<deploy-all>
<clean>[delete]
<deploy-all>[javac deprecation=on debug=on destdir=build srcdir=src includes=ise/ excludes=ise/antelope/plugin/ includejavaruntime=yes source=1.4]
<deploy-all>[copy todir=build]
<deploy-all>[jar jarfile=/usr/local/java/antelope/Antelope]
</deploy-all>
Done tracing target: deploy-all
`

And a line by line explanation:

Tracing target: deploy-all | The trace is going to trace the deploy-all target.
Legend: <target>[task] | Targets shown with angle brackets, tasks with square brackets.
<deploy-all> | The trace is starting on the deploy-all target.
<clean>[delete] | The deploy-all target depends on the clean target, which performs a 'delete' task.
<deploy-all>[javac deprecation=on debug=on destdir=build srcdir=src includes=ise/ excludes=ise/antelope/plugin/ includejavaruntime=yes source=1.4] | The deploy-all target executes a 'javac' task. The parameters for the task are shown.
<deploy-all>[copy todir=build] | The deploy-all target executes a 'copy' tasks. Most likely, this tasks has nested includes and/or excludes, which are not shown in the trace.
<deploy-all>[jar jarfile=/usr/local/java/antelope/Antelope] | The deploy-all target executes the 'jar' task.
</deploy-all> | The trace has reached the end of the deploy-all target.
Done tracing target: deploy-all | Obviously, the trace is done.

So the 'deploy_all' target first causes the 'clean' target to execute a 'delete' task, then causes the 'compile' target to execute a 'javac' task, and finally causes the 'deploy' target to create a jar file.

Top

## Antelope as a Stand-Alone Application

Antelope is packaged as a single jar file, Antelope.jar. Several other jar files may be necessary:

- kappalayout.jar This is required for Antelope to run. KappaLayout is a layout manager. This jar file is bundled with the Antelope distribution. Put it in your classpath.
- ant.jar Antelope requires Ant to do anything useful. Ant is available at http://jakarta.apache.org/ant. Put it in your classpath.
- optional.jar This is an optional library that is distributed with Ant. It has additional Ant tasks that may be useful. Put it in your classpath as required.
- tools.jar This is distributed with the Java Software Development Kit. If your build file makes use of any of the JDK tools (such as javac or javadoc), put this in your classpath.
- An XML parser This can be one of several publicly available XML parsers. Ant is shipped with the Xerces parser. To use the Xerces parser shipped with Ant, add xercesImpl.jar and xml-api.jar from the ${ant.home}/lib directory to your classpath.

The manifest file for Antelope.jar specifies kappaylayout.jar and ant.jar on the classpath, so all that should be necessary to start Antelope is:

`java -jar Antelope.jar`

If using the optional.jar and/or tools.jar:

`java -cp optional.jar:tools.jar -jar Antelope.jar`

Here is Antelope running as a stand-alone application:

Antelope as a stand-alone application provides a few features not found in the plugin version. In the plugin version, these features are provided by jEdit, so are not duplicated. The additional features are:

- The "File" menu deals with the build file, providing the ability to open a build file and to save changes to the build file. Antelope is not intended to be a full-featured editor, so it is assumed that the build file already exists. The editing facilities provided by Antelope are for convenience, and were not designed to create build files from scratch, however, the ability to create a new file is on the feature list for implementation in a future version.
- Also on the "File" menu is the list of recently opened files. This is handy for choosing a file that was previously opened without using the file chooser.
- The "Output" menu provides the ability to save the Ant output to a file and to clear the 'Output' window.
- The "Format" menu provides the ability to set the font for the output and edit windows. The same font is used for both windows. The color coding of the edit and output windows is not adjustable in this version.

Printing is not available in this version, but is also on the feature list for implementation. Top

## Antelope as a jEdit Plugin

Antelope is packaged as a single jar file, Antelope.jar. To install Antelope, copy Antelope.jar to ${user.home}/.jedit/jars. Several other jar files are required:

- kappalayout.jar This is required for Antelope to run. KappaLayout is a layout manager. This jar file is bundled with the Antelope distribution. Copy or link this file to ${user.home}/.jedit/jars.
- ant.jar Antelope requires Ant to do anything useful. Ant is available at http://jakarta.apache.org/ant. Copy or link this file to ${user.home}/.jedit/jars.
- optional.jar This is an optional library that is distributed with Ant. It has additional Ant tasks that may be useful. Copy or link this file to ${user.home}/.jedit/jars as required.
- tools.jar This is distributed with the Java Software Development Kit. If your build file makes use of any of the JDK tools (such as javac or javadoc), you need this in the classpath. The AntelopePlugin asks jEdit to load tools.jar automatically, but depending on your environment (jEdit is running in a plain JRE, for example), this may fail. Copy or link this file to ${user.home}/.jedit/jars if you need it and jEdit can't load it. Antelope will tell you when it can't find a tool from this jar the first time you try to use the tool.
- Console.jar This is a jEdit plugin and is required. Output from Antelope will be displayed in the Console. Make sure jEdit has this plugin installed.
- ErrorList.jar This is another jEdit plugin and is required. Errors produced by Ant are displayed by Antelope in the ErrorList plugin. Make sure jEdit has this plugin installed.
- An XML parser This can be one of several publicly available XML parsers. Ant is shipped with the Xerces parser. To use the Xerces parser shipped with Ant, add xercesImpl.jar and xml-api.jar from the ${ant.home}/lib directory to your classpath. If you have the XML plugin installed, then you already have a version of Xerces installed. Note: There is sometimes a problem with various jEdit plugins and xml parsers. Generally, this is due to a conflict with several similar parsers being in the class path. The simplest way to resolve this issue is to remove ALL xml parsers (xerces, crimson, xml4j, etc) from the ${user.home}/.jedit/jar directory and copy ONE of them to your ${jedit.home}/jars directory. This will ensure that a good parser is in your classpath, that it is loaded before any plugins, and that there will be no conflicts from having multiple parsers. My recommendation is that the latest Xerces jars from http://xml.apache.org/xerces2-j/index.html be used as this is the industry standard Java XML parser.

Here is Antelope running in jEdit:

Top

## AntLogger

One of the classes distributed with Antelope is AntLogger, which is useful outside of Antelope. This is a special Ant logger and can be attached to Ant as the default logger on the command line. All Ant log messages are sent to a java.util.logging.Logger, so any number of handlers can be associated for controlling output. Make sure ise.antelope.AntLogger is in the classpath, then run Ant:

`ant -logger ise.antelope.AntLogger [other standard Ant options]`

Properties
Properties can be set either on the command line or in the build file. All are optional. These properties are read and set at the start of each call to `buildStarted`

Property | Description | Default
antlogger.echo | If set to true, output from this logger will be echoed to the original System.out and System.err print streams. | false
antlogger.namespace | The namespace for the logger. See the java.util.logging.Logger API documentation for a discussion of logger namespaces. This should be a dot separated name and should normally be based on the package name or class name of the subsystem, such as org.apache.tools.ant. | ise.antelope.Antelope
antlogger.file | If used, will add a java.util.logging.FileHandler to the current logger. See the java.util.logging.FileHandler API for a discussion of the value pattern. Basically, this is the name of a file, but other things can be done. | none
antlogger.file.append | If set to true and antlogger.file is being used, then output will be appended to an existing file. If false, any existing file will be overwritten. | false

Examples:

<property name="antlogger.echo" value="true"/>
- or -
ant -logger ise.antelope.AntLogger -Dantlogger.echo=true [other options]

<property name="antlogger.namespace" value="com.mycompany.package"/>
- or -
ant -logger ise.antelope.AntLogger -Dantlogger.namespace=com.mycompany.package [other options]

<property name="antlogger.file" value="/tmp/output.log"/>
<property name="antlogger.file.append" value="true"/>
- or -
ant -logger ise.antelope.AntLogger -Dantlogger.file=/tmp/output.log -Dantlogger.file.append=true [other options]

Output

Messages for certain build events are sent at a particular log Level. See java.util.logging.Level for a discussion of the various levels. AntLogger associates build events with log Levels as follows:

Level.ERROR | Build failed
Level.WARNING | Build succeeded
Level.CONFIG | Build started, task started/ended, target started/ended
Level.INFO | All other messages

Top