執行 Apache Ant

命令列

如果您已經按照 安裝 Ant 部分的描述安裝了 Apache Ant，從命令行運行 Ant 就很簡單：只需輸入 ant。

當未指定任何參數時，Ant 會在當前目錄中尋找一個 build.xml 檔案，如果找到，則將該檔案用作構建檔並運行 <project> 標籤的 default 屬性中指定的目標。若要讓 Ant 使用除 build.xml 以外的構建檔，請使用命令行選項 -buildfile file，其中 file 是您想要使用的構建檔的名稱（或包含 build.xml 檔案的目錄）。

如果使用 -find [file] 選項，Ant 將首先在當前目錄中搜尋構建檔，然後在父目錄中搜尋，依此類推，直到找到構建檔或達到檔案系統的根目錄為止。默認情況下，它將尋找一個名為 build.xml 的構建檔。若要讓它搜索除 build.xml 以外的構建檔，請指定一個檔案參數。注意：如果在 -find 標誌之後命令行中包含任何其他標誌或參數，則必須包含 -find 標誌的檔案參數，即使您要找的構建檔名稱是 build.xml。

您也可以在命令行上設置 屬性。這可以通過 -Dproperty=value 選項完成，其中 property 是屬性的名稱，value 是該屬性的值。如果您指定的屬性在構建檔中也已經設置（請參閱 property 任務），則命令行中指定的值將覆蓋構建檔中指定的值。在命令行上定義屬性也可用於傳遞環境變量的值；只需將 -DMYVAR=%MYVAR%（Windows）或 -DMYVAR=$MYVAR（Unix）傳遞給 Ant。然後您可以在構建檔中作為 ${MYVAR} 訪問這些變量。您還可以使用 property 任務的 environment 屬性訪問環境變量。

影響 Ant 輸出日誌數量的選項包括：-quiet，指示 Ant 將較少的信息輸出到控制台；-verbose，使 Ant 將額外的信息輸出到控制台；-debug，使 Ant 輸出更多的額外信息；以及 -silent，使 Ant 只輸出任務輸出和構建失敗（對於通過腳本捕獲 Ant 輸出很有用）。

還可以指定一個或多個應該執行的目標。當省略時，將使用在 project 標記的 default 屬性中指定的目標。

-projecthelp 選項會列印出構建文件的目標列表。包含 description 屬性的目標被列為“主目標”，沒有 description 的目標被列為“其他目標”，然後列出“默認”目標（只有在沒有主目標，或者在以 -verbose 或 -debug 模式調用 Ant 時才顯示“其他目標”）。

命令行選項摘要

ant [options] [target [target2 [target3] ...]]
Options:
  -help, -h              print this message and exit
  -projecthelp, -p       print project help information and exit
  -version               print the version information and exit
  -diagnostics           print information that might be helpful to
                         diagnose or report problems and exit
  -quiet, -q             be extra quiet
  -silent, -S            print nothing but task outputs and build failures
  -verbose, -v           be extra verbose
  -debug, -d             print debugging information
  -emacs, -e             produce logging information without adornments
  -lib <path>            specifies a path to search for jars and classes
  -logfile <file>        use given file for log
    -l     <file>                ''
  -logger <classname>    the class which is to perform logging
  -listener <classname>  add an instance of class as a project listener
  -noinput               do not allow interactive input
  -buildfile <file>      use given buildfile
    -file    <file>              ''
    -f       <file>              ''
  -D<property>=<value>   use value for given property
  -keep-going, -k        execute all targets that do not depend
                         on failed target(s)
  -propertyfile <name>   load all properties from file with -D
                         properties taking precedence
  -inputhandler <class>  the class which will handle input requests
  -find <file>           (s)earch for buildfile towards the root of
    -s  <file>           the filesystem and use it
  -nice  number          A niceness value for the main thread:
                         1 (lowest) to 10 (highest); 5 is the default
  -nouserlib             Run ant without using the jar files from ${user.home}/.ant/lib
  -noclasspath           Run ant without using CLASSPATH
  -autoproxy             Java 5+ : use the OS proxies
  -main <class>          override Ant's normal entry point

