Korzystanie z kompilatora wsadowego

Znajdowanie kompilatora wsadowego

Klasa kompilatora wsadowego znajduje się we wtyczce podstawowego modułu narzędzi JDT. Nazwa tej klasy to org.eclipse.jdt.compiler.batch.BatchCompiler. Znajduje się w pakiecie plugins/org.eclipse.jdt.core_<wersja>.jar. Od wersji 3.2 jest również dostępna jako osobny plik do pobrania. Plik nosi nazwę ecj.jar. Dostępny jest również jej kod źródłowy. Aby uzyskać te pliki, należy przejść na stronę pobierania i wyszukać sekcję Kompilator wsadowy JDT Core. Ten plik JAR zawiera kompilator wsadowy i adapter Ant javac.

Od wersji 3.3, ten plik JAR zawiera również funkcje obsługi jsr199 (interfejsu API kompilatora) oraz jsr269 (przetwarzania adnotacji). Do korzystania z obsługi przetwarzania adnotacji niezbędna jest maszyna VM w wersji 1.6.

Może być zatem używany jako aplikacja autonomiczna i wewnątrz kompilacji narzędzia Ant poza środowiskiem Eclipse.

Uruchamianie kompilatora wsadowego

Dostępne opcje

Zalecane opcje są wyróżnione pomarańczowym tłem.

Jeśli niektóre opcje zostaną określone wiele razy, kompilator wsadowy wykorzysta je kolejno od lewej do prawej. Jeśli opcja ostrzeżeń (-warn:....) zostanie użyta bez znaku + lub -, spowoduje to przesłonięcie uprzednio zdefiniowanego zestawu ostrzeżeń. Oznacza to, że użytkownik powinien się upewnić, że taka opcja zostanie określona przed dowolnym innym użyciem opcji -warn.

To samo dotyczy opcji -err:.

Nazwa Opis
Opcje ścieżki klas
-bootclasspath <kat 1>;<kat 2>;...;<kat P> Lista katalogów lub plików JAR służących do inicjowania plików klas używanych przez kompilator. Domyślnie używane są biblioteki działającej maszyny wirtualnej. Poszczególne pozycje są rozdzielone separatorem ścieżek dla danej platformy.
Każdy katalog lub plik może określać reguły dostępu do typów zawartych w nawiasach [ i ].

Jeśli nie zostanie podana startowa ścieżka klas, kompilator wyprowadzi ją na podstawie następujących właściwości systemu: sun.boot.class.path, vm.boot.class.path lub org.apache.harmony.boot.class.path, w tej kolejności.

