Работа с пакетным компилятором (batch compiler)

Поиск пакетного компилятора

Класс пакетного компилятора находится в модуле JDT Core. Имя класса - org.eclipse.jdt.compiler.batch.BatchCompiler. Он находится в файле plugins/org.eclipse.jdt.core_<версия>.jar. Начиная с версии 3.2 его можно загрузить отдельно. Имя файла - ecj.jar. Также для загрузки доступен и соответствующий источник. Для получения файлов перейдите на страницу загрузки выполните поиск раздела Пакетный компилятор JDT Core (JDT Core Batch Compiler). В этом файле jar содержится пакетный компилятор и адаптер javac ant.

Начиная с версии 3.3, файл jar также содержит поддержку jsr199 (Компилятор API) и поддержку jsr269 (поддержка аннотирования).Для использования аннотирования требуется 1.6 VM.

Поэтому его можно использовать в качестве автономного приложения и внутри компиляции Ant за пределами Eclipse.

Запуск пакетного компилятора

Доступные опции

Рекомендованные опции выделены оранжевым.

Если отдельные параметры указаны несколько раз, то пакетный компилятор обрабатывает их слева направо. Если параметр предупреждения (-warn:....) указан без '+' или '-', то он переопределяет набор предупреждений, указанных ранее. Таким образом, такие параметры следует указывать перед другими вариантами параметра -warn.

Параметр -err: обрабатывается аналогичным образом.

Имя Формат
Опции Classpath
-bootclasspath <dir 1>;<dir 2>;...;<dir P> Список каталогов или файлов JAR для первоначальной загрузки файлов классов в компилятор. По умолчанию используются библиотеки рабочей виртуальной машины. Записи разделяются символов разделителя путей платформы.
В каждом каталоге или файле можно указать правила доступа для типов в квадратных скобках '[' и ']'.

Если bootclasspath не указан, компилятор использует в его качестве параметры sun.boot.class.path, vm.boot.class.path или org.apache.harmony.boot.class.path соответственно.

