Ant User Guide

Another exam connection: http://www.huihoo.com/java/hello-ant/index.html (ANT practice Eric (ericwq@263.net) 1. Ant is what? 2. install ant 3. run ant 4. compile build. XML 5. built-in task (Internet) 6. ear task (Internet) 7. war Task (Internet) 8. JUnit task (Internet) -------------------------------------------------------------------------------- 1. what is Ant? -------------------------------------------------------------------------------- Ant is a Java-based build tool. Theoretically, it is similar to make in (UNIX) C, but it does not have the defect of make. Now that we have make, gnumake, nmake, jam, and other build tools, why do we need a new build tool? The reason is that the author of ant cannot bear the limitations and inconveniences of these tools when developing software on multiple (hardware) platforms. Tools similar to make are essentially shell-based: they compute dependencies and then execute commands (these commands are not much different from the commands you typed on the command line ). This means that you can easily extend the tool by using OS-specific or writing new (command) programs; however, it also means that you limit yourself to a specific OS, or a specific OS type, such as UNIX. Makefile is also hateful. Anyone who has used them has encountered a nasty tab problem. The original author of ant often asked himself: "is my command not executed because there is a space in front of my tab ?!!". A tool similar to jam well handles such problems, but (users) must remember and use a new format. Ant is different. Unlike the extension mode based on shell commands, ant uses Java classes for extension. (User) You do not need to write shell commands. The configuration file is XML-based. You can execute various tasks by calling the target tree. Each task is run by an object that implements a specific task interface. (If you have no idea about ant at all, you may not be able to read this section. It does not matter. We will introduce target and task in detail later. If you don't have much time or even can skip this section, and then you can come back to view the introduction here, then you will understand it. Similarly, if you are not familiar with tools such as make, the following introduction will not use the concept of make .) It must be acknowledged that, in doing so, some special expressions will be lost when constructing shell commands. For example, 'Find.-Name foo-exec RM {} ', but it gives you cross-platform capabilities-you can work anywhere. If you really need to execute some shell commands, ant has a task that allows you to execute commands on a specific OS. 2. install ant ------------------------------------------------------------------------------ because ant is an open source software, there are two ways to install ant, one is to install ant with the compiled binary file, use the source code to build ant. Ant in binary format can be downloaded from http://jakarta.apache.org/builds/ant/release/v1.4.1/bin. If you want to compile ant on your own, you can go to http://jakarta.apache.org/builds/ant/release/v1.4.1/src. Note that all the connections listed are ant of the latest release version. If you read this article and find that an updated version is available, use the new version. If you are a crazy Tech enthusiast, You can also download the latest ant version from ANT cvs repository. You need to build ant on your own. You need a JAXP compatible XML Parser (parser) in your classpath system variables. Ant in binary format includes the latest Apache crimson XML parser. You can get more information about JAXP from http://java.sun.com/xml. If you want to use another JAXP-compatible parser. Delete JAXP. jar and Crimson. jar from the lib directory of ant. Then you can put the JAR file of your beloved parser in the ant lib directory or in your classpath system variable. For the current version of ant, you need JDK, Version 1.1, or higher in your system. JDK 1.2 or later is required for future ant versions. Ant for ant binary has three directories: Bin, Docs, and Lib. Only the bin and Lib directories are required to run ant. To install ant, select a directory and copy the released files to the directory. This directory is called ant_home. You need to do some configuration work before running ant. Add the bin directory to the path environment variable. Set the ant_home environment variable to point to the directory where you install ant. On some operating systems, ant scripts can guess ant_home (UNIX and ipvs NT/2000)-but it is best not to rely on this feature. (Optional) set the java_home environment variable (refer to the advanced section below). This variable should point to the directory where you install JDK. Note: Do not place the ant. JAR file of ant in the LIB/EXT directory of JDK/JRE. Ant is an application, and the LIB/EXT directory is used for JDK extensions (such as JCE and JSSE extensions ). In addition, classes loaded by extension have security restrictions. Optional task ant supports some Optional tasks. An optional task generally requires an additional library to work. Optional tasks are separated from built-in tasks of ant and packaged separately. This Optional package can be downloaded from the same place where you download ant. The jar file name that currently contains the optional task is called the jakarta-ant-1.4.1-optional.jar. This jar file should be placed in the lib directory of the ant installation directory. For the external libraries required for each optional task, see the dependent library section. These external libraries can be placed in the ant lib directory, so that ant can be automatically loaded or put into environment variables. Windows assumes that ant is installed in the C:/ANT/directory. The following command sets the environment: Set ant_home = C:/ant set java_home = C:/jdk1.2.2 set Path = % PATH %; % ant_home %/bin Unix (BASH) assume that ant is installed in the/usr/local/ant directory. The following command sets the environment: Export ant_home =/usr/local/ant export java_home =/usr/local/jdk-1.2.2 export path =$ {path }: $ {ant_home}/bin advanced many variables must be used to run ant. You must at least refer to the following content: ant's classpath must contain ant. jar and the JAR file of the JAXP compatible XML Parser you selected. When you need JDK functions (such as javac or rmic task), The classes.zip file for JDK 1.1. JDK must be placed in classpath; for JDK 1.2 or JDK 1.3, you must add tools. jar. If the correct java_home environment variable and ant script are set, the required JDK class is automatically added to the bin directory. When you execute programs on a specific platform (such as exec task or CVS task), you must set the ant. Home attribute to point to the ant installation directory. Similarly, the ant script uses the ant_home environment variable to automatically set this attribute. To build ant from the source code, you must first install the ant source code release or the checkout Jakarta-ant module from CVS. After installing the source code, go to the installation directory. Set the java_home environment variable to the JDK installation directory. To learn how to do this, see the ant installation section. Make sure that you have downloaded any auxiliary jar files to build the tasks you are interested in. These jar files can be stored in classpath or lib/optional. See the dependency library section to see which jar files are required for different tasks. Note that these jar files are only used for building ant. To run ant, you need to set these jar files as you have done in installing ant. Now you can build ant: Build-ddist. dir = dist (Windows) build. sh-ddist. dir = dist (UNIX) so that you can create a binary version in the specified directory. The above command executes the following action: If necessary, you can use the bootstrap ant code. Bootstrap includes manually editing ant code to run ant. Bootstrap is used for the following build steps. Pass parameters to the build script to call Bootstrap ant. The parameter defines the ant property value and specifies the "Dist" target of the ant build. xml file. In most cases, you do not have to directly Bootstrap ant, because the build script completes this for you. Run Bootstrap. BAT (Windows) or Bootstrap. Sh (UNIX) to build a new Bootstrap ant version. If you want to install ant in the ant_home directory, you can use: build install (Windows) build. sh install (UNIX) If you want to skip lengthy javadoc steps, you can use: build install-lite (Windows) build. sh install-lite (UNIX) then only the bin and Lib directories will be installed. Note that both install and install-lite will overwrite the current ant version in ant_home. If you need to execute a specific task, you need to put the corresponding library into the classpath or the lib directory of the ant installation directory. Note that only one Regexp library is required when mapper is used. At the same time, you also need to install ant's optional jar package, which contains the definition of the task. Refer to the above installation ant section. Jar name needed for available at an XSL transformer like xalan or XSL: P style task http://xml.apache.org/xalan-j/index.html or http://www.clc-marketing.com/xslp/ jakarta-regexp-1.2.jar Regexp type with mappers fill jakarta-oro-2.0.1.jar Regexp type with mappers and the perforce tasks jakarta.apache.org/oro/ JUnit. jar JUnit tasks www.junit.org stylebook. jar stylebook task CVS Repository of xml.apache.org testlet. jar test task java.apache.org/framework anlr. jar anlr task www.antl.org BSF. jar script task oss.software.ibm.com/?works/projects/bsf netrexx. jar netrexx task www2.hursley.ibm.com/netrexx rhino. jar JavaScript with Script task www.mozilla.org jpython. jar Python with Script task www.jpython.org netcomponents. jar FTP and telnet tasks www.savarese.org/oro /Downloads 3. Run ant ------------------------------------------------------------------------------ it is very easy to run ant. After installing ant correctly, you only need to enter ant. If no parameter is specified, ant queries the build. xml file in the current directory. If yes, use this file as buildfile. If you use the-find option. Ant searches for buildfile in the parent directory until it reaches the root of the file system. To enable ant to use other buildfiles, you can use the-buildfile parameter. Here, file specifies the buildfile you want to use. You can also set some attributes to overwrite the attribute values specified in buildfile (see property task ). You can use the-dproperty = value option. Here, property refers to the property name, while value refers to the property value. You can also use this method to specify the values of some environment variables. You can also use property tasks to access environment variables. Just set-dmyvar = % myvar % (Windows) or-dmyvar = $ myvar (UNIX) pass to ant-you can use $ {myvar} In Your buildfile to access these environment variables. There are also two options-quite, which tells ant to output only a small amount of necessary information during runtime. -Verbose tells ant to output more information during runtime. You can specify to execute one or more targets. If the target is omitted, ant uses the target specified by the default attribute of the tag. If yes, the-projecthelp option outputs the project description and the project target list. List the targets with descriptions and no descriptions. Command Line option Summary: ant [Options] [target [TARGET2 [target3]...] options: -Help print this message-projecthelp print project help information-version print the version information and exit-Quiet be extra quiet-verbose be extra verbose-Debug print debugging information-Emacs produce logging information adornments-logfile file use given file for log output-logger classname the class that is t O Perform logging-listener classname add an instance of class as a project listener-buildfile file use specified buildfile-find file search for buildfile towards the root of the filesystem and use the first one found- dproperty = value set property to value example ant uses build in the current directory. run ant in XML and execute the default target. Ant-buildfile test. XML uses test. XML in the current directory to run ant and execute the default target. Ant-buildfile test. xml Dist uses test. XML in the current directory to run ant and execute a target called Dist. Ant-buildfile test. XML-dbuild = build/classes Dist use test. run ant in XML, execute a target called Dist, and set the build attribute value to build/classes. On UNIX, the ant execution script will read and calculate the value of the source file before doing anything )~ /. Antrc file; on Windows, the ant batch processing file will call % home %/antrc_pre.bat at the beginning and call % home %/antrc_post.bat at the end. You can use these files to configure or cancel some environment variables that are only required to run ant. Let's look at the example below. The environment variable package script (wrapper scripts) uses the following environment variables (if any): the absolute path of the javacmd Java executable file. You can use this value to specify a JVM different from java_home/bin/java(.exe. Ant_opts command line variables passed to JVM-for example, you can define attributes or set the maximum value of Java heap to manually run ant. If you install (DIY) Ant by yourself, you can run the following command to start ant: Java-Dant. home = C:/ant Org. apache. tools. ant. main [Options] [target] is the same as the ant command. The options are the same as those for the target command. This example assumes that your classpath contains: ant. jar jars/classes for your XML Parser the JDK's required JAR/ZIP files 4. compile build. XML -------------------------------------------------------------------------------- the buildfile of ant is written in XML. Each buildfile contains a project. Each task element in buildfile can have an id attribute that can be used to reference a specified task. This value must be unique. (For details, see the following task section.) projects have the following attributes: attribute description required name Project name. no Default: the default target Yes basedir used when no target is specified is used to calculate the base path of all other paths. This attribute can be overwritten by the basedir property. This attribute is ignored when it is overwritten. If neither the attribute nor basedir property is set, use the parent directory of the buildfile file. The no project description appears as a top-level element (see the description section ). A project can define one or more targets. A target is a series of tasks you want to execute. When you execute ant, you can select the target to execute. If no target is specified, the target defined by the default attribute of the project is used. One target of targets can depend on other targets. For example, you may have a target for program compilation and a target for generating executable files. You must compile the executable file before it is generated. Therefore, the target of the generated Executable File depends on the compiled target. Ant will process this dependency. However, it should be noted that the ant depends attribute only specifies the order in which the target should be executed-if the target to be depended cannot be run, such depends will not affect the target with the specified dependency. Ant will execute each target in sequence (from left to right) according to the order in which the target appears in the depends attribute. However, remember that as long as a target depends on one target, the latter will be executed first. Suppose we want to execute target D. From its dependency attributes, you may think that C is executed first, B is executed, and A is executed finally. If yes, C depends on B and B depends on a. Therefore, execute A, B, C, and D first. A target can only be executed once, and multiple targets depend on it (see the preceding example ). If (or if not) Some attributes are set, a target is executed. In this way, the build process can be better controlled based on the system status (Java version, OS, command line attribute definition, and so on. If you want a target to do this, you should add the IF (or unless) attribute to the target element, with the target attribute for this judgment. For example, if there is no if or unless attribute, the target will always be executed. The optional description attribute can be used to provide a line description about the target, which can be output by the-projecthelp command line option. It is good to initialize your tstamp task in a so-called target. Other targets depend on this to initialize the target. Make sure that the initialization target is the first target in other target dependent tables. In this manual, most initialization targets are named "init ". Target has the following attributes: attribute description required name target name: Yes depends, a list of target names separated by commas (,), that is, a dependency table. No if: the attribute name to be set when target is executed. No unless target needs to clear the set attribute name. No description Brief description of the target function. No tasks a task is a piece of executable code. A task can have multiple attributes (you can call it a variable if you want ). The property may only contain references to the property. These references will be parsed before the task is executed. The following is the general construction form of a task: Here name is the name of the task, attributen is the attribute name, And valuen is the attribute value. There is a set of built-in (built-in) Tasks and some Optional tasks, but you can also write your own tasks. All tasks have a task name attribute. Ant uses attribute values to generate log information. You can assign an ID attribute to a task. Here, taskname is the name of the task, and taskid is the unique identifier of the task. With this identifier, You can reference the corresponding task in the script. For example, in the script, you can set the foo attribute of a task instance. In another task (written in Java), you can use the following statements to access the corresponding instance. Project. getreference ("task1 "). note 1: IF Task 1 is not running, it will not take effect (for example, if you do not set attributes). If you configure it later, everything you do will be overwritten. NOTE 2: Future ant versions may not be compatible with the attributes mentioned here, because there may be no task instances and only proxies. Properties a project can have many properties. Property tasks can be set in buildfile or outside ant. A property has a name and a value. Property can be used as the attribute value of a task. This is achieved by placing the attribute name between "$ {" and "}" and the attribute value. For example, if the value of a property builddir is "build", this property can be used for the property value $ {builddir}/classes. This value can be parsed to build/classes. If you use a task to define all system attributes, ant allows you to use these attributes. For example, the name of the operating system corresponding to $ {OS. name. For a list of System Properties, see the javadoc of system. getproperties. In addition to the system attributes of Java, ant also defines some built-in attributes: the absolute path of the basedir project base Directory (the same as the basedir attribute ). The absolute path of ant. File buildfile. Ant. Version ant version. Ant. project. name: the name of the project currently executed; it is set by the name attribute. ant. java. the JVM Version Detected by version ant. The current value is "1.1", "1.2", "1.3" and "1.4 ". in this example, Token filters can have many tokens in a project. These tokens will be automatically extended during file copy. Therefore, you must select the filter copy function in the task that supports this line. This function can be set in buildfile by using the filter task. Since this is probably a harmful behavior, the tokens in the file must be in the form of @ token @. Here the token is the token name set in the filter task. This token syntax is the same as that used to execute a file similar to filtering in other build systems, and does not conflict with most programming and scripting languages and document systems. Note: if a token in the form of @ token @ is found in a file, but no filter is related to the token, nothing will happen. Therefore, there is no escape method-but as long as you select a proper name for the token, there will be no problem. Warning If you enable the filtering function when copying binary files, you may destroy the files. This function is only applicable to text files. Path-like structures you can use ":" and ";" as the separator to specify references similar to path and classpath. Ant converts the separator to the one used by the current system. You can use nested elements to specify values similar to paths. Generally, the location attribute specifies a file and directory relative to the project base Directory, while the path attribute accepts a location list separated by commas or semicolons. The path attribute is generally used as a predefined path. In other cases, multiple location attributes should be used. For the sake of conciseness, The classpath label supports its own path and location attributes. Therefore, it can be written in a simple way: you can specify the path through the element. The order of adding multiple files in a fileset to path-like structure is not fixed. The preceding example constructs a path with the following values: $ {classpath}, followed by all jar files under the lib directory, followed by the classes directory. If you want to use the same path-like structure in multiple tasks, you can use elements to define them (the same as the target), and then use the ID attribute to reference them. For more information, see the referencs example. Path-like structure may include references to another path-like structurede (via nested elements): the concise writing mentioned above is also effective, for example: some tasks of command line variables accept parameters and pass them to another process. To include space characters in a variable, you can use nested Arg elements. Attribute description required value is a command line variable. It can contain space characters. A list of command line variables that can only be separated by one line space. File is the name of the command line variable. It is replaced by the absolute name of the file. PATH is a path-like string used as a single command line variable; or as a separator, ant converts it into a separator for a specific platform. The example is a single command line variable with spaces. Is a command line variable separated by spaces. Is a command line variable whose value is/DIR;/dir2;/dir3 on the dossystem;/DIR:/dir2:/dir3 on the UNIX system. The ID attribute of the references buildfile element can be used to reference these elements. This attribute is useful if you need to copy the same XML code block over and over again-for example, using the structure multiple times. The following example: all tasks that use patternsets, filesets, or path-like structures nested elements also accept this type of reference. Huihoo.com copyright (2001,2002, mpeg2004) allright reseved