Ant-taak API-gebruik

Doel

This task runs a complete search of a given baseline to create a report of API usage.

De analyse verwerkt geen bundels waarvoor API Tools niet is ingeschakeld.

Gebruik

Beschrijving

De naam van de ant-taak is apitooling.apiuse. Om deze te kunnen gebruiken, moet het JAR-bestand apitooling-ant.jar zich in het ant-klassenpad bevinden.

<apitooling.apiuse
	location="..."
	scopepattern="..."
	referencepattern="..."
	report="..."
	considerinternal="..."
	considerapi="..."
	considerillegaluse="..."
	apipatterns="..."
	internalpatterns="..."
	archivepatterns="..."
	excludelist="..."
	includelist="..."
			debug="..."
/>

Parameters

Kenmerk Beschrijving Verplicht
location Dit kenmerk geeft de locatie aan van het huidige product waarvoor u het API-gebruik wilt opzoeken.

It can be a .zip, .jar, .tgz, .tar.gz file, or a directory containing a product or a collection of bundles.

De locatie wordt opgegeven als absoluut pad.
True
scopepattern This attribute specifies a regular expression pattern used to select what bundles in the location will be searched.

For example, the following would only scan for API usage in Eclipse bundles:
org.eclipse.*
Het patroon moet een correct geformuleerde expressie zijn, zie hier.
Nee
referencepattern This attribute specifies a regular expression pattern used to filter the search results. Only API usage that references a bundle matching the filter will be reported.

For example, the following would only report usage that references code in JDT:
org.eclipse.jdt.*
Het patroon moet een correct geformuleerde expressie zijn, zie hier.
Nee
report Het instellen van de uitvoerlocatie waar de rapporten worden gegenereerd.

Als de taak is voltooid, zijn de rapporten in deze directory beschikbaar in een hiërarchische structuur. Er wordt een submap gemaakt voor alle componenten waarnaar een andere bundel verwijst. Elke submap bevat een bestand met de naam "[bundelnaam].xml". In deze map bevindt zich een submap (genaamd "[verwijsbundelnaam].xml") voor elke bundel die verwijst naar de bundel van de map. In de map van de verwijzende bundel bevindt zich een van drie submappen (API, PRIVATE en OTHER), die type-, methode- of veldverwijzingen bevatten.

Three other special files are written into the report directory, which are "counts.xml", "not_searched.xml" and "no_apidescription.xml" and they contain information about the number of references found, bundles from the baseline that were not search for usage information and those that did not have an .api_description files in them, respectively.

De locatie wordt opgegeven als absoluut pad.

Bijvoorbeeld:
  root
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- "counts.xml"
   +-- bundle name with usage
   		|
   		+--referencing bundle name
   			|
   			+-- [API or PRIVATE or OTHER]
   				|
   				+--[type_ or method_ or field_]references.xml
True
considerinternal Als in de zoekactie rekening gehouden moet worden met interne verwijzingen.

De standaardwaarde is false.
Nee
considerapi Als in de zoekactie rekening gehouden moet worden met API-verwijzingen.

De standaardwaarde is false.
Nee
considerillegaluse Als in de zoekactie rekening gehouden moet worden niet toegestane API-gebruiksverwijzingen.

De standaardwaarde is false.
Nee
apipatterns Een door komma's gescheiden lijst van pakketnaampatronen (expressies) om te beschouwen als API-pakketten.

Standaard worden API-beschrijvingen gebruikt in de gescande bundels, maar u kunt dit kenmerk gebruiken voor het negeren of toevoegen van API-pakketten.
Nee
internalpatterns Een door komma's gescheiden lijst van pakketnaampatronen (expressies) om te beschouwen als persoonlijke pakketten.

Standaard worden API-beschrijvingen gebruikt in de gescande bundels, maar u kunt dit kenmerk gebruiken voor het negeren of toevoegen van persoonlijke pakketten.
Nee
archivepatterns Een door komma's gescheiden lijst van archief-ID's die moeten worden genegeerd tijdens het scannen.

Een archief-ID heeft de notatie: [bundel-id]:[pad naar archief].
Nee
excludelist Instelling van de locatie van de uitsluitingslijst.

The exclude list location specifies a text file listing bundles to be excluded from the analysis. By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, all bundles are included), and the exclude list is then applied. Each line of the file specifies one of:
  • a specific bundle name
  • a regular expression to match against bundle names (lines being with "R:")
  • a comment (lines being with '#')

De locatie wordt opgegeven als absoluut pad.
Following is an example exclude list:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
Nee
includelist Set the include list location.

The include list location specifies a text file listing bundles to be included in the analysis. By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, all bundles are included), and the exclude list is then applied. Each line of the file specifies one of:
  • a specific bundle name
  • a regular expression to match against bundle names (lines being with "R:")
  • a comment (lines being with '#')

De locatie wordt opgegeven als absoluut pad.
Following is an example include list:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
Nee
filters Set the root directory of API filters to use during the use scan.

The argument is the root directory of the .api_filters files that should be used to filter references.

The .api_filters files specify specific problems to ignore during api analysis. During the use scan, the problem filters will be converted to a list of references that will be filtered from the use scan results.

De hoofddirectory wordt opgegeven als absoluut pad.
De hoofddirectory moet de volgende structuur hebben:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
Nee
debug Instellen van de foutopsporingswaarde.

De mogelijke waarden zijn true en false.
De standaardwaarde is false.
Nee

Voorbeelden

	<apitooling.apiuse
		location="/eclipse/eclipse.tar.gz"
		scopepattern=".*"
		referencepattern="org\.eclipse.*"
		report="/eclipse/apiuse-both/XML"
		considerinternal="true"
		considerapi="true"
		considerillegaluse="true"
		archivepatterns="org.eclipse.test.bundle:/libs/contributed.jar"
		excludelist="D:\exclude_list_external.txt"
		debug="true"
	/>

Hiermee wordt de taak gestart voor het maken van *.xml-bestanden in de map /eclipse/apiuse-both/XML. The task will search all bundles in the product location - defined by the regular expression .* - searching for all references to any bundles whose identifier begins with org.eclipse (defined by the org\.eclipse.* regular expression). It will use the exclude list file located in D:\exclude_list_external.txt to reduce the number of problems to report.

Tijdens het scannen worden klassenbestanden die worden aangetroffen in het /libs/contributed.jar-archief binnen org.eclipse.test.bundle genegeerd.

Als de foutopsporing is ingeschakeld, zijn er enige foutopsporingsgegevens te zien in de ant-console.

Verwante onderwerpen

Ant-taak API blokkeren
Ant-taak Bestanden genereren
Ant-taak Analyserapport converteren
Ant-taak API-blokkeringsrapport converteren
Ant-taak API-depreciëring
Ant-taak API-depreciëringsrapport converteren
Ant-taak API-gebruiksrapport converteren