Where are classpath, path and pathelement documented in Ant version 1.8.0?

Question

I'm looking over the documentation that comes with Apache Ant version 1.8.0 and can't find where classpath, path and pathelement are documented. I've found a page that describes path like structures but it doesn't list the valid attributes or nested elements for these. Another thing I can't find in the documentation is a description of the relationships between filelist, fileset, patternset and path and how to convert them back and forth. For instance there has to be an easier way to compile only those classes in one package while removing all class dependencies on the package classes and update documentation.

<!-- Get list of files in which we're interested. -->
<fileset id = "java.source.set"
    dir     = "${src}">
  <include name = "**/Package/*.java" />
</fileset>

<!-- Get a COMMA separated list of classes to compile. -->
<pathconvert property = "java.source.list"
    refid             = "java.source.set"
    pathsep           = ",">
  <globmapper from = "${src}/*.@{src.extent}"
      to           = "*.class" />
</pathconvert>

<!-- Remove ALL dependencies on package classes. -->
<depend srcdir = "${src}"
    destdir    = "${build}"
    includes   = "${java.source.list}"
    closure    = "yes" />

<!-- Get a list of up to date classes. -->
<fileset id = "class.uptodate.set"
    dir     = "${build}">
  <include name = "**/*.class" />
</fileset>

<!-- Get list of source files for up to date classes. -->
<pathconvert property = "java.uptodate.list"
    refid             = "class.uptodate.set"
    pathsep           = ",">
  <globmapper from="${build}/*.class" to="*.java" />
</pathconvert>

<!-- Compile only those classes in package that are not up to date. -->
<javac srcdir    = "${src}"
    destdir      = "${build}"
    classpathref = "compile.classpath"
    includes     = "${java.source.list}"
    excludes     = "${java.uptodate.list}"/>

<!-- Get list of directories of class files for package. --:
<pathconvert property = "class.dir.list"
    refid             = "java.source.set"
    pathsep           = ",">
  <globmapper from = "${src}/*.java"
      to           = "${build}*" />
</pathconvert>

<!-- Convert directory list to path. -->
<path id  = "class.dirs.path">
  <dirset dir  = "${build}"
      includes = "class.dir.list" />
</path>

<!-- Update package documentation. -->
<jdepend outputfile = "${docs}/jdepend-report.txt">
  <classpath refid = "compile.classpath" />
  <classpath location = "${build}" />
  <classespath>
    <path refid = "class.dirs.path" />
  </classespath>
  <exclude name = "java.*"  />
  <exclude name = "javax.*" />
</jdepend>

Notice there's a number of conversions between filesets, paths and comma separated list just to get the proper 'type' required for the different ant tasks. Is there a way to simplify this while still processing the fewest files in a complex directory structure?

Varix

I wish I could up vote this more. The man pages for ant absolutely suck. They are worthless. – Wolford

Answer 1

This is the closest I could find to documentation on classpath.

http://ant.apache.org/manual/using.html#path

Shanks

Yea, I found that but it doesn't go into details. Specifically it does not say what attributes or nested elements are valid. – Varix

The ANT doco concentrates on tasks. The other parts you learn by osmosis :-) For example references took me a long time to figure out (ant.apache.org/manual/using.html#references) – Vatic

So this is a pretty unhelpful answer. Nothing but linking to documentation that doesn't actually have a solution in it either doesn't contribute much. – Cleanthes

Answer 2

Path:

This object represents a path as used by CLASSPATH or PATH environment variable. A path might also be described as a collection of unique filesystem resources.

and PathElement:

Helper class, holds the nested <pathelement> values.

are defined directly in the JavaDoc.

ClassPathis an implementation of AbstractClasspathResource:

A Resource representation of anything that is accessed via a Java classloader. The core methods to set/resolve the classpath are provided.

which is a direct subclass of Resource:

Describes a "File-like" resource (File, ZipEntry, etc.). This class is meant to be used by classes needing to record path and date/time information about a file, a zip entry or some similar resource (URL, archive in a version control repository, ...).

FileSet is defined as:

A FileSet is a group of files. These files can be found in a directory tree starting in a base directory and are matched by patterns taken from a number of PatternSets and Selectors.

Selectors is defined as:

Selectors are a mechanism whereby the files that make up a <fileset> can be selected based on criteria other than filename as provided by the <include> and <exclude> tags.

PatternSet is defined as:

Patterns can be grouped to sets and later be referenced by their id attribute. They are defined via a patternset element, which can appear nested into a FileSet or a directory-based task that constitutes an implicit FileSet. In addition, patternsets can be defined as a stand alone element at the same level as target — i.e., as children of project as well as as children of target.

FileList is defined as:

FileLists are explicitly named lists of files. Whereas FileSets act as filters, returning only those files that exist in the file system and match specified patterns, FileLists are useful for specifying files that may or may not exist. Multiple files are specified as a list of files, relative to the specified directory, with no support for wildcard expansion (filenames with wildcards will be included in the list unchanged). FileLists can appear inside tasks that support this feature or as stand-alone types.

In Schematron, you could validate this by the following:

  <sch:pattern>

      <sch:title>Check allowed elements</sch:title>

      <sch:rule context="target/*[name() =  ancestor::*/taskdef/@name]">

              <sch:assert  test="true()">

              The target element may contain user-defined tasks.

            </sch:assert>

      </sch:rule>

 </sch:pattern>         

References

• Types - Apache Ant Manual
• AntLib
• Apache Ant/Build File Structure - Wikibooks, open books for an open world
• Meeting new challenges with Ant1.7 (pdf)
• Ant Extending Ant
• Apache Ant - Apache AntUnit
• Validating Ant with Schematron
• Ant Script Visualizer

Epiphysis