Ant 15 Best Practices
Author: Eric M. Burke, coauthor of Java Extreme Programming Cookbook
Original: http://www.onjava.com/pub/a/onjava/2003/12/17/ANT_BestPractices.html
Translator: Xu Wei MSN: Xt121@hotmail.com
Before Ant appears, build and deploy Java applications require use of scripts including specific platforms, Make files, various versions of IDE, and even manual "hodgepodge". Now, almost all open source Java projects are using Ant, most companies' internal projects are also using ANT. The wide use of Ant in these projects naturally leads to an urgent need for readers' best practices in Ant.
This article summarizes my favorite Ant skill or best practice, most of the "terror" story that I personally experienced or the "terror" story I have heard of the "terror" story. For example, someone tells me that there is a project to put the code generated by the XDoclet into the version control tool with the lock file function. When the developer modifies the source code, he must remember the check out and lock all files that will be regenerated. Then, manually run the code generator, only when he can let Ant compile the code, this method still has some problems:
The generated code cannot be stored in the version control system. Ant (this case is xDoclet) should automatically determine the source file involved next time, and should not be determined by the programmer. The build file of Ant should define the correct task dependencies so that the programmer does not have to bundle the task in accordance with the specific order.
When I started a new project, I first write Ant build files. The ANT file explicitly defines the built-in process and is used by each programmer in the team. The techniques listed herein are based on such assumptions: ANT build files are important files that must be carefully prepared, which should be maintained in the version control system and regularly reconstructed. Below is my fifteen big Ant best practices.
1. Adopt consistent coding specifications
Ant users have XML syntax that likes to hate their build files. Instead of jumping into this confused debate, let us first look at some methods that keep the XML build files.
The first is also the most important, spending time formatting your XML makes it very clear. Whether the XML is beautiful, Ant can work. But ugly XML is difficult to read. If you leave an empty line between the tasks, there is rule indentation, each line is not more than 90 columns, then XML is surprisingly easy to read. Coupled with an excellent editor or IDE tool that is highlighting XML syntax, you will not have trouble.
Similarly, the selected words are clear and easy to read to name tasks and properties. For example, Dir.Reports is better than RPTS. The specific coding specification is not important, just take a set of specifications and insist on using it.
2. Place build.xml in the project root directory
Ant build files build.xml can be placed in any location, but placed in the top-level directory of the project. This is the most commonly used specification, developers can find expected build.xml in the top directory. Place the build file in the root directory and enable people to easily understand the logical relationship between the different directories in the project directory tree. The following is a typical project directory level:
[root dir] | build.xml - src - lib (including third-party JAR package) - build (generated by Build Task) - Dist (Generated by Build Task)
When building.xml is in the top-level directory, assume you in a subdirectory, just enter: Ant -Find compile command, you don't need to change the work directory to compile the code. Parameters -Find tells Ant to find Build.xml existing in the superior directory and execute. 3. Use a single build file
Some people like to break a big project into several small build files, each build file sharing a small part of the entire build process. This is indeed different problems, but it should be recognized that the building file segmentation will increase the difficulty of understanding the overall build process. Be careful not to be an Over-Engineer if the single build file can clearly manifest the build level.
Even if you divide the project into multiple build files, you should also make programmers to find core build.xml in the project root directory. Although the document is just appointed the actual build work to the lower-level build file, it should be guaranteed that the file is available.
4. Provide good help notes
The construction file should be as self-documentation. Increasing task description is the easiest way. When you enter Ant -ProjectHelp, you can see the task list with a description. For example, you can define this task: Description = "Compiles Code, Output Goes to the Build Dir."> The simplest rule is to add all the tasks you want to make the programmer can call through the command line. For internal tasks typically used to perform intermediate processing, such as generating code or establish an output directory, etc., the description properties cannot be used. At this time, it can be processed by adding an XML annotation in the build file. Or specifically define a Help task, showing a detailed instructions when the programmer inputs Ant Help. 5. Provide clear tasks Each build file should contain a clear task to delete all generated files and directories, so that the system returns to the initial state before the build file is executed. The files that are still existing after the emptying task should be under the management of the version control system. For example: Description = "Destroys All generated files and dirs."> Do not automatically call the Clean task unless you generate a special task of the entire system version. When the programmer only performs compilation tasks or other tasks, they don't need to build files in advance, which is both annoying and unnecessary empty tasks. To believe that programmers can determine when all files need to be emptied. 6. Use the ANT management task dependency Suppose your application consists of Swing GUI components, web interfaces, EJB layers, and public application code. In a large system, you need to clearly define which layer of each Java belongs to the system. Otherwise, any changes must be re-compiled into 100 thousand files. The bad task is from the relationship management that leads to excessive complex and fragile systems. Change the design of the GUI panel should not cause recompilation of servlet and EJB. When the system becomes huge, it is slightly not paying attention to the server that can be rely on the client's code. This is because typical IDE project files compile any files using a single ClassPath. And Ant allows you to control build activities more effectively. Design your Ant build file to compile large projects: First, compile the public application code and make the compile result into a JAR package file. Then, compile the previous item code, rely on the JAR file generated by the first step when compiling. Continue to repeat this process until the highest layer code is completed. Step by step construction strengthens the management of the task. If you work on the underlying Java frame, you accidentally reference the high-level GUI template assembly, and the code does not need to be compiled. This is because the build file does not include the code of the high-rise GUI panel component in the source path when compiling the underlying frame. 7. Define and reuse file paths If the file path is defined in one place, it is more prone to understanding in the entire build file. The following is an example of this: ... etc This technology is more and more embodied when the project grows increasingly complex. You may need to define your file paths for compilation of different levels of applications, such as running unit testing, running the application, running xDoclet, generating javadocs, etc. Different paths. This method of component-defined path definitions is much more advantageous to define a path individually for each task. Otherwise, it is easy to lose the trajectory of the task depending on the relationship. 8. Define the right task dependence Suppose the DIST task is from JAR tasks, then which task deviates from the COMPILE task from the prepare task? The ANT build file finally defines the dependgram of the task, which must be carefully defined and maintained. The dependence of the task should be checked regularly to ensure that the build work is implemented correctly. Big build documents tend to increase more tasks over time, so it may be very difficult to build work due to unnecessary dependence. For example, you may find that the EJB code is regenerated when programmers only need to compile some GUI code that does not use EJB. The dependence of ignoring the task with the name of "Optimization" is another common error. Such a mistake forces the programmer to remember and call a string task in a specific order. Better approach is to provide a clear public task that includes the correct task dependence; additional "Expert" tasks allow you to manually perform individual build steps, these tasks do not provide a complete build process, but Let those expert users skip certain steps during fast and annoying encoding. 9. Using properties Any information that needs to be configured or possible should be defined as an ANT attribute. For values that appear multiple times in the build file, also processed. Attributes can be defined in a separate attribute file in building a file header or for better flexibility. The following is a style that defines attributes in the build file: Value = "$ {jdom.home} / build / $ {jdom.jar}" /> ETC ... Or you can use the properties file: ETC ... In the attribute file Sample.Properties: Dir.Build = Build Dir.src = SRC Jdom.home = .. / java-Tools / JDOM-B8 JDom.jar = jdom.jarjdom.jar.withPath = $ {jdom.home} / build / $ {jdom.jar} Define attributes with a separate file that is good, it can clearly define the configurable parts in the built. In addition, in the case of developers working in different operating systems, you can provide different versions of the file on different platforms. 10. Maintain the construction process For maximum scalability, do not apply external paths and library files. The most important thing is to rely on programmers' ClassPath settings. Instead, the relative path is used in the build file and define its own path. If you reference absolute paths such as C: / Java / Tools, other developers may not use the same directory structure as you, so you can't use your build file. If you deploy an open source project, you should provide a release version of all JAR files needed to compile code. Of course, this is based on the license agreement. For internal projects, the relevant JAR files should be in the management of the version control system, and pick out to everyone. When you must reference an external path, the path should be defined as attributes. Make the programmer to overload these properties with parameters suitable for their own machine environment. You can also use the following syntax to reference environment variables: 11. Using the version control system Building a file is an important product, which should be controlled like a code. When you mark your code, you also apply the same tag tag to build a file. This will use the corresponding version of the build file when you need to go back to the old version and build. In addition to building files, you should also maintain a third-party JAR file in version control. Similarly, this allows you to re-build the old version of the software. This can easily ensure that all developers have a consistent JAR file because they are all from the version control system together with the build file. It is usually avoided to save the construction results in the version control system. If your source code is well received, you can regenerate any version of the product by building a building process. 12. Take Ant as a "minimum bithotherm" Suppose your development team uses the IDE tool, how do you have to worry about Ant when you can build the entire app by clicking the icon? The IDE problem is a question about team consistency and reproducibility. Almost all IDE design is to improve the personal productivity of programmers, not the continuous construction of the development team. Typical IDE requires each programmer to define its own project files. Programmers may have different directory structures, which may use different versions of library files, which may also work on different platforms. This will result in this situation: run good code in Bob, you can't run until Sally. No matter what IDE your development team uses, you must build all the Ant build files that all programmers can use. To create a programmer, you must perform the rules of the ANT build file before submitting a new code control system. This will ensure that the code is built by the same ANT build file. When there is a problem, use the project standard Ant build file instead of an IDE to perform a clean built. Programmers can freely choose any IDE tool or editor that they are used to use. However, Ant should be used as a public baseline to ensure that the code is always built. 13. Using ZipFileSet properties People often use ANT to produce WAR, JAR, ZIP, and EAR files. These files usually require a specific internal directory structure, but it is often mismatched with the directory structure of your source code and compilation. A most common method is to write an Ant task, copy a large pile of files to the temporary directory according to the desired directory structure, and then generate a compressed file. This is not the most effective way. Using ZipFileSet properties is a better solution. It allows you to select files from any location and put them in different directory structures into the compressed file. The following is an example: Appxml = "$ {Dir.Resources} /Application.xml"> In this example, all JAR files are placed in the lib directory of the EAR file package. Hr.jar and billing.jar are from building a directory. So we use the ZipFileSet property to move them to the lib directory inside the EAR file. The Prefix property specifies its target path in the EAR file. 14. Test the Clean task Suppose you have the task of Clean and Compile in your build file, do the following tests. The first step is to execute Ant Clean; step 2, execute Ant Compile; third step, execute Ant Compile. The third step should not be anything. If the file is compiled again, you have a problem with your building file. Building a file should perform tasks only when the input file associated with the output file is changed. A build file is inefficient if you do not have to perform these tasks when you do not have to perform such tasks. When the project size grows, even small inefficient work will become a big problem. 15. Avoid ANT packages for specific platforms No matter what reason, some people like to load their products or scripts with a batch file or script called Compile. When you go to the script, you will find the following: Ant Compile In fact, developers are familiar with Ant and are fully typed in Ant Compile. Please do not use only the script of a specific platform to call Ant. This will only make other people add a biotuda of learning and understanding when using your scripts for the first time. In addition, you can't provide a script for each operating system, which is a place really bothering other users. to sum up Too many companies rely on manual methods and special programs to compile code and generate software release versions. Those developers that do not use the Ant or similar tool definition build procedures, spend too much time to capture problems in the code compilation process: Compile success in some developers, but also failure there. . Generating and maintaining building scripts is not a charming job, but it is a necessary job. A good Ant build file will allow you to concentrate on a more favorite job - write code! reference Ant Antgraph: Ant Dependency Visualization Tool Ant: The Definitive Guide, O'Reilly Java Extreme Programming Cookbook, O'Reilly
