API Tools File Generation Ant Task

Purpose

This task runs to generate all files required by API Tools inside a binary bundle. This task is run during the Eclipse builds or during the bundle export for all projects that have an API Tools nature.

Right now, only the file called .api_description is created.

Usage

Description

The name of the Ant task is: apitooling.apigeneration. To be used, the jar file apitooling-ant.jar has to be on the Ant classpath.

<apitooling.apigeneration
	projectname="..."
	project="..."
	binary="..."
	target="..."
	encoding="..."
	debug="..."
/>

Parameters

Attribute Description Required
projectname Set the project name Yes
project Set the project location.

This is the folder that contains all the source files for the given project.

The location is set using an absolute path.
Yes
binary Set the binary locations.

This is a list of folders or jar files that contain all the .class files for the given project. They are separated by the platform path separator. Each entry must exist.

They should be specified using absolute paths.
Yes
target Set the target location.

This is the folder in which the generated files are generated.

The location is set using an absolute path.
Yes
encoding Set the file encoding.

This is the file encoding to use while reading source files during the generation. If an encoding is not specified the system property file.encoding will be used.

The specified encoding is not checked to ensure it is valid in any way and an invalid encoding will cause an UnsupportedEncodingException to be thrown from the Ant task.
No
debug Set the debug value.

The possible values are: true, false
Default is false.
No
extramanifests Set the extra manifest files' locations.

This is a list of extra MANIFEST.MF files' locations that can be set to provide more api packages to scan. They are separated by the platform path separator. Each entry must exist.

If the path is not absolute, it will be resolved relative to the current working directory.

Jar files can be specified instead of MANIFEST.MF file. If a jar file is specified, its MANIFEST.MF file will be read if it exists.
No
extrasourcelocations Set the extra source locations.

This is a list of locations for source files that will be scanned. They are separated by the platform path separator. Each entry must exist.

They should be specified using absolute paths.
No
allownonapiproject Allow the task to run on non-API Tools enabled projects.

If this task is run on a project that does not have an API Tools nature, no api_description file will be generated as it is assumed that the project does not support API Tools. In some cases there is a need to generate the description file on projects without the nature. Setting this parameter to true will cause the task to not check for a nature.
No

Examples

 <apitooling.apigeneration
  projectname="org.eclipse.jdt.core_3.5.0.v_927"
  project="d:\eclipse\org.eclipse.jdt.core"
  binary="d:\eclipse\org.eclipse.jdt.core\bin;d:\eclipse\org.eclipse.jdt.core\antbin"
  target="d:\plugins\org.eclipse.jdt.core"
  encoding="UTF-8"
  allownonapiproject="true"
  debug="true"
 />

This will create a file called .api_description inside the folder d:\plugins\org.eclipse.jdt.core based on the source contained in d:\eclipse\org.eclipse.jdt.core and the .class files contained in d:\eclipse\org.eclipse.jdt.core\bin.

Related reference

Analysis Ant Task
API Freeze Ant Task
API Use Ant Task
Analysis Report Conversion Ant Task
API Freeze Report Conversion Ant Task
API Deprecation Ant Task
API Deprecation Report Conversion Ant Task
API Use Report Conversion Ant Task