-cp
-classpath <dir 1>;<dir 2>;...;<dir P>
Список каталогов или файлов JAR, служащих для компиляции исходных файлов. Значение по умолчанию - значение свойства "java.class.path". Записи разделяются символов разделителя путей платформы.
В каждом каталоге или файле можно задать правила доступа к типам в квадратных скобках '[' и ']' (например, [-X] для запрета доступа к типу X, [~X] для рекомендации не использовать тип X, [+p/X:-p/*] для запрета доступа ко всем типам пакета p, за исключением p/X).
Компилятор следует операторам Class-Path манифестов файлов jar рекурсивно и добавляет каждый использованный файл jar в конец пути к классу, если его еще там нет.
-extdirs <dir 1>;<dir 2>;...;<dir P> Список каталогов с файлами расширений zip и jar. Записи разделяются символов разделителя путей платформы.
-endorseddirs <dir 1>;<dir 2>;...;<dir P> Список каталогов, в которых находятся расширяемые файлы zip/jar. Записи разделяются символов разделителя путей платформы.
-sourcepath <dir 1>;<dir 2>;...;<dir P> Список каталогов исходных файлов. Записи разделяются символов разделителя путей платформы.
В каждом каталоге можно задать правила доступа для типов в квадратных скобках '[' и ']'.
-d <dir 1>|none Расположение создаваемых файлов .class. Если оно не указано, структура каталогов пакетов не создается.
Чтобы отказаться от создания файла .class используйте -d none.
-encoding <кодировка> Укажите кодировку по умолчанию для всех исходных файлов. Можно также задавать кодировку для отдельных файлов, снабжая файлы или каталоги суффиксом [<кодировка>]. Например, X.java[utf8] задает кодировку UTF-8 для модуля компиляции X.java, расположенного в текущем каталоге пользователей.

Если задано несколько кодировок исходных файлов по умолчанию, то применяется последняя.

Пример:

  • ... -encoding UTF-8 X.java[Cp1252] Y.java[UTF-16] Z.java ....
    Все исходные файлы будут считаны с помощью кодировки UTF-8 (включая файл Z.java). X.java будет считан с помощью кодировки Cp1252, а Y.java - с помощью кодировки UTF-16.
  • ... -encoding UTF-8 -encoding UTF-16 ....
    Все исходные файлы будут считаны с помощью кодировки UTF-16. Опция -encoding для UTF-8 будет проигнорирована.
  • ... -encoding Cp1252 /foo/bar/X.java[UTF-16] /foo/bar[UTF-8] ....
    Все исходные файлы будут считаны с помощью кодировки Cp1252. X.java - это единственный файл в каталоге /foo/bar, который будет считан с помощью кодировки UTF-16. Все остальные файлы в этом каталоге будут использовать кодировку UTF-8.
Опции совместимости
-target 1.1 to 1.7 or (5, 5.0, etc) Параметры цели файлов .class. Допустимые значения:
  • 1.1 (версия major: 45 minor: 3)
  • 1.2 (версия major: 46 minor: 0)
  • 1.3 (версия major: 47 minor: 0)
  • 1.4 (версия major: 48 minor: 0)
  • 1.5, 5 или 5.0 (версия major: 49 minor: 0)
  • 1.6, 6 или 6.0 (версия major: 50 minor: 0)
  • 1.7, 7 или 7.0 (версия major: 51 minor: 0)
Значения по умолчанию:
  • 1.1 в режиме -1.3
  • 1.2 в режиме -1.4
  • 1.5 в режиме -1.5
  • 1.6 в режиме -1.6
  • 1.7 в режиме -1.7

clcd1.1 можно использовать для создания атрибута StackMap.

-1.3 Уровень совместимости 1.3. Подразумевает -source 1.3 -target 1.1.
-1.4 Уровень совместимости 1.4 (значение по умолчанию). Подразумевает -source 1.3 -target 1.2.
-1.5 Уровень совместимости 1.5. Подразумевает -source 1.5 -target 1.5.
-1.6 Уровень совместимости 1.6. Подразумевает -source 1.6 -target 1.6.
-1.7 Уровень совместимости 1.7. Подразумевает -source 1.7 -target 1.7.
-source 1.1 to 1.7 or (5, 5.0, etc) Используется для указания уровня источника, ожидаемого компилятором.
Допустимые значения:
  • 1.3
  • 1.4
  • 1.5, 5 или 5.0
  • 1.6, 6 или 6.0
  • 1.7, 7 или 7.0
Значения по умолчанию:
  • 1.3 в режиме -1.3
  • 1.3 в режиме -1.4
  • 1.5 в режиме -1.5
  • 1.6 в режиме -1.6
  • 1.7 в режиме -1.7
В режиме 1.4, assert считается ключевым словом. В режиме 1.5 и 1.6, enum и assert считаются ключевыми словами.
Опции предупреждений
-?:warn -help:warn Представляет дополнительные опции предупреждения
-warn:... Укажите набор активных предупреждений.
Например, -warn:unusedLocal,deprecation
-warn:none отключить все предупреждения
-warn:<маркеры предупреждений, перечисленные через ,> включить только указанные предупреждения
-warn:+<маркеры предупреждений, перечисленные через ,> включить дополнительные предупреждения
-warn:-<маркеры предупреждений, перечисленные через ,> отключить конкретные предупреждения
В столбце Default ниже знак "+/-" указывает на то, что опция предусматривает несколько вариантов более тонко настраиваемых предупреждений, одни из которых по умолчанию включены, а другие - отключены. То есть, знак "+", установленный для определенной опции, позволяет включить больше предупреждений по сравнению с установкой по умолчанию, а знак "-" отключает некоторые предупреждения, включенные по умолчанию.
стандартная Маркер Описание
+/- allDeadCode неиспользуемый код, включающий упрощенный код при проверке (DEBUG)
+/- allDeprecation устаревший фрагмент даже в устаревшем коде
- allJavadoc неверный или отсутствующий javadoc
- allOver-ann все отсутствующие аннотации @Override (суперкласс и интерфейсы суперкласса)
- all-static-method метод all может быть объявлен как статические предупреждения
+ assertIdentifier assert, используемое как идентификатор
- boxing преобразование автоматического приведения типов
+ charConcat массив char, используемый как строка в concat без явного преобразования к типу строки
+ compareIdentical сравнение идентичных выражений
- conditionAssign возможная ошибка булевского присваивания
+ constructorName метод с именем конструктора
+ deadCode неиспользуемый код, исключающий упрощенный код при проверке (DEBUG)
- dep-ann отсутствует аннотация @Deprecated
+/- deprecation использование устаревшего типа или элемента вне устаревшего кода
+ discouraged использование нерекомендованных типов
- emptyBlock недокументированный пустой блок
+ enumIdentifier enum используется как идентификатор
+ enumSwitch неполная информация перечисления в операторе switch
- enumSwitchPedantic сообщать об отсутствующих константах перечисления в switch даже при наличии блока default
- fallthrough возможный прецедент прохода
- fieldHiding поле скрывает другую переменную
+ finalBound параметр типа с ограничением final
+ finally ненормальное завершение блока finally
+ forbidden использование запрещенных типов
- hashCode метод hashCode() отсутствует при переопределении equals()
+/- hiding макрос для fieldHiding, localHiding, typeHiding и maskedCatchBlock
- includeAssertNull выдача предупреждений о пустых значениях переменных, поврежденных в выражениях ресурсов
- indirectStatic косвенная ссылка на статический элемент
+ intfAnnotation тип аннотации в качестве базового интерфейса
+ intfNonInherited совместимость неунаследованного метода интерфейса
- intfRedundant поиск избыточных суперинтерфейсов
- javadoc неверный javadoc
- localHiding локальная переменная скрывает другую переменную
+ maskedCatchBlock скрытый блок catch
- nls строковые литералы non-nls (без тегов //$NON-NLS-<n>)
+ noEffectAssign бесполезное присваивание
+/- null потенциальная отсутствующая или избыточная проверка на null
- nullAnnot включить анализ null на основе аннотаций.
Если это необходимо, типы аннотаций, интерпретируемые компилятором, можно указать, добавив (nullable|nonnull|nonnullbydefault) и обозначив каждый тип аннотации с использованием его полного имени.
См. также описание параметра nonNullByDefault ниже.
- nullDereference отсутствует проверка на null
- over-ann отсутствует аннотация @Override (только суперкласс)
- paramAssign присваивание параметру
+ pkgDefaultMethod переопределение метода по умолчанию пакета
+ raw применение непараметризованного типа (вместо параметризованного)
+/- resource (возможно) небезопасное использование ресурса типа Closeable
- semicolon ненужная точка с запятой или пустой оператор
+ serial отсутствует serialVersionUID
- specialParamHiding конструктор или параметр set скрывает другое поле
+/- static-access макрос для indirectStatic и staticReceiver
- статический метод метод экземпляра, который должен статическим
+ staticReceiver нестатический получатель служит для получения статического поля или вызова статического метода
- super переопределение метода без выполнения главного вызова
+ suppress включить @SuppressWarnings
- switchDefault в операторе switch отсутствует блок default
- syncOverride отсутствует "синхронный" в переопределении синхронного метода
- syntheticAccess синтетический доступ к внутреннему классу
- tasks включить поддержку тегов задач в исходном коде
+ typeHiding тип параметра скрывает другой тип
+ unavoidableGenericProblems игнорировать неизбежные неполадки безопасности типов из-за поточных API
+ Не отмечена операция с непроверенным типом
- unnecessaryElse ненужный оператор else
- unqualifiedField нетипизированная ссылка на поле
+/- unused макрос для unusedAllocation, unusedArgument, unusedImport, unusedLabel, unusedLocal, unusedPrivate, unusedThrown и unusedTypeArgs
- unusedAllocation выделение неиспользуемого объекта
- unusedArgument неиспользуемый аргумент метода
+ unusedImport неиспользуемая директива import
+ unusedLabel неиспользуемая метка
+ unusedLocal неиспользуемая локальная переменная
+ unusedPrivate объявление неиспользуемого элемента private
- unusedThrown неиспользуемая объявленная исключительная ситуация
+ unusedTypeArgs неиспользуемый тип аргументов для метода и конструктора
- uselessTypeCheck ненужный оператор cast/instanceof
+ varargsCast аргумент с переменным числом аргументов требует явного приведения
+/- warningToken маркер необрабатываемого или неиспользуемого предупреждения в @SuppressWarnings
-nowarn Не показывать предупреждения (аналогично -warn:none)
-err:... Укажите набор предупреждений для преобразования в ошибки.
Например, -err:unusedLocal,deprecation
Предупреждения unusedLocal и deprecation преобразуются в ошибки. Все остальные предупреждения отображаются как предупреждения.
-err:<маркеры предупреждений, перечисленные через ,> преобразовать указанные предупреждения в ошибки
-err:+<маркеры предупреждений, перечисленные через ,> преобразовать дополнительные предупреждения в ошибки
-err:-<маркеры предупреждений, перечисленные через ,> удалить конкретные предупреждения из числа подлежащих преобразованию в ошибки
-deprecation Аналогично -warn:+deprecation.
-properties <файл> Укажите опцию ошибок/предупреждений с учетом содержимого файла свойств. Эту опцию можно указывать вместе с опциями -nowarn, -err:.. или -warn:.. , однако для настройки параметров используется та опция, которая указана в команде последней.

Файл свойств можно создать путем настройки параметров проекта в существующем проекте java, используя файл .settings/org.eclipse.jdt.core.prefs в качестве файла свойств. Кроме того, можно создать простой текстовый файл, добавив в него пары свойство/значение с учетом констант из класса org.eclipse.jdt.core.JavaCore.

...
org.eclipse.jdt.core.compiler.problem.annotationSuperInterface=warning
org.eclipse.jdt.core.compiler.problem.assertIdentifier=warning
org.eclipse.jdt.core.compiler.problem.autoboxing=ignore
...
Опции отладки
-g[:none|:lines,vars,source] Уровень атрибутов отладки
-g Вся отладочная информация (аналогично -g:lines,vars,source)
-g:none Не показывать отладочную информацию
-g:[lines,vars,source] Показывать избранную отладочную информацию
-preserveAllLocals Явным образом указать компилятору необходимость сохранения локальных переменных для отладки. При отсутствии этого атрибута компилятор удалит все локальные переменные.
Аннотирование опций обработки (требует 1.6 VM или выше и используется только если есть соответствие с 1.6)
-Akey[=значение] Опции процессора аннотаций. key состоит из идентификаторов, разделенных точками
-proc:[only|none] Если указан параметр -proc:only, процессор аннотаций будет запущен, но не будет выполнять компилирование. Если задано значение -proc:none, процессор аннотаций не будет обнаружен или запущен; компиляция будет выполнена так, как если процессор аннотаций не был бы найден. По умолчанию компилятор должен искать classpath для процессора аннотаций, поэтому указание значения -proc:none может ускорить компиляцию, если обработка аннотаций не требуется.
-processor <класс1[,класс2,...]> Полное имя класса запускаемого процессора аннотаций. Если указано, процесс поиска процессора будет пропущен.
-processorpath <каталог 1>;<каталог 2>;...;<каталог P> Список каталогов или файлов jar, поиск которых будет производиться для процессора аннотаций. Записи разделяются символов разделителя путей платформы. Если значение не задано, будет выполнен поиск classpath.
-s <каталог> Каталог, в котором будут сохранены созданные исходные файлы.
-XprintProcessorInfo Напечатать информацию об аннотациях и элементах, запрашиваемых процессором для работы
-XprintRounds Напечатать информацию о циклах обработки аннотаций
-classNames <класс-1[,класс-2,...]> Квалифицированные имена обрабатываемых бинарных типов
Игнорируемые опции (для опций совместимости с javac)
-J<опция> Передает опцию виртуальной системе
-X<опция> Задает нестандартную опцию. -Xemacs не игнорируется.
-X Печать нестандартных опций и выход
-O Оптимизация для времени выполнения
Дополнительные опции
@<file> Загрузить аргументы командной строки из файла
-maxProblems <n> Максимальное число ошибок в модуле компиляции (по умолчанию 100)
-log <имя-файла> Файл протокола для вывода компилятора. Полезная опция при отладке пакетного компилятора для получения файла со всеми ошибками и предупреждениями пакетной компоновки. Если расширение - это .xml, файл протокола будет создан в формате xml.
-Xemacs Использует стиль emacs для представления расположений ошибок и предупреждений в протоколах консоли и обычных текстовых протоколах. Не влияет на протоколы XML. При включении этой опции сообщение:
2. ПРЕДУПРЕЖДЕНИЕ в /workspace/X.java
(строка 8)...

отображается как:
/workspace/X.java:8: предупреждение: Метод...
-proceedOnError[:Fatal] Продолжить компиляцию при возникновении ошибок, выводя файлы классов с ошибками в методах или типах. Рекомендуется только в том случае, если требуется запустить приложение даже при наличии оставшихся ошибок.
Если указан аргумент ":Fatal", то все дополнительные ошибки рассматриваются как неустранимые; в результате выполнение кода прерывается каждый раз при обнаружении ошибки. Без аргумента ":Fatal" дополнительные ошибки не влияют на создание кода и полученные файлы .class могут работать правильным образом.
-verbose Показывать в консоли обрабатываемые модули компиляции или записывать их в файл протокола.
-referenceInfo Обработать информацию ссылок. Полезно только в связке с компоновщиком. Во всех других случаях информация о ссылках бесполезна.
-progress Показать ход выполнения (только в режиме -log ).
-time Показать данные о быстродействии.
-noExit Не вызывать System.exit(n) по завершении компиляции (n=0, если нет ошибок ).
-repeat <n> Повторить процесс компиляции <n> раз (анализ быстродействия).
-inlineJSR Встроить байт-код JSR (задано неявно для целей >= 1.5).
-enableJavadoc Учитывать ссылки внутри javadoc.
-missingNullDefault Если включен анализ null на основе аннотаций (см. описание "nullAnnot" выше), эта опция выдает предупреждение каждый раз при отсутствии аннотации по умолчанию в пакете или типе.
Опции справки
-? -help Показать справочную информацию.
-v -version Показать номер сборки компилятора. Полезно при сообщениях об ошибках.
-showversion Показать номер сборки компилятора и продолжить. Полезно при сообщениях об ошибках.

Примеры

d:\temp -classpath rt.jar -time -g -d d:/tmp Скомпилировать все исходные файлы в d:\temp и ее подпапках. classpath - это rt.jar. Будут созданы все атрибуты отладки, а файлы .class будут записаны в d:\tmp. По окончании пакетной операции будет показана скорость работы компилятора.
d:\temp\Test.java -classpath d:\temp;rt.jar -g:none Компилирует только Test.java и зависимые файлы при их наличии, извлекая зависимые файлы из каталога d:\temp. Classpath - это d:\temp и rt.jar, что означает, что требуемые классы сначала просматриваются в d:\temp и затем в rt.jar. Никакие атрибуты отладки не создаются, а файлы .class будут записаны в d:\temp.