-cp
-classpath <kat 1>;<kat 2>;...;<kat P>
Lista katalogów lub plików JAR służących do kompilowania plików źródłowych. Wartością domyślną jest wartość właściwości java.class.path. Poszczególne pozycje są rozdzielone separatorem ścieżek dla danej platformy.
Każdy katalog lub plik może określać reguły dostępu do typów zawartych w nawiasach [ i ] (np. [-X] oznacza zakaz dostępu do typu X, [~X] oznacza, że dostęp do typu X jest niewskazany, [+p/X:-p/*] oznacza, że dostęp do wszystkich typów w pakiecie p jest zabroniony, ale dostęp do typu p/X jest dozwolony).
Kompilator rekurencyjnie wykonuje instrukcje z klauzul Class-Path w manifestach plików JAR i dołącza każdy przywoływany plik JAR na końcu ścieżki klas, o ile ten plik nie znajduje się już w ścieżce klas.
-extdirs <kat 1>;<kat 2>;...;<kat P> Lista katalogów służących do określania położenia plików ZIP/JAR rozszerzenia. Poszczególne pozycje są rozdzielone separatorem ścieżek dla danej platformy.
-endorseddirs <kat 1>;<kat 2>;...;<kat P> Lista katalogów służących do określania położenia promowanych plików ZIP/JAR. Poszczególne pozycje są rozdzielone separatorem ścieżek dla danej platformy.
-sourcepath <kat 1>;<kat 2>;...;<kat P> Lista katalogów służących do określania położenia plików źródłowych. Poszczególne pozycje są rozdzielone separatorem ścieżek dla danej platformy.
Każdy katalog może określać reguły dostępu do typów zawartych w nawiasach [ i ].
-d <kat 1>|none Służy do określania katalogu, do którego mają zostać zrzucone wygenerowane pliki .class. Jeśli zostanie pominięta, nie zostanie utworzona struktura katalogów pakietu.
Jeśli w ogóle nie chcesz generować pliku .class, użyj opcji -d none.
-encoding <nazwa kodowania> Określa domyślne kodowanie wszystkich plików źródłowych. Dla poszczególnych plików można również określać kodowanie niestandardowe, dodając do każdej nazwy wejściowego pliku/folderu źródłowego przyrostek [<nazwa kodowania>]. Na przykład zapis X.java[utf8] spowoduje określenie kodowania UTF-8 dla jednostki kompilacji X.java umieszczonej w bieżącym katalogu użytkownika.

W przypadku określenia wielu domyślnych kodowań plików źródłowych zostanie użyte ostatnie.

Na przykład:

  • ... -encoding UTF-8 X.java[Cp1252] Y.java[UTF-16] Z.java ....
    Wszystkie pliki źródłowe zostaną odczytane z użyciem kodowania UTF-8 (dotyczy to także pliku Z.java). Plik X.java zostanie odczytany z użyciem kodowania CP1252, a plik Y.java będzie używany z kodowaniem UTF-16.
  • ... -encoding UTF-8 -encoding UTF-16 ....
    Wszystkie pliki źródłowe zostaną odczytane z użyciem kodowania UTF-16. Opcja -encoding dla kodowania UTF-8 zostanie zignorowana.
  • ... -encoding Cp1252 /foo/bar/X.java[UTF-16] /foo/bar[UTF-8] ....
    Wszystkie pliki źródłowe zostaną odczytane z użyciem kodowania CP1252. X.java to jedyny plik z katalogu /foo/bar, który zostanie odczytany z użyciem kodowania UTF-16. Dla pozostałych plików w tym katalogu zostanie użyte kodowanie UTF-8.
Opcje zgodności
-target 1.1 do 1.7 lub (5, 5.0, itd.) Określa docelowe ustawienie pliku .class. Możliwe wartości:
  • 1.1 (numer wersji głównej: 45, drugorzędnej: 3)
  • 1.2 (numer wersji głównej: 46, drugorzędnej: 0)
  • 1.3 (numer wersji głównej: 47, drugorzędnej: 0)
  • 1.4 (numer wersji głównej: 48, drugorzędnej: 0)
  • 1.5, 5 lub 5.0 (numer wersji głównej: 49, drugorzędnej: 0)
  • 1.6, 6 lub 6.0 (numer wersji głównej: 50, drugorzędnej: 0)
  • 1.7, 7 lub 7.0 (numer wersji głównej: 51, drugorzędnej: 0)
Wartości domyślne:
  • 1.1 w trybie -1.3
  • 1.2 w trybie -1.4
  • 1.5 w trybie -1.5
  • 1.6 w trybie -1.6
  • 1.7 w trybie -1.7

Za pomocą elementu clcd1.1 można generować atrybut StackMap.

-1.3 Ustawia poziom zgodności na wartość 1.3. Niejawnie: -source 1.3 -target 1.1.
-1.4 Ustawia poziom zgodności na wartość 1.4 (domyślny). Niejawnie: -source 1.3 -target 1.2.
-1.5 Ustawia poziom zgodności na wartość 1.5. Niejawnie: -source 1.5 -target 1.5.
-1.6 Ustawia poziom zgodności na wartość 1.6. Niejawnie: -source 1.6 -target 1.6.
-1.7 Ustawia poziom zgodności na 1.7. Niejawnie: -source 1.7 -target 1.7.
-source 1.1 do 1.7 lub (5, 5.0, itd.) Służy do określania wersji kodu źródłowego oczekiwanego przez kompilator.
Możliwe wartości:
  • 1.3
  • 1.4
  • 1.5, 5 lub 5.0
  • 1.6, 6 lub 6.0
  • 1.7, 7 lub 7.0
Wartości domyślne:
  • 1.3 w trybie -1.3
  • 1.3 w trybie -1.4
  • 1.5 w trybie -1.5
  • 1.6 w trybie -1.6
  • 1.7 w trybie -1.7
W trybie 1.4 słowo assert jest traktowane jako słowo kluczowe. W trybie 1.5 i 1.6 słowa enum i assert są traktowane jako słowa kluczowe.
Opcje ostrzeżeń
-?:warn -help:warn Służy do wyświetlania zaawansowanych opcji ostrzeżeń.
-warn:... Określa zestaw włączonych ostrzeżeń.
np. -warn:unusedLocal,deprecation
-warn:none wyłącza wszystkie ostrzeżenia
-warn:<elementy ostrzeżeń rozdzielone przecinkami> włącza tylko wymienione ostrzeżenia
-warn:+<elementy ostrzeżeń rozdzielone przecinkami> włącza dodatkowe ostrzeżenia
-warn:-<elementy ostrzeżeń rozdzielone przecinkami> wyłącza konkretne ostrzeżenia
W poniższej kolumnie Wartość domyślna oznaczenie „+/-” wskazuje, że operacja pokrywa kilka precyzyjnych wariantów ostrzeżeń, w przypadku których niektóre są domyślnie włączone, a niektóre wyłączone. Oznacza to, że określenie opcji „+” włączy większą liczbę ostrzeżeń niż domyślna, a określenie opcji „-” wyłączy część włączoną domyślnie.
Wartość domyślna Nazwa elementu Opis
+/- allDeadCode Wystąpienie martwego kodu z kodem prostym, jeśli zaznaczono opcję (DEBUG)
+/- allDeprecation Wystąpienie nieaktualności, również wewnątrz nieaktualnego kodu
- allJavadoc Niepoprawna lub brakująca dokumentacja Javadoc
- allOver-ann Wszystkie brakujące adnotacje @Override (nadklasa i nadinterfejs)
- all-static-method Ostrzeżenie o deklarowaniu wszystkich metod jako static
+ assertIdentifier Wystąpienie słowa assert w charakterze identyfikatora
- boxing Konwersja automatycznego opakowania
+ charConcat Tablica typu char użyta w konkatenacji łańcuchów bez jawnego przekształcenia w łańcuch
+ compareIdentical Porównanie identycznych wyrażeń
- conditionAssign Możliwe przypadkowe przypisanie boolowskie
+ constructorName Metoda o nazwie konstruktora
+ deadCode Wystąpienie martwego kodu bez kodu prostego, jeśli zaznaczono opcję (DEBUG)
- dep-ann Brak adnotacji @Deprecated
+/- deprecation Użycie nieaktualnego typu lub składowej poza nieaktualnym kodem
+ discouraged Użycie typów odpowiadających regule niewskazanego dostępu
- emptyBlock Nieudokumentowany pusty blok
+ enumIdentifier Wystąpienie słowa enum w charakterze identyfikatora
+ enumSwitch Niekompletna instrukcja switch deklaracji enum
- enumSwitchPedantic Zgłaszanie brakujących bloków case w instrukcjach switch na zmiennych enum nawet wtedy, gdy podano przypadek default
- fallthrough możliwy przypadek niedojścia do skutku
- fieldHiding Pole ukrywające inną zmienną
+ finalBound Parametr typu z powiązaniem final
+ finally Blok finally niezakończony normalnie
+ forbidden Użycie typów odpowiadających regule zabronionego dostępu
- hashCode Brak metody hashCode() podczas przesłaniania metody equals()
+/- hiding Makro dla opcji fieldHiding, localHiding, typeHiding i maskedCatchBlock
- includeAssertNull Zgłaszanie ostrzeżeń dotyczących wartości null zmiennych zmodyfikowanych w wyrażeniu assert
- indirectStatic Pośredni dostęp do składowej static
+ intfAnnotation Typ adnotacji używany jako nadinterfejs
+ intfNonInherited Zgodność metody niedziedziczona po interfejsie
- intfRedundant Znalezienie nadmiarowych nadinterfejsów
- javadoc Niepoprawna dokumentacja Javadoc
- localHiding Zmienna lokalna ukrywająca inną zmienną
+ maskedCatchBlock Ukryty blok catch
- nls Literały łańcuchowe non-nls (brak znaczników //$NON-NLS-<n>)
+ noEffectAssign Przypisanie bez efektu
+/- null Potencjalne nadmiarowe sprawdzenie wartości NULL lub jego brak
- nullAnnot Włączenie analizy wartości NULL opartej na adnotacjach.
W razie potrzeby można określić typy adnotacji do interpretowania przez kompilator, dodając łańcuch (nullable|nonnull|nonnullbydefault), gdzie każdy typ adnotacji jest określany za pomocą pełnej nazwy kwalifikowanej.
Patrz również opcja -nonNullByDefault poniżej.
- nullDereference Sprawdzanie braku wartości NULL
- over-ann Brakująca adnotacja @Override (tylko nadklasa)
- paramAssign Przypisanie do parametru
+ pkgDefaultMethod Próba przesłonięcia metody domyślnej pakietu
+ raw Użycie typu surowego (zamiast sparametryzowanego)
+/- resource (Potencjalnie) niebezpieczne użycie zasobu typu Closeable
- semicolon Zbędny średnik lub instrukcja pusta
+ serial Brak identyfikatora serialVersionUID
- specialParamHiding Parametr konstruktora lub metody ustawiającej ukrywający inne pole
+/- static-access Makro dla opcji indirectStatic i staticReceiver
- static-method Metoda instancji, która mogłaby być metodą statyczną
+ staticReceiver Odbiornik inny niż static użyty do uzyskania pola static lub wywołania metody static
- super przesłonięcie metody bez wywołania typu super
+ suppress Włącza adnotacje @SuppressWarnings
- switchDefault Brak przypadku default w instrukcji switch
- syncOverride Brak synchronizowanych elementów podczas przesłaniania metody synchronizowanej
- syntheticAccess Syntetyczny dostęp do klasy wewnętrznej
- tasks Włącza obsługę znaczników zadań w kodzie źródłowym
+ typeHiding Parametr typu ukrywający inny typ
+ unavoidableGenericProblems Ignorowanie problemów z bezpieczeństwem typów niemożliwych do uniknięcia z powodu surowych funkcji API
+ unchecked Operacja na niekontrolowanym typie
- unnecessaryElse Zbędna klauzula else
- unqualifiedField Niekwalifikowany dostęp do pola
+/- unused Makro dla opcji unusedAllocation, unusedArgument, unusedImport, unusedLabel, unusedLocal, unusedPrivate, unusedThrown i unusedTypeArgs
- unusedAllocation Przydzielenie nieużywanego obiektu
- unusedArgument Nieużywany argument metody
+ unusedImport Nieużywane odwołanie do instrukcji importu
+ unusedLabel Nieużywana etykieta
+ unusedLocal Nieużywana zmienna lokalna
+ unusedPrivate Nieużywana deklaracja składowej private
- unusedThrown Nieużywany zadeklarowany zgłoszony wyjątek
+ unusedTypeArgs Nieużywane argumenty typów metod i konstruktorów
- uselessTypeCheck Zbędna operacja cast/instanceof
+ varargsCast Argument varargs wymaga jawnego rzutowania
+/- warningToken Nieobsługiwany lub nieużywany element ostrzeżenia w adnotacji @SuppressWarnings
-nowarn Bez ostrzeżeń (równoważne opcji -warn:none).
-err:... Określa zestaw włączonych ostrzeżeń, które są przekształcane w błędy,
np. -err:unusedLocal,deprecation.
Ostrzeżenia unusedLocal i deprecation będą przekształcane w błędy. Wszystkie inne ostrzeżenia będą w dalszym ciągu zgłaszane jako ostrzeżenia.
-err:<elementy ostrzeżeń rozdzielone przecinkami> przekształca w błędy tylko wymienione ostrzeżenia
-err:+<elementy ostrzeżeń rozdzielone przecinkami> przekształca w błędy dodatkowe ostrzeżenia
-err:-<elementy ostrzeżeń rozdzielone przecinkami> wyłącza przekształcanie w błędy konkretnych ostrzeżeń
-deprecation Odpowiednik -warn:+deprecation.
-properties <plik> Umożliwia ustawienie opcji dotyczących ostrzeżeń lub błędów na podstawie treści pliku właściwości. Tej opcji można używać w połączeniu z opcjami -nowarn, -err:.. lub -warn:.., jednak ostatnia pozycja w wierszu komend powoduje ustawienie używanych opcji.

Treść pliku właściwości można wygenerować, określając ustawienia dotyczące projektu w ramach istniejącego projektu Java i używając pliku .settings/org.eclipse.jdt.core.prefs jako pliku właściwości lub też tworząc prosty plik tekstowy zawierający pary wpisów pozycja/wartość używających stałych zdefiniowanych w klasie 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
...
Opcje debugowania
-g[:none|:lines,vars,source] Ustawia poziom atrybutów debugowania.
-g Wszystkie informacje dla debugowania (równoważne opcji -g:lines,vars,source).
-g:none Brak informacji dla debugowania.
-g:[lines,vars,source] Wybrane informacje dla debugowania.
-preserveAllLocals Jawne żądanie, aby kompilator zachował wszystkie zmienne lokalne (do celów debugowania). Jeśli zostanie pominięta, kompilator usunie nieużywane zmienne lokalne.
Opcje przetwarzania adnotacji (wymagają VM 1.6 lub nowszej i są używane tylko po ustawieniu zgodności na poziom 1.6)
-Aklucz[=wartość] Opcje przekazywane do procesorów adnotacji. Klucz składa się z identyfikatorów rozdzielanych kropkami.
-proc:[only|none] Jeśli podana zostanie opcja -proc:only, to procesor adnotacji zostanie uruchomiony, ale nie zajdzie kompilacja. Jeśli podana zostanie opcja -proc:none, to procesory adnotacji nie będą wykrywane ani uruchamiane. Kompilacja będzie przebiegać tak, jakby nie znaleziono żadnych procesorów adnotacji. Domyślnie, kompilator musi przeszukać ścieżkę klas pod kątem procesorów adnotacji, zatem podanie opcji -proc:none może przyspieszyć kompilację, jeśli przetwarzanie adnotacji jest niepotrzebne.
-processor <klasa1[,klasa2,...]> Kwalifikowane nazwy klas wszystkich procesorów adnotacji, które mają zostać uruchomione. Gdy ta opcja zostanie podana, pomijany jest zwykły proces wykrywania procesorów.
-processorpath <kat 1>;<kat 2>;...;<kat P> Lista katalogów lub plików JAR, które będą przeszukiwane pod kątem procesorów adnotacji. Poszczególne pozycje są rozdzielone separatorem ścieżek dla danej platformy. Jeśli ta opcja nie zostanie podana, przeszukiwana będzie ścieżka klas.
-s <kat> Katalog, w którym tworzone będą wygenerowane pliki źródłowe.
-XprintProcessorInfo Generuje informacje o tym, jakie adnotacje i elementy ma przetwarzać procesor.
-XprintRounds Generuje informacje o etapach przetwarzania adnotacji.
-classNames <klasa1[,klasa2,...]> Kwalifikowane nazwy typów binarnych, które mają zostać przetworzone.
Opcje ignorowane (ze względu na zgodność z opcjami javac)
-J<opcja> Przekazanie opcji do maszyny wirtualnej.
-X<opcja> Określenie opcji niestandardowej. Opcja -Xemacs nie jest ignorowana.
-X Wygenerowanie informacji o niestandardowych opcjach i wyjście.
-O Optymalizacja pod kątem czasu wykonywania.
Opcje zaawansowane
@<plik> Wczytuje argumenty wiersza komend z pliku.
-maxProblems <n> Maksymalna liczba problemów na jednostkę kompilacji (domyślnie 100).
-log <nazwa_pliku> Określa plik dziennika, do którego będą zrzucane wszystkie dane wyjściowe kompilatora. Jest to bardzo przydatna opcja do debugowania kompilatora wsadowego lub uzyskania pliku zawierającego wszystkie błędy i ostrzeżenia z budowania wsadowego. W przypadku określenia rozszerzenia .xml wygenerowany dziennik będzie plikiem xml.
-Xemacs Wyświetlanie położeń ostrzeżeń i błędów w konsoli i standardowych dziennikach tekstowych w stylu edytora emacs. Opcja ta nie ma wpływu na dzienniki XML. Jeśli ta opcja jest aktywna, komunikat
2. Ostrzeżenie: /workspace/X.java
(w wierszu 8)...

jest wyświetlany jako
/workspace/X.java:8: ostrzeżenie: Metoda...
-proceedOnError[:Fatal] Nie przerywa kompilowania mimo błędów, zrzucając pliki klasy z problematycznymi metodami lub typami. Użycie tej opcji jest zalecane tylko wtedy, gdy chce się uruchomić aplikację nawet pomimo występujących błędów.
Przy włączonej opcji „:Fatal” wszystkie opcjonalne błędy są traktowane jako krytyczne, co powoduje wygenerowanie kodu, który przerywa wykonanie w przypadku napotkania błędu w czasie wykonywania. Bez opcji „:Fatal” opcjonalne błędy nie uniemożliwiają poprawnego wygenerowania kodu, a utworzony plik .class można uruchomić bez problemów.
-verbose Zapisuje jednostki kompilacji, do których uzyskano dostęp lub które zostały przetworzone, w konsoli lub w pliku dziennika (jeśli został określony).
-referenceInfo Oblicza informacje o odwołaniach. Jest to przydatne tylko w przypadku połączenia z programem budującym. W przeciwnym razie informacje te są bezużyteczne.
-progress Wyświetla postęp (tylko w trybie -log).
-time Wyświetla informacje o szybkości.
-noExit Nie wywołuje metody System.exit(n) na zakończenie kompilacji (w razie braku błędów n=0).
-repeat <n> Powtarza proces kompilacji <n> razy (analiza wydajności).
-inlineJSR Wstawia kod bajtowy JSR (niejawnie, jeśli wersja docelowa >= 1.5).
-enableJavadoc Uwzględnia odwołania w dokumentacji Javadoc.
-missingNullDefault Po włączeniu analizy wartości NULL opartej na adnotacjach (za pomocą powyższej opcji „nullAnnot”) ta opcja spowoduje zgłoszenie ostrzeżenia w przypadku, gdy w pakiecie lub typie nie będzie adnotacji domyślnej.
Opcje pomocy
-? -help Wyświetla komunikat pomocy.
-v -version Wyświetla numer kompilacji kompilatora. Jest to bardzo przydatne do raportowania błędów.
-showversion Wyświetla numer kompilacji kompilatora, nie zatrzymując jego działania. Jest to bardzo przydatne do raportowania błędów.

Przykłady

d:\temp -classpath rt.jar -time -g -d d:/tmp Uruchamia kompilację wszystkich plików źródłowych z folderu d:\temp i jego podfolderów. Ścieżka klas to po prostu rt.jar. Komenda ta generuje wszystkie atrybuty debugowania, a wszystkie wygenerowane pliki .class są zrzucane do folderu d:\tmp. Szybkość kompilatora zostanie wyświetlona po zakończeniu procesu wsadowego.
d:\temp\Test.java -classpath d:\temp;rt.jar -g:none Kompiluje tylko plik Test.java i pliki od niego zależne, jeśli istnieją, pobierając je z folderu d:\temp. Ścieżka klas to d:\temp, a następnie rt.jar, co oznacza, że wszelkie potrzebne klasy są wyszukiwane najpierw w folderze d:\temp, a następnie w pliku rt.jar. Komenda ta nie generuje żadnych atrybutów debugowania, a wszystkie wygenerowane pliki .class są zrzucane do folderu d:\temp.