使用批次編譯器

尋找批次編譯器

批次編譯器類別位於 JDT 核心外掛程式中。 該類別的名稱為 org.eclipse.jdt.compiler.batch.BatchCompiler。 其套裝在 plugins/org.eclipse.jdt.core_<version>.jar 中。從 3.2 開始，它也可以個別下載。 該檔案的名稱為 ecj.jar。對應的來源也能夠使用。 如果要取得它們，請移至下載頁面，搜尋 JDT 核心批次編譯器一節。 這個 JAR 包含批次編譯器和 javac Ant 配接器。

從 3.3 版開始，這個 jar 也包含 jsr199（編譯器 API）的支援，以及 jsr269（註釋處理）的支援。您需要有 1.6 VM，才能使用註釋處理支援。

因此，您可以利用它來作為獨立式應用程式，也可以在 Eclipse 之外，在 Ant 建置之內使用它。

執行批次編譯器

有哪些可用的選項？

橙色背景的選項是建議選項。

當多次設定某些選項時，批次編譯器會由左至右來使用它們。 當使用不含 '+' 或 '-' 的警告選項 (-warn:....) 時，先前指定的警告集就會被置換掉。 因此，您應先給定上述選項後，再使用其他 -warn 選項。

-err: 選項也是如此。

名稱 用法
類別路徑選項
-bootclasspath <dir 1>;<dir 2>;...;<dir P> 這是用來引導編譯器所用之類別檔的目錄或 JAR 檔清單。 依預設會使用執行中之 VM 的程式庫。這些項目會以平台路徑分隔字元來區隔。
每一個目錄或檔案可以在 '[' 和 ']' 之間指定類型的存取規則。

如果未指定啟動類別路徑，編譯器會分別依序使用以下系統內容來加以推斷：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）。
編譯器會遞迴地遵循 jar 檔之資訊清單的 Class-Path 子句，並將每一個參照的 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 <encoding name> 指定所有原始檔的預設編碼。您也可以在每個輸入原始檔/資料夾名稱後面，附加 [<encodingname>] 字尾，以便依每個檔案來指定自訂編碼。比方說，X.java[utf8] 將針對位於現行使用者目錄中的編譯單元 X.java，指定 UTF-8 編碼。

如果指定了多項預設原始檔編碼，就會使用最後一個。

例如：

  • ... -encoding UTF-8 X.java[Cp1252] Y.java[UTF-16] Z.java ....
    將使用 UTF-8 編碼來讀取所有的原始檔（這包含 Z.java）。將使用 Cp1252 編碼來讀取 X.java，以及使用 UTF-16 編碼來讀取 Y.java。
  • ... -encoding UTF-8 -encoding UTF-16 ....
    將使用 UTF-16 編碼來讀取所有的原始檔。會忽略 UTF-8 的 -encoding 選項。
  • ... -encoding Cp1252 /foo/bar/X.java[UTF-16] /foo/bar[UTF-8] ....
    將使用 Cp1252 編碼來讀取所有的原始檔。/foo/bar 目錄內唯有 X.java 檔案是使用 UTF-16 編碼來讀取。該目錄中的其他所有檔案都將使用 UTF-8 編碼。
標準選項
-target 1.1 至 1.7 或是（5、5.0 等等） 這會指定 .class 檔目標設定。 可能的值為：
  • 1.1（主要版本：45 次要：3）
  • 1.2（主要版本：46 次要：0）
  • 1.3（主要版本：47 次要：0）
  • 1.4（主要版本：48 次要：0）
  • 1.5、5 或 5.0（主要版本：49 次要：0）
  • 1.6、6 或 6.0（主要版本：50 次要：0）
  • 1.7、7 或 7.0（主要版本：51 次要：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 至 1.7 或是（5、5.0 等等） 這用來指定編譯器所預期的來源層次。
可能的值為：
  • 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:none 停用所有警告
-warn:<warning tokens separated by ,> 確實啟用列出的警告
-warn:+<warning tokens separated by ,> 啟用其他警告
-warn:-<warning tokens separated by ,> 停用特定警告

範例：

  • -warn:unusedLocal,deprecation：只啟用給定的兩個警告選項，並停用其他所有的選項
  • -warn:-unusedLocal,deprecation,+fallthrough：停用 unusedLocal 和 deprecation，啟用 fallthrough，其他警告選項則不更動
