antInclude is a set of reusable Apache Ant targets. The goal of antInclude is to standardize project build files and avoid excessive redundancy. The antInclude targets are defined in Ant XML Fragment (AXF) files. These fragments are not complete XML files, therefore they only are correctly interpreted when expanded in a project build file. The fragment inclusion is made using XML entities, like in the following example: ]> &antIncludeCore; In this example the contents of the file located at "../antInclude/core.axf" are expanded in place at "&antIncludeCore;". The AXF files are stored in the antInclude directory next to the other project directories. There are two types of AXF: - Project AXF - Environment AXF A project AXF contains a set of targets and properties to support the build process for specific project types: - antInclude core (core.axf) - command-line application (cmdApp.axf) - JAR archive support (jar.axf) - web application (webApp.axf) - Struts web application (strutsApp.axf) - BERSERK application (berserkApp.axf) - web service (webSvc.axf) - web service client (webSvcCli.axf) - uddi publish, delete and query (uddi.axf) - Unit testing (junit.jar) - Unit testing using databases (dbUnit.jar) An environment AXF contains specific targets and properties to support application servers or execution environments. It defines library classpaths among other useful properties and targets: - envJwsdp15.axf - Java Web Services Developer Pack 1.5 - envTomcat5.axf - Tomcat 5.0 - envImq3.axf - Sun Message Queue 3.0 AXF dependencies ---------------- Some AXF files need definitions from other AXF files. These dependencies are verified using the ant task. AXF properties default values ----------------------------- Most of the settings assumed in the AXF targets use properties with default values. In most cases it's not necessary to override these values. To override the property must be defined before. This behaviour exists because each ant property can only be set once. Therefore, the first (temporal) definition is the one that is used. In antInclude, properties can be overriden by definining them before the AXF includes, or by using a file named "build.properties" in the project directory, in the project parent directory or in the user home directory. The targets that don't define default values for properties require their definition and verify it using the ant task. Standard project directory structure ------------------------------------ The following directories are the joint-set of directories used in all project types. Depending on the project type (cmdApp, webApp, ...), only a sub-set of the directories are used. / Root directory. The project 'build.xml' file should be here. This file should include the necessary ant build file fragments and define the project specific variables and targets. A 'build.properties' file can be created here to override property values. (used in all project types) /src Java source code directory. All java files should be stored in sub-directories according to the class package, for example: proj.Hello in src/proj/Hello. (used in all project types) /src/web Web resource files (HTML, JSP, images, ...) directory. These files can be organized in a project specific directory structure. (used in webApp projects) /src/java Java source code directory for webApp projects. (used in webApp projects) /lib Project libraries directory. Project-specific JAR libraries should be placed here. (used in all project types) /config Configuration files directory. Each subdirectory contains configuration files for a particular purpose. Examples: - config/jar - stores JAR archive manifest file - config/web - stores web.xml - config/struts - config/berserk - config/webSvc - web service configuration file (jaxrpc-ri.xml) - config/webSvcCli - web service client configuration file is stored in , - ... (used in project types where configuration files are necessary) /etc Directory for additional project files, that don't fit in another standard directory. These files can be: database scripts, data files (text or xml), readme files, etc. (can be used by all project types, in a project-specific way) /build Build directory (TEMPORARY - all its contents are subject to deletion) All intermediate files necessary to build projects are created in this directory. (used in all project types) /build/classes Class compilation directory (TEMPORARY) Mirrors /src sub-directory structure. Instead of .java files, contains the compiled .class Java bytecode files. (used in all project types) /dist Distribution files directory (TEMPORARY - all its contents are subject to deletion) All project distribution packages (JAR, WAR, ...) are created here as results of the build process. The distribution packages contain all the information necessary to install and execute the project. (used in all project types) /doc Java documentation files (TEMPORARY - its contents are subject to deletion) Directory where javadoc output files are generated. Javadoc files are used to extract special code comments and generate html documentation for a project. (used in all project types that have javadoc formatted comments) ../extensions (default value) Directory for libraries shared between projects in sibling directories. Usually all these projects are related. Additional remarks ------------------ Directory-related property conventions: .reldir - relative path (build/classes) .dir - absolute path (c:/proj/build/classes) File-related property conventions: .filename - file name (config.xml) .file - absolute or relative file path (c:/proj/config/web/web.xml or config/web/web.xml) --- Last review: $Id: readme.txt,v 1.1 2006-01-02 23:37:12 smf Exp $