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

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.

(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-allThe 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-allObviously, 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:

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:

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:

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.ERRORBuild failed
Level.WARNINGBuild succeeded
Level.CONFIGBuild started, task started/ended, target started/ended
Level.INFOAll other messages
Top