在以下的預設值直欄中，"+/-" 標記指出某個選項涵蓋數個精細的警告變式，其中的部分變式會依預設啟用，其他則停用。這表示指定具有 "+" 的給定選項將會啟用比預設值更多的警告，而指定 "-" 則會停用依預設啟用的警告。
預設值 記號名稱 說明
+/- allDeadCode 包括無價值的 if(DEBUG) 檢查的停用碼
+/- allDeprecation 淘汰，即使在已淘汰的程式碼內亦同
- allJavadoc 無效或遺漏的 Javadoc
- allOver-ann 所有遺漏的 @Override 註釋（超類別和超介面）
- all-static-method 所有方法皆可宣告為靜態警告
+ assertIdentifier 用來作為 ID 的 assert 的出現處
- boxing autoboxing 轉換
+ charConcat 字元陣列用於字串連接，而不需明確轉換成字串的時機
+ compareIdentical 比較相同的表示式
- conditionAssign 可能的意外 Boolean 指派
+ constructorName 含有建構子名稱的方法
+ deadCode 排除無價值的 if(DEBUG) 檢查的停用碼
- dep-ann 遺漏 @Deprecated 註釋
+/- deprecation 在已淘汰的程式碼之外，已淘汰之類型或成員的用法
+ discouraged 使用的類型符合不建議的存取規則
- emptyBlock 未記載的空區塊
+ enumIdentifier 用來作為 ID 的 enum 的出現處
+ enumSwitch 不完整的 enum 切換選項
- enumSwitchPedantic 即使出現預設案例仍報告遺漏列舉 switch 案例
- fallthrough 可能的 fall-through 案例
- fieldHiding 欄位隱藏了另一個變數
+ finalBound 含有最終界限的類型參數
+ finally finally block 未正常完成
+ forbidden 使用的類型符合禁止存取規則
- hashCode 置換 equals() 時遺漏 hashCode() 方法
+/- hiding 用於 fieldHiding、localHiding、maskedCatchBlock 和 typeHiding 的巨集
- includeAssertNull 對於在 assert 表示式中遭到污染的變數，會產生空值警告
- indirectStatic Static 成員的間接參照
- inheritNullAnnot 將空值註釋視為從被置換方法繼承到任何置換方法
+ intfAnnotation 用來作為超介面的註釋類型
+ intfNonInherited 介面非繼承方法的相容性
- intfRedundant 尋找冗餘的超介面
- invalidJavadoc 用來切換「形態異常的 Javadoc 註解」選項及下列所有其子選項的巨集
- invalidJavadocTag 報告 Javadoc 註解中的無效 Javadoc 標籤。
- invalidJavadocTagDep 報告 Javadoc 標籤引數中的無效淘汰參照
- invalidJavadocTagNotVisible 報告 Javadoc 標籤引數中的無效不可見參照
- invalidJavadocVisibility(<visibility>) 為形態異常的 Javadoc 標籤警告指定可見性修飾元（"public"、"protected" 或 "private"）。用法範例：invalidJavadocVisibility(public)
- javadoc 無效的 Javadoc
- localHiding 區域變數隱藏了另一個變數
+ maskedCatchBlock 隱藏的 catch 區塊
- missingJavadocTags 用來切換「遺漏 Javadoc 標籤」選項及下列所有其子選項的巨集
- missingJavadocTagsMethod 報告遺漏方法的類型參數的 Javadoc 標籤
- missingJavadocTagsOverriding 報告置換方法中遺漏 Javadoc 標籤
- missingJavadocTagsVisibility(<visibility>) 對遺漏 Javadoc 標籤警告指定可見性修飾元（"public"、"protected" 或 "private"）。用法範例：missingJavadocTagsVisibility(public)
- missingJavadocComments 用來切換「遺漏 Javadoc 註解」選項及下列所有其子選項的巨集
- missingJavadocCommentsOverriding 報告置換方法中遺漏 Javadoc 註解
- missingJavadocCommentsVisibility(<visibility>) 對遺漏 Javadoc 註解警告指定可見性修飾元（"public"、"protected" 或 "private"）。用法範例：missingJavadocCommentsVisibility(public)
- nls 非 nls 字串文字（缺少 //$NON-NLS-<n> 標籤）
+ noEffectAssign 沒有作用的指派
+ nonnullNotRepeated 來自被置換方法的非空值參數註釋不會在被置換方法中重複。只有在搭配啟用 nullAnnot 選項時才有作用。
+/- null 可能的遺漏或冗餘空值檢查
- nullAnnot 啟用註釋型空值分析。
需要的話，可以藉由附加 (nullable|nonnull|nonnullbydefault) 來指定要由編譯器解譯的註釋類型，其中是使用其完整名稱來指定每一種註釋類型。
用法範例：nullAnnot(p.Nullable|p.NonNull|p.NonNullByDefault)
啟用此選項可啟用所有空值註釋相關的子選項。這些選項可利用下列選項來個別控制
- nullAnnotConflict 報告指定的空值註釋與推斷的空值之間的衝突。只有在搭配啟用 nullAnnot 選項時才有作用。
- nullAnnotRedundant 報告冗餘的空值註釋指定。只有在搭配啟用 nullAnnot 選項時才有作用。
- nullDereference 遺漏的空值檢查
- nullUncheckedConversion 報告未檢查的未標註類型至 @NonNull 類型轉換。只有在搭配啟用 nullAnnot 選項時才有作用。
- over-ann 遺漏 @Override（只限超類別）
- paramAssign 指派給參數
+ pkgDefaultMethod 嘗試置換套件預設方法
+ raw 使用原始類型（而不是參數化類型）
+/- 資源 （潛在地）不安全地使用 Closeable 類型的資源
- semicolon 不必要的分號或空的陳述式
+ serial 遺漏 serialVersionUID
- specialParamHiding 建構子或 setter 參數隱藏了另一個欄位
+/- static-access indirectStatic 和 staticReceiver 的巨集
- static-method 可作為 static 方法的實例方法
+ staticReceiver 非 static 接收端是否用來取得 static 欄位或呼叫 static 方法
- super 置換方法時不執行 super 呼叫
+ suppress 啟用 @SuppressWarnings
- switchDefault 缺少預設案例的 switch 陳述式
- syncOverride 在同步化方法置換中遺漏同步化
- syntheticAccess 對內部類別執行綜合存取的時機
- tasks 在程式碼中啟用 tasks 標籤的支援
+ typeHiding 類型參數隱藏了另一個類型
+ unavoidableGenericProblems 仍會報告因原始 API 所導致的無法避免的類型安全問題
+ unchecked 未檢查的 type 作業
- unnecessaryElse 不必要的 else 子句
- unqualifiedField 欄位的未限定參照
+/- unused unusedImport、unusedLabel、unusedLocal、unusedPrivate、unusedThrown、unusedTypeArgs 和 unusedTypeParameter 的巨集
- unusedAllocation 配置未用的物件
- unusedArgument 未用的方法參數（已淘汰的選項；請改用 unusedParam）
+ unusedImport 未使用的匯入參照
+ unusedLabel 未用的標籤
+ unusedLocal 未使用的區域變數
+ unusedParam 未使用的方法參數
+ unusedParamImplementing 實作方法的未用參數
+ unusedParamIncludeDoc 未用的參數記錄在 Javadoc 註解標籤
+ unusedParamOverriding 置換方法的未用參數
+ unusedPrivate 未使用的私密成員宣告
- unusedThrown 未使用的已宣告擲出異常狀況
- unusedThrownIncludeDocComment Javadoc 註解標籤中記錄的未用的已宣告擲出異常狀況
- unusedThrownExemptExceptionThrowable 報告已宣告但未使用的擲出異常狀況（Exception 和 Throwable 除外）
- unusedThrownWhenOverriding 置換方法中未用的已宣告擲出異常狀況
+ unusedTypeArgs 方法和建構子未使用的類型引數
+ unusedTypeParameter 未使用的類型參數
- uselessTypeCheck 不必要的 cast/instanceof 作業
+ varargsCast varargs 引數需要明確強制轉型
+/- warningToken @SuppressWarnings 中無法處理或未用的警告記號
-nowarn 沒有警告（相當於 -warn:none）
-err:... 指定轉換成錯誤的啟用警告集。
例如：-err:unusedLocal,deprecation
unusedLocal 和 deprecation 警告將轉換成錯誤。 所有其他警告仍報告為警告。
-err:<warning tokens separated by ,> 將列出的警告確實轉換成錯誤
-err:+<warning tokens separated by ,> 將其他警告轉換成錯誤
-err:-<warning tokens separated by ,> 將特定警告移除，不轉換成錯誤
-deprecation 相等於 -warn:+deprecation。
-properties <file> 根據內容檔內容來設定警告/錯誤選項。 這個選項可用來搭配 -nowarn、-err:.. 或 -warn:.. 選項，但指令行上的最後一個會設定要用的選項。

