Задача Ant анализа API

Назначение

Эта задача выполняет полный анализ профайла API относительно контрольной версии, включая использование API, двоичную совместимость и проверку номера версии комплекта. Профайл - это текущее состояние продукта, находящегося в разработке. Профайл сравнивается с контрольной версией API на двоичную совместимость (обычно предыдущий выпуск продукта).

Анализ не включает в себя проверку тега @since, так как эта проверка выполняется в двоичных файлах класса (исходный файл не анализируется).

Формат

Описание

Именем задачи Ant является apitooling.analysis. Для использования JAR-файла apitooling-ant.jar он должен находиться в classpath Ant.

<apitooling.analysis
	baseline="..."
	profile="..."
	report="..."
	filters="..."
	excludelist="..."
	includelist="..."
	preferences="..."
	debug="..."
	eefile="..."
/>

Параметры

Атрибут Описание Обязательный
baseline Этот атрибут задает расположение справочной контрольной версии.

Это может быть файл .zip, .jar, .tgz, .tar.gz или каталог, который соответствует каталогу установки Eclipse. Это каталог, в котором находятся исполняемые файлы Eclipse.

Расположение задается с помощью абсолютного пути.
Да
profile Этот атрибут задает расположение текущего продукта или профайла, который вы хотите сравнить со справочной контрольной версией.

Это может быть файл .zip, .jar, .tgz, .tar.gz или каталог, который соответствует каталогу установки Eclipse. Это каталог, в котором находятся исполняемые файлы Eclipse.

Расположение задается с помощью абсолютного пути.
Да
report Установите расположение вывода, в котором будут генерироваться отчеты.

После выполнения задачи отчеты становятся доступными в этом каталоге с помощью структуры, подобной корневому фильтру. Подпапка создается для каждого компонента, который имеет неполадки. Каждая подпапка содержит файл с именем "report.xml".

В этой папке также создается специальная папка по имени "allNonApiBundles", которая содержит файл "report.xml". В этом файле перечислены все комплекты, которые не используют классификатор Инструменты API.

Также в каталоге отчета создается файл "counts.xml", содержащий сводную информацию о найденных ошибках.

Расположение задается с помощью абсолютного пути.
Да
filters Установите корневой каталог фильтров API, используемых в процессе анализа.

Аргумент - это корневой каталог файлов .api_filters, который должен использоваться для фильтрации потенциальных неполадок, созданных при анализе инструмента API.
Корневой каталог задается с помощью абсолютного пути.
В корневом каталоге должна содержаться следующая структура:
 root
  |
  +-- имя компонента (например, org.eclipse.jface)
         |
         +--- .api_filters
Нет
excludelist Установите расположение списка исключений.

Расположение списка исключения указывает текстовый файл, в котором перечислены комплекты, подлежащие исключению из анализа. По умолчанию анализируются все комплекты профайла. Атрибуты списка включения и списка исключения можно использовать для выборочного включения и исключения комплектов. Список включения задает набор комплектов для анализа (если не указан, включаются все комплекты), затем применяется список исключения. Каждая строка файла задает один из следующих элементов:
  • имя определенного комплекта
  • регулярное выражение для поиска совпадений с именами комплектов (строки с "R:")
  • комментарий (строки с '#')

Расположение задается с помощью абсолютного пути.
Пример списка исключения:
 # DOC BUNDLES
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 org.eclipse.platform.doc.isv
 org.eclipse.platform.doc.user
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
Нет
includelist Задайте расположение списка включения.

Расположение списка включения указывает текстовый файл, в котором перечислены комплекты, подлежащие включению в анализ. По умолчанию анализируются все комплекты профайла. Атрибуты списка включения и списка исключения можно использовать для выборочного включения и исключения комплектов. Список включения задает набор комплектов для анализа (если не указан, включаются все комплекты), затем применяется список исключения. Каждая строка файла задает один из следующих элементов:
  • имя определенного комплекта
  • регулярное выражение для поиска совпадений с именами комплектов (строки с "R:")
  • комментарий (строки с '#')

Расположение задается с помощью абсолютного пути.
Пример списка включения:
 # DOC BUNDLES
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 R:org.eclipse.platform.doc.*
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
Нет
параметры Установите параметры для задачи.

Параметры используются для настройки серьезности неполадки. Серьезность неполадки может принимать одно из трех значений: Ignore, Warning или Error. Набор обнаруженных неполадок определяется соответствующими ключами атрибутов неполадок в инструментах API.
Расположение задается с помощью абсолютного пути. Если данной расположение не существует, параметры не будут установлены.
Строки, начинающиеся с символа '#', игнорируются. Формат файла параметров имеет следующий вид:
 #Thu Nov 20 17:35:06 EST 2008
 ANNOTATION_ELEMENT_TYPE_ADDED_METHOD_WITHOUT_DEFAULT_VALUE=Ignore
 ANNOTATION_ELEMENT_TYPE_CHANGED_TYPE_CONVERSION=Ignore
 ANNOTATION_ELEMENT_TYPE_REMOVED_FIELD=Ignore
 ANNOTATION_ELEMENT_TYPE_REMOVED_METHOD=Ignore
 ANNOTATION_ELEMENT_TYPE_REMOVED_TYPE_MEMBER=Warning
 API_COMPONENT_ELEMENT_TYPE_REMOVED_API_TYPE=Ignore
 API_COMPONENT_ELEMENT_TYPE_REMOVED_TYPE=Ignore
 CLASS_ELEMENT_TYPE_ADDED_METHOD=Error
 CLASS_ELEMENT_TYPE_ADDED_RESTRICTIONS=Ignore
 CLASS_ELEMENT_TYPE_ADDED_TYPE_PARAMETER=Ignore
 CLASS_ELEMENT_TYPE_CHANGED_CONTRACTED_SUPERINTERFACES_SET=Ignore
 ...
Ключи находятся в org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
Нет
debug Установите значение отладки.

Возможны следующие значения: true, false
Значение по умолчанию - false.
Нет
eefile Задает используемый файл среды выполнения.

По умолчанию используется файл среды выполнения JavaSE-1.6.

Формат файла описан на этой странице вики.

Файл задается с помощью абсолютного пути.
Нет

Примеры

	<apitooling.analysis
		baseline="D:\eclipse\3.4.1\eclipse"
		profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"
		report="D:\reports\xml"
		filters="D:\filters"
		excludelist="D:\exclude_list_external.txt"
		preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs"
		debug="true"
	/>

Выполнится задача, создающая файлы report.xml в папке D:\reports\xml. Будет использоваться список исключения и файлы .api_filter, расположенные в папках D:\exclude_list_external.txt и D:\filters, для того чтобы уменьшить количество неполадок в отчете.

Серьезность неполадки будет генерироваться, как указано в D:\tests_api\org.eclipse.pde.api.tools.prefs.

После включения отладки некоторая информация трассировки будет показана на консоли Ant.

Связанные ссылки

Задача Ant фиксации состояния API
Задача Ant генерации файла
Задача Ant использования API
Задача Ant преобразования отчета об анализе
Задача Ant преобразования отчета о фиксации состояния API
Задача Ant преобразования отчета об использовании API
Задача Ant об устаревшем API
Задача Ant преобразования отчета об устаревшем API