有關 -logger 和 -listener 的更多信息，請參見 日誌記錄器與監聽器。

有關 -inputhandler 的更多信息，請參見 輸入處理器。

更改退出行為的最簡單方法是對原始主類進行子類化

public class CustomExitCode extends org.apache.tools.ant.Main {
    protected void exit(int exitCode) {
        // implement your own behaviour, e.g. NOT exiting the JVM
    }
}

並使用訪問（-lib path-to-class）啟動 Ant 到這個類。

庫目錄

在 Ant 1.6 之前，所有位於 ANT_HOME/lib 中的 jar 都將添加到運行 Ant 的 CLASSPATH 中。這是在啟動 Ant 的腳本中完成的。自從 Ant 1.6 開始，預設情況下會掃描兩個目錄，並根據需要添加更多目錄。預設掃描的目錄是 ANT_HOME/lib 和用戶特定目錄 ${user.home}/.ant/lib。這種安排允許多個用戶共享 Ant 安裝，同時仍然允許每個用戶部署其他 jar。這些附加的 jar 可以是 Ant 的可選任務的支持 jar，或者包含要在構建中使用的第三方任務的 jar。它還允許對主要 Ant 安裝進行鎖定，這將使系統管理員感到滿意。

可以通過使用 -lib 選項來添加要搜索的其他目錄。 -lib 選項指定了搜索路徑。路徑中的任何 jar 或類都將添加到 Ant 的類加載器中。添加到類路徑的 jar 的順序如下：

• 按照命令行上 -lib 選項指定的順序添加的 jar
• 從 ${user.home}/.ant/lib 中的 jar（除非設置了 -nouserlib）
• 從 ANT_HOME/lib 中的 jar

請注意，將 CLASSPATH 環境變量作為 -lib 選項傳遞給 Ant。Ant 本身是以非常簡化的類路徑啟動的。Ant 應該可以完美地處理空的 CLASSPATH 環境變量，事實上，-noclasspath 選項實際上是強制執行的。我們收到的與類路徑問題相關的支持呼叫比我們喜歡的要多得多（尤其是引用問題）。

位置的 ${user.home}/.ant/lib 稍微依賴於 JVM。 在 Unix 系統上，${user.home} 對應使用者的家目錄，而在最近版本的 Windows 上，它會在類似 C:\Users\使用者名稱\.ant\lib 的位置。 您應該查閱您的 JVM 文件以獲取更多詳細資訊。

範例

ant

在目前目錄中使用 build.xml 檔案，執行 Ant 的預設目標。

ant -buildfile test.xml

在目前目錄中使用 test.xml 檔案，執行 Ant 的預設目標。

ant -buildfile test.xml dist

在目前目錄中使用 test.xml 檔案，執行名為 dist 的目標。

ant -buildfile test.xml -Dbuild=build/classes dist

在目前目錄中使用 test.xml 檔案，執行名為 dist 的目標，並將 build 屬性設置為值 build/classes。

ant -lib /home/ant/extras

執行 Ant 並從 /home/ant/extras 位置提取額外的任務和支援 jars。

ant -lib one.jar;another.jar

ant -lib one.jar -lib another.jar

將兩個 jars 添加到 Ant 的類路徑中。

檔案

對於 Unix 的 Ant 包裝腳本將在執行任何操作之前源（讀取並評估）檔案 ~/.antrc。 在 Windows 上，Ant 包裝批處理檔會在開始時調用 %HOME%\antrc_pre.bat，並在結束時調用 %HOME%\antrc_post.bat。 您可以使用這些檔案，例如，設置/取消設置僅在執行 Ant 時可見的環境變數。 請參閱下一節以獲取範例。

環境變數