您可以在現有的 Java 專案上設定特定專案專用設定，再利用 .settings/org.eclipse.jdt.core.prefs 檔中的檔案來作為內容檔，或作為利用 org.eclipse.jdt.core.JavaCore 類別定義的常數來定義項目/值組的簡式文字檔，以產生內容檔內容。這些宣告在此類別的常數中，開頭為 "org.eclipse.jdt.core.compiler." 的所有選項會由批次編譯器來解譯。

...
org.eclipse.jdt.core.compiler.problem.annotationSuperInterface=warning
org.eclipse.jdt.core.compiler.problem.assertIdentifier=warning
org.eclipse.jdt.core.compiler.problem.autoboxing=ignore
...

為了確保內容檔在使用於 IDE 和批次處理編譯器時具有相同的效果，使用 -properties 選項會變更部分選項的預設值：

-g預設值變更為 all enabled
-preserveAllLocals預設值變更為 enabled
-enableJavadoc預設值變更為 enabled
error/warning forbidden預設值變更為 error
除錯選項
-g[:none|:lines,vars,source] 設定除錯屬性層次
-g 所有除錯資訊（相當於 -g:lines,vars,source）
-g:none 沒有除錯資訊
-g:[lines,vars,source] 選擇性的除錯資訊
未指定此選項等同於設定 -g:lines,source。
-preserveAllLocals 明確要求編譯器保留所有區域變數（用於除錯）。如果省略的話，編譯器會移除未用的區域變數。
-parameters 針對要從反射程式庫、註釋處理程序、程式碼編排和除錯器中存取的方法，明確要求編譯器保留其正式參數的相關資訊（例如其名稱）。從目標層次 1.8 及更新版本開始支援這個選項。
註釋處理選項（需要有 1.6 VM 或更新的版本，且只適用於標準 1.6）
-Akey[=value] 傳給註釋處理器的註釋處理器選項。key 是由以點區隔的 ID 所組成
-proc:[only|none] 如果指定 -proc:only，系統會執行註釋處理器，但不會執行編譯。如果指定 -proc:none，系統不會探索或執行註釋處理器；編譯會依照找不到註釋處理器的方式來執行。依預設，編譯器必須搜尋註釋處理器的類別路徑，因此如果不需要註釋處理，指定 -proc:none 可能會加速編譯。
-processor <class1[,class2,...]> 要執行之註釋處理器的完整類別名稱。如果指定，則會略過一般處理器探索程序。
-processorpath <dir 1>;<dir 2>;...;<dir P> 會搜尋註釋處理器的目錄或 JAR 檔清單。 這些項目會以平台路徑分隔字元來區隔。如果未指定，則會改為搜尋類別路徑。
-s <dir> 會在其中建立產生的原始檔的目錄。
-XprintProcessorInfo 列印要求處理器處理哪些註釋和哪些元素的相關資訊
-XprintRounds 列印註釋處理回合的相關資訊
-classNames <class1[,class2,...]> 需要處理之二進位類型的完整名稱
忽略的選項（為了相容於 javac 選項）
-J<option> 將選項傳給虛擬機器
-X<option> 指定非標準選項。不會忽略 -Xemacs。
-X 列印非標準選項並結束
-O 最佳化執行時間
進階選項
@<file> 從檔案讀取指令行引數
-maxProblems <n> 每一編譯單元的問題數上限（預設值為 100）
-log <filename> 指定會在其中傾出來自編譯器的所有輸出的日誌檔。如果您要除錯批次編譯器，或取得含有來自批次建置之所有錯誤和警告的檔案，這真的非常有用。如果副檔名是 .xml，產生的日誌便是 xml 檔。
-Xemacs 請利用 emacs 樣式，將錯誤和警告位置呈現在主控台和一般文字日誌中。 這個選項不會影響 XML 日誌。 當這個選項在作用中，下列訊息：
2. WARNING 在 /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 內的參照。只有在啟用這個選項時，Javadoc 選項才有效。
-missingNullDefault 當已啟用註釋型空值分析（使用上述的 "nullAnnot"）時，這個選項會在每當套件或類型上沒有預設註釋時發出警告。
說明選項
-? -help 顯示說明訊息。
-v -version 顯示編譯器的建置號碼。這對報告錯誤非常有用。
-showversion 顯示編譯器的建置號碼並繼續進行。這對報告錯誤非常有用。

範例

d:\temp -classpath rt.jar -time -g -d d:/tmp 這會編譯 d:\temp 和其子資料夾中的所有原始檔。類別路徑只是 rt.jar。其會產生所有除錯屬性，且所有產生的 .class 檔都會傾出至 d:\tmp 中。在批次程序完成後，即會顯示編譯器的速度。
d:\temp\Test.java -classpath d:\temp;rt.jar -g:none 它只會編譯 Test.java 及其相依檔案（如果有的話，會從 d:\temp 中擷取相依的檔案）。 類別路徑是 d:\temp，後面接著 rt.jar，這表示會先搜尋 d:\temp 中所有必要的類別，再搜尋 rt.jar。 它不會產生任何除錯屬性，且所有產生的 .class 檔都會傾出到 d:\temp 中。