Original: http://www.onjava.com/pub/a/onjava/2003/12/17/ANT_BestPractices.html
STONEXU
QQ: 19722707
MSN: Xt121@hotmail.com
Before Ant appears, compile and deploy Java applications requires hodgepodges that include scripts including specific platforms, Make files, different IDEs, and handmade operations. Now, almost all open source Java projects are using Ant, and many company development projects are also using ANT. Aunt's large use, naturally brought urgent needs to summarize Ant best practices.
This article summarizes my good ANT best practice, many of the projects that have experienced projects, or from other developers' "horror" story inspiration. For example, someone tells me that there is a project to put the code generated by the XDoclet into the version control tool of the locked file. When a single 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 when he can let Ant compile the code, and 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 manually determined by programmers.
Ant's build file should define the correct task dependencies so that programmers do not have to call tasks in a specific order.
When I started a new project, I first write Ant build files. The process of defining the built-in builds and uses each programmer in the team. All best practices in this article assume that Ant build files are important files that must be carefully prepared, which should be maintained in the version control system, and reconstruct it regularly. Below is my fifteen big Ant best practices.
1. Adopt consistent coding specifications
Ant users are willing to jump into this charming debate whether they like or hate XML build files. Let's take some way to keep XML build files.
First of all, it is also the most important, time formatting your XML makes it look very clear. However, XML is beautiful, Ant can work. But ugly XML is hard to read. If you leave a blank line between the tasks, there is rule indentation, each line is not more than 90 columns, then XML is surprising to read. Plus a good editor or IDE highlight the corresponding statement, you will not read the trouble. Similarly, the selection is clear and easy to read to naming tasks and properties. For example, Dir.Reports is better than RPTS. It does not require specific coding specifications, as long as there is a norm and stick to it.
2. Place build.xml in the project root directory
Ant build files build.xml can be placed on how, but placed in the top of the project to keep the project is concise. This is the most common specification that makes developers to find it at the root directory. At the same time, it is also possible to understand the logical relationship between different directories in the project. Here is a typical project level:
[root dir]
| build.xml
- SRC
- LIB (including third-party JAR package)
- Build (Generated by Build Task)
- Dist (generated by Build Task)
When build.xml is in a top-level directory, if you are in a subdirectory, just enter: Ant -Find compile command, you do not 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 decompose a large project to several small build files, each build file sharing a small part of the entire build process. However, it should be appreciated that the construction of file segmentation will increase the difficulty of understanding the entire build process. Be careful not to be an Over-Engineer if the single build file can be clearly manifesting. 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 easiest rule is to add a description for all tasks you want programmers directly call directly 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. Description = "Display Detailed Usage Information"> 5. Provide empty tasks Each build file should contain a clear task, delete all generated files and directories, so that the system returns to the initial state before the build file is executed. The files still exist after the emptying task should be in the management of the version control system. such as: 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, which is inexhaustible. 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 large systems, you need to clearly define which layer of the Java package belongs to the system. Otherwise how to recompile thousands of files. The difference between task dependence management will lead 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 IDE uses a single ClassPath when compiling files. ANT makes you more effectively control the build activity. Design your 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 framework, reference the high-level GUI template component, at this time, the code does not need to be compiled. This is because the build file is compiled under the underlying framework, there is no code including the high-level GUI panel component in the source path. 7. Define and reuse file paths If the file path is defined in one place and is reused throughout the build file, the build file is easier to understand. The following is an example of doing this: ... ETC When the project grows, this technology is more complicated, and this technology is more embodied. You may define your respective file paths for compilation of different levels of applications, such as running units, running xDoclets, generating javadocs, etc., to generate javadocs. 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 task depending on the relationship. 8. Define the right task parameter relationship Suppose the DIST task is from the JAR task, then which task is from the Compile task, which task deviates 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 is very difficult to build work due to unnecessary dependence. For example, you may find that when programmers just need to compile some GUI code that does not use EJB, regenerate EJB code. 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 experts skip some steps during fast and annoying encoding 9. Using configuration 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 properties file Sample.Properties: Dir.build = build Dir.src = SRC Jdom.home = .. / java-Tools / JDOM-B8 jday.jar = jday.jar JDom.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 a development source code, you should provide a release version of all the JAR files that needed, of course, on the basis of compliance with the license agreement. For internal projects, the relevant JAR files should be in the management of the version control system and to the location of everyone know. When you have to apply an external path, the path should be defined as attributes. Make the programmer to overload the parameters of their own machines to overload these properties. You can also use the following syntax to reference environment variables: 11. Using the version control system Building a file is an important file, which should be controlled like a code. When you mark your code, you also apply the same tag tag to build a file. This allows you to build a file using the corresponding older version of the file when you need to retrore the old version of the software. 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 store build output 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 IDE, why is you worried about the programmer by clicking the icon? The issue of IDE is a problem about consistency and reproducibility in the team. 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 lead to this situation: run a good code there, where you can't run it. 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 they used to use. But Ant should be used as a public baseline to ensure that it 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 to copy a large pile of files into the temporary directory in accordance with 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. Run the test of Clean build tasks 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. The building file should only 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 don't have to compile, copy, or other tasks. When the project size grows, even small inefficient work will become a big problem. 15. Avoid ANT packages for a specific platform 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 fully typing Ant Compile. Please do not use only the script of a specific platform to call Ant. This will only increase the harassment of learning and understanding when others use your script 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 procedures to compile code and generate software release versions. Those developing teams that do not use the Ant or similar tools, spend a surprising time to capture problems in the code compilation process, which compiles successful code in some developers, but also some developers there Failed. Generating and maintaining building scripts is not a charming job, but it is a necessary job. A good Ant build file will make you 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
