Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "PDE/API Tools/Tasks"
Line 1: | Line 1: | ||
+ | == API Tooling Ant Tasks == | ||
+ | |||
API Tools provides a number of tasks to integrate the tooling into your releng builds. They are available in the <code>org.eclipse.pde.api.tools bundle</code>. The jarred task code <code>apitooling-ant.jar</code> must be on the Ant classpath. | API Tools provides a number of tasks to integrate the tooling into your releng builds. They are available in the <code>org.eclipse.pde.api.tools bundle</code>. The jarred task code <code>apitooling-ant.jar</code> must be on the Ant classpath. | ||
Line 10: | Line 12: | ||
There are [[#Examples|example ant build files]] at the bottom of this page. | There are [[#Examples|example ant build files]] at the bottom of this page. | ||
− | == Analysis Task== | + | == Task Descriptions == |
+ | |||
+ | === Analysis Task === | ||
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-ant-task.htm Official Documentation] | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-ant-task.htm Official Documentation] | ||
Line 20: | Line 24: | ||
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-reportconversion-ant-task.htm Analysis Report Conversion] - The report conversion task converts the XML reports created by the Analysis Ant task into an HTML report. | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/analysis-reportconversion-ant-task.htm Analysis Report Conversion] - The report conversion task converts the XML reports created by the Analysis Ant task into an HTML report. | ||
− | == API Freeze Task == | + | === API Freeze Task === |
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-ant-task.htm Official Documentation] | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-ant-task.htm Official Documentation] | ||
Line 28: | Line 32: | ||
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-reportconversion-ant-task.htm API Freeze Report Conversion] - The report conversion task converts the XML reports created by the API Freeze Ant task into an HTML report. | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apifreeze-reportconversion-ant-task.htm API Freeze Report Conversion] - The report conversion task converts the XML reports created by the API Freeze Ant task into an HTML report. | ||
− | == API Deprecation Task == | + | === API Deprecation Task === |
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-ant-task.htm Official Documentation] | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-ant-task.htm Official Documentation] | ||
Line 36: | Line 40: | ||
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-reportconversion-ant-task.htm API Deprecation Report Conversion] - The report conversion task converts the XML reports created by the API Deprecation Ant task into an HTML report. | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/deprecation-reportconversion-ant-task.htm API Deprecation Report Conversion] - The report conversion task converts the XML reports created by the API Deprecation Ant task into an HTML report. | ||
− | == API Use Task== | + | === API Use Task === |
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-ant-task.htm Official Documentation] | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-ant-task.htm Official Documentation] | ||
Line 46: | Line 50: | ||
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-reportconversion-ant-task.htm API Use Report Conversion] - The report conversion task converts the XML reports created by the API Use Ant task into an HTML report. | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apiuse-reportconversion-ant-task.htm API Use Report Conversion] - The report conversion task converts the XML reports created by the API Use Ant task into an HTML report. | ||
− | == API Use Migration Task == | + | === API Use Migration Task === |
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-ant-task.htm Official Documentation] | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-ant-task.htm Official Documentation] | ||
Line 54: | Line 58: | ||
[http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-reportconversion-ant-task.htm API Use Migration Report Conversion] - The report conversion task converts the XML reports created by the API Use Migration Ant task into an HTML report. | [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.pde.doc.user/reference/api-tooling/ant-tasks/apimigration-reportconversion-ant-task.htm API Use Migration Report Conversion] - The report conversion task converts the XML reports created by the API Use Migration Ant task into an HTML report. | ||
− | == File Generation Task == | + | === File Generation Task === |
This task runs to generate all files required by API Tooling inside a binary bundle. This task is run during the Eclipse builds or during the bundle export for all projects that have an API Tooling nature. | This task runs to generate all files required by API Tooling inside a binary bundle. This task is run during the Eclipse builds or during the bundle export for all projects that have an API Tooling nature. |
Revision as of 15:05, 24 November 2010
API Tooling Ant Tasks
API Tools provides a number of tasks to integrate the tooling into your releng builds. They are available in the org.eclipse.pde.api.tools bundle
. The jarred task code apitooling-ant.jar
must be on the Ant classpath.
If you are running the tasks from an Eclipse target workspace, you must preface the task name with apitooling.
. When running the ant task directly, just the task name is required. If the task name is incorrect, you will get the following error:
/target/Project/build.xml:15:
Problem: failed to create task or type apideprecation
Cause: The name is undefined.
For documentation on task parameters and results see our official documentation.
There are example ant build files at the bottom of this page.
Task Descriptions
Analysis Task
This task runs a complete API analysis of an API profile relative to a baseline - including API use, binary compatibility, and bundle version number validation. The profile is the current state of a product under development. The profile is compared to an API baseline for binary compatibility (usually the previous release of a product).
The analysis does not include @since tag validation as all verification is performed on binary class files (source is not analyzed).
Analysis Report Conversion - The report conversion task converts the XML reports created by the Analysis Ant task into an HTML report.
API Freeze Task
This task identifies APIs that have been added, modified, or removed relative to an API baseline. This task is intended to validate no API changes occur after an API freeze.
API Freeze Report Conversion - The report conversion task converts the XML reports created by the API Freeze Ant task into an HTML report.
API Deprecation Task
This task runs a complete API analysis of an API profile relative to a baseline - looking only for members (classes, fields, methods) that have been deprecated / un-deprecated. The profile is the current state of a product under development. The profile is compared to an API baseline for deprecation changes (usually the previous release of a product).
API Deprecation Report Conversion - The report conversion task converts the XML reports created by the API Deprecation Ant task into an HTML report.
API Use Task
This task runs a complete search of a given baseline to determine a producer-centric report of API usage.
The analysis does not include bundles that are not API Tools enabled.
API Use Report Conversion - The report conversion task converts the XML reports created by the API Use Ant task into an HTML report.
API Use Migration Task
This task takes a given API use scan and tries to re-resolve it within a given candidate product release and reports any unresolved references.
API Use Migration Report Conversion - The report conversion task converts the XML reports created by the API Use Migration Ant task into an HTML report.
File Generation Task
This task runs to generate all files required by API Tooling inside a binary bundle. This task is run during the Eclipse builds or during the bundle export for all projects that have an API Tooling nature.
Right now, only the file called .api_description is created.
Examples
Example ant build files for the various tasks.
Analysis Task
<?xml version="1.0" encoding="UTF-8"?> <project name="project" default="default"> <property name="xml" value="/reports/analysis/xml"/> <property name="html" value="/reports/analysis/html"/> <property name="profile" value="/eclipse/eclipse/plugins"/> <property name="baseline" value="/eclipse/eclipse_3.6.2/plugins"/> <property name="prefs" value="/settings/analysis/prefs.properties"/> <property name="filters" value="/settings/analysis/.api_filters"/> <target name="default"> <analysis baseline="${baseline}" profile="${profile}" report="${xml}" preferences="${prefs}" filters="${filters}" debug="true" /> <analysis_reportconversion xmlfile="${xml}" htmlfile="${html}" debug="true" /> </target> </project>
API Freeze Task
<?xml version="1.0" encoding="UTF-8"?> <project name="project" default="default"> <property name="xml" value="/reports/freeze/xml"/> <property name="html" value="/reports/freeze/html"/> <property name="profile" value="/eclipse/eclipse/plugins"/> <property name="baseline" value="/eclipse/eclipse_3.6.2/plugins"/> <target name="default"> <apifreeze baseline="${baseline}" profile="${profile}" report="${xml}" debug="true" /> <apifreeze_reportconversion xmlfile="${xml}" htmlfile="${html}" debug="true" /> </target> </project>
API Deprecation Task
<?xml version="1.0" encoding="UTF-8"?> <project name="project" default="default"> <property name="xml" value="/reports/deprecation/xml"/> <property name="html" value="/reports/deprecation/html"/> <property name="profile" value="/eclipse/eclipse/plugins"/> <property name="baseline" value="/eclipse/eclipse_3.6.2/plugins"/> <target name="default"> <apideprecation baseline="${baseline}" profile="${profile}" report="${xml}" debug="true" /> <apideprecation_reportconversion xmlfile="${xml}" htmlfile="${html}" debug="true" /> </target> </project>
API Use Task
<project name="project" default="default"> <property name="xml" value="/reports/use/xml"/> <property name="html" value="/reports/use/html"/> <property name="exclude.list" value="/reports/settings/exclude.txt"/> <property name="include.list" value="/reports/settings/include.txt"/> <property name="scope.pattern" value=".*"/> <property name="ref.pattern" value=".*"/> <property name="api.pattern" value="org.mybundle.package.*"/> <property name="internal.pattern" value="org.mybundle.internal.package.*.*"/> <target name="default"> <apiuse considerinternal="true" considerillegaluse="true" excludelist="${exclude.list}" includelist="${include.list}" report="${xml}" referencepattern="${ref.pattern}" scopepattern="${scope.pattern}" apipatterns="${api.pattern}" internalpatterns="${internal.pattern}" debug="true" /> <apiuse_reportconversion xmlfiles="${xml}" htmlfiles="${html}" debug="true" /> </target> </project>
API Use Migration Task
<?xml version="1.0" encoding="UTF-8"?> <project name="project" default="default"> <property name="xml" value="/reports/migration/xml"/> <property name="html" value="/reports/migration/html"/> <property name="exclude.list" value="/reports/settings/exclude.txt"/> <property name="include.list" value="/reports/settings/include.txt"/> <property name="scope.pattern" value=".*"/> <property name="ref.pattern" value=".*"/> <property name="scan" value="/reports/use-3.6.2/xml"/> <property name="candidate" value="/eclipse/eclipse-3.7/plugins"/> <target name="default"> <apimigration excludelist="${exclude.list}" includelist="${include.list}" usescan="${scan}" candidate="${candidate}" scopepattern="${scope.pattern}" referencepattern="${ref.pattern}" report="${xml}" debug="true" /> <apimigration_reportconversion xmlfiles="${xml}" htmlfiles="${html}" debug="true" /> </target> </project>
File Generation Task
<?xml version="1.0" encoding="UTF-8"?> <project name="project" default="default"> <property name="project.name" value="api.tools.generation"/> <property name="bin" value="/eclipse/org.eclipse.pde.api.tools/bin:/eclipse/org.eclipse.pde.api.tools/antbin"/> <property name="src" value="/eclipse/org.eclipse.pde.api.tools/src"/> <property name="target" value="/eclipse/plugins/org.eclipse.pde.api.tools"/> <property name="manifests" value="/eclipse/my.bundle/MANIFEST.MF:/eclipse/my.bundle.2/MANIFEST.MF"/> <target name="default"> <apigeneration projectname="${project.name}" project="${src}" binary="${bin}" target="${target}" extramanifests="${manifests}" debug="true" /> </target> </project>