包裝腳本使用以下環境變數（如果已設置）

• JAVACMD—Java 執行檔的完整路徑。 使用此來呼叫不同於 JAVA_HOME/bin/java(.exe) 的 JVM。
• ANT_OPTS—應傳遞給 JVM 的命令列參數。 例如，您可以在此定義系統屬性或設置最大的 Java 堆大小。
• ANT_ARGS—Ant 命令列參數。 例如，將 ANT_ARGS 設置為指向不同的記錄器，包括一個監聽器，並包含 -find 標誌。
  注意: 如果在 ANT_ARGS 中包含 -find，則應包含要尋找的建置檔的名稱，即使該檔案被稱為 build.xml。

Java 系統屬性

某些 Ant 的核心類別可以通過系統屬性配置。

這是通過程式碼庫的搜尋結果。 由於系統屬性通過 Project 實例可用，我使用了一個

grep -r -n "getPropert" * > ..\grep.txt

命令來搜索它們。 之後，我過濾出了經常使用但不太重要的值（大多數為只讀值）：path.separator、ant.home、basedir、user.dir、os.name、line.separator、java.home、java.version、java.version、user.home、java.class.path
然後我過濾出了 getPropertyHelper 的存取。

如果添加了新的屬性（這是可能的），則可以期望它們出現在ant.和org.apache.tools.ant.前綴下，除非開發人員有非常好的理由使用另一個前綴。因此，請避免使用以這些前綴開頭的屬性。這可以保護您免受未來Ant版本破壞您的構建文件。

返回代碼

Ant啟動腳本（其Windows和Unix版本）返回java程序的返回代碼。因此，成功構建返回0，失敗的構建返回其他值。

臨時目錄

在調用Ant時設置系統屬性並不直接，因為相應的命令行參數必須發送給Java可執行文件而不是Ant的主類。使用ant(.cmd)包裝腳本時，您可以使用ANT_OPTS環境變量來實現。

從Ant 1.10.8開始，我們引入了一個新的Ant屬性ant.tmpdir，當設置時優先於java.io.tmpdir。由於這是一個普通的Ant屬性，因此可以通過命令行甚至從構建文件內部設置它。

使用臨時目錄的任務和類型將在其各自的手冊頁面內部註明此事實。此外，OpenVMS上的每個外部命令執行都將創建一個臨時文件，其中包含調用實際命令的DCL腳本。

從 Ant 1.10.9 開始，Ant 將嘗試在 java.io.tmpdir 內建立一個特定於建置過程的臨時目錄，權限設置為僅由當前使用者訪問，並在未設置 ant.tmpdir 且 Ant 能夠在相關檔案系統上設置權限時使用該目錄。

未隨 Ant 分發的任務將忽略 ant.tmpdir 屬性或處理子目錄，並使用 java.io.tmpdir，除非它們已經適應了 Ant 1.10.8 的更改的 API。

安全提示： 使用由 java.io.tmpdir 指定的預設臨時目錄可能導致敏感資訊的洩漏，或者可能允許攻擊者將源文件注入到建置過程中。在多使用者環境中尤其如此。建議將 ant.tmpdir 設置為由執行 Ant 的使用者擁有的 0700 權限的目錄。Ant 1.10.8 及更高版本將嘗試僅使其創建的臨時文件可讀/可寫給當前使用者，但根據作業系統和檔案系統的不同，可能會在不知不覺中失敗。

Cygwin 使用者

隨 Ant 附帶的 Unix 啟動腳本在 Cygwin 中運作正常。您不應該在從 Cygwin shell 啟動 Ant 時遇到任何問題。然而，重要的是要注意，一旦 Ant 運行，它就是 JDK 的一部分，該 JDK 作為本機 Windows 應用程序運行。JDK 不是 Cygwin 可執行文件，因此不了解 Cygwin 路徑等。特別是在使用 <exec> 任務時，如 /bin/sh 等執行文件名將不起作用，即使這些在從啟動 Ant 的 Cygwin shell 中也是有效的。您可以使用執行文件名，例如 sh，並依賴 Windows 路徑中可用的該命令。

OS/2 使用者

OS/2 啟動腳本被開發用於執行複雜的任務。它分為兩部分：ant.cmd 用於調用 Ant 和 antenv.cmd 用於設置 Ant 的環境。您通常將使用相同的命令行選項調用 ant.cmd。行為可以通過以下方式進行修改。

腳本 ant.cmd 首先驗證 Ant 環境是否正確設置。要求如下：

1. 環境變量 JAVA_HOME 已設置。
2. 環境變量 ANT_HOME 已設置。
3. 環境變量 CLASSPATH 已設置，並包含來自 JAVA_HOME 和 ANT_HOME 至少一個元素。

如果違反了上述任何條件，則會調用腳本 antenv.cmd。該腳本首先調用配置腳本（如果存在）：antconf.cmd 來自 %ETC% 目錄，然後是用戶配置 antrc.cmd 來自 %HOME% 目錄。此時必須定義 JAVA_HOME 和 ANT_HOME，因為 antenv.cmd 現在將 classes.zip 或 tools.jar（取決於 JVM 版本）以及來自 %ANT_HOME%\lib 的所有內容，除了 ant-*.jar，添加到 CLASSPATH。最後，ant.cmd 調用每個目錄的配置 antrc.cmd。由 ant.cmd 所做的所有設置都是本地的，在腳本結束時會被還原。由 antenv.cmd 所做的設置在 shell 的生存期間是持久的（當然，除非自動從 ant.cmd 調用）。因此，在調用 ant.cmd 之前，可以手動調用 antenv.cmd 並修改一些設置。

腳本 envset.cmd 和 runrc.cmd 執行輔助任務。所有腳本內部都有一些文檔。

在 Unix(-like) 系統上作為背景進程運行 Ant

如果您將 Ant 運行為背景進程（例如在 ant & 中），並且構建過程創建了另一個進程，則 Ant 將立即嘗試從標準輸入讀取，這可能會暫停該進程。為了避免這種情況，您必須重定向 Ant 的標準輸入，或通過相應任務的輸入相關屬性明確地為每個生成的進程提供輸入。

創建此類新進程的任務包括 <exec>、<apply> 或 <java>，當 fork 屬性設置為 true 時。

通過 Java 運行 Ant

如果您以自己的方式安裝了 Ant，則可以從兩個入口點中的一個開始運行 Ant

java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]

java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]

第一種方法運行 Ant 的傳統入口點。第二種方法使用 Ant 1.6 中引入的 Ant 啟動器。前一種方法不支持 -lib 選項，並且所有所需的類都從 CLASSPATH 中加載。您必須確保所有所需的 jar 包都可用。至少，CLASSPATH 應包括

• ant.jar 和 ant-launcher.jar
• 用於您的 XML 解析器的 jar/類
• JDK 所需的 jar/zip 文件

後一種方法支持 -lib、-nouserlib、-noclasspath 選項，並且將從指定的 ANT_HOME 加載 jar。您應該使用最小可能的類路徑啟動後者，通常只需 ant-launcher.jar。

Ant 可以通過 <java> 命令在 Ant 中啟動。這是一個示例

<java classname="org.apache.tools.ant.launch.Launcher"
      fork="true"
      failonerror="true"
      dir="${sub.builddir}"
      timeout="4000000"
      taskname="startAnt">
    <classpath>
        <pathelement location="${ant.home}/lib/ant-launcher.jar"/>
    </classpath>
    <arg value="-buildfile"/>
    <arg file="${sub.buildfile}"/>
    <arg value="-Dthis=this"/>
    <arg value="-Dthat=that"/>
    <arg value="-Dbasedir=${sub.builddir}"/>
    <arg value="-Dthe.other=the.other"/>
    <arg value="${sub.target}"/>
</java>