WebSphere Studio Application Developer Version 5 Programming Guide part 67 pps

634 WebSphere Studio Application Developer Version 5 Programming Guide What is Ant? Ant is a Java-based, platform independent, open source build tool. It was formerly a sub-project in the Apache Jakarta project, but in November 2002, it was migrated to an Apache top-level project. Ant’s function is similar to the make tool but, at least according to Ant’s Web page, without its wrinkles. As it is Java-based and does not make use of any OS-specific functions, it is platform independent, allowing you to build your projects using the same build script on any Java-enabled platform. To control what operations Ant should perform during your build, you supply it an XML-based script file. This file not only defines what operations to perform but also in which order they should be performed and any dependencies between them. Ant comes with a large number of built-in tasks sufficient to perform many common build operations. However, if the tasks included are not sufficient, you also have the ability to extend Ant’s functionality by using Java to develop your own specialized tasks. These tasks can then be plugged into Ant. Not only can Ant be used to build your applications, but it can also be used for many other operations such as retrieving source files from a version control system, storing the result back in the version control system, transferring the build output to other machines, deploying the applications, generating Javadoc, and sending messages, for example, when a build is finished. To find out more about Ant, visit the Ant Web site at: http://ant.apache.org/ This chapter provides a basic outline of the features and capabilities of Ant. For complete information you should consult the Ant documentation included in the Ant distribution or available on the Internet at: http://ant.apache.org/manual/index.html Note: Application Developer includes Ant version 1.4.1. Chapter 19. Building applications with Ant 635 Sample demo project and application To show you the basic concepts of Ant we wrote a really simple Java application, HelloAnt. This is simply a Hello World program that prints a message to stdout. We created a new Java project for this that we called ItsoProGuideAnt. In this project we created a Java package called itso.ant.hello and a class called HelloAnt. Since these steps are basic Application Developer tasks and the application does nothing but a simple System.out.println("Hello Ant") we do not show them here. The source code is available in: \sg246957\sampcode\deploy-ant\simple Ant build files Ant uses XML build files to define what operations must be performed to build a project. These are the main components of a build file:  project—A build file contains build information for a single project. It may contain one or more targets .  target—A target describes the tasks that must be performed to satisfy a goal, for example compiling source code into class files may be one target, and packaging the class files into a JAR file may be another target. Targets may depend upon other targets, for example the class files must be up to date before you can create the JAR file. Ant resolves these dependencies.  task—A task is a single step that must be performed to satisfy a target. Tasks are implemented as Java classes that are invoked by Ant, passing parameters defined as attributes in the XML. Ant provides a set of standard tasks (core tasks), a set of optional tasks, and an API which allows you to write your own tasks.  property—A property has a name and a value. Properties are essentially variables that can be passed to tasks through task attributes. Property values can be set inside a build file, or obtained externally from a properties file or from the command line. A property is referenced by enclosing the property name inside ${}, for example ${basedir}.  path—A path is a set of directories or files. Paths can be defined once and referred to multiple times, easing the development and maintenance of build files. For example, a Java compilation task may use a path reference to determine the classpath to use. 636 WebSphere Studio Application Developer Version 5 Programming Guide Ant tasks A comprehensive set of built-in tasks are supplied with the Ant distribution. The tasks that we use in this example are described below: delete Deletes files and directories echo Outputs messages jar Creates Java archive files javac Compiles Java source mkdir Creates directories tstamp Sets properties containing date and time information Creating a simple build file We created a simple build file that compiles the Java source for our HelloAnt application and generates a JAR file with the result. The build file is called build.xml, which is the default name assumed by Ant if no build file name is supplied. Our simple build file has the following targets: init Performs build initialization tasks—all other targets depend upon this target compile Compiles Java source into class files dist Creates the deliverable JAR for the module—depends upon the compile target clean Removes all generated files—used to force a full build Each Ant build file may have a default target. This target is executed if Ant is invoked on a build file and no target is supplied as a parameter. In our case the default target is dist. The dependencies between the targets are illustrated in Figure 19-1. Chapter 19. Building applications with Ant 637 Figure 19-1 Ant example: dependencies To create the simple build file, do the following:  Select the ItsoProGuideAnt project and select New -> File from its context menu.  Enter build.xml as the filename and click Finish (Figure 19-2). Figure 19-2 Creating a build.xml file  Then paste the text in Figure 19-3 into the file. depends on clean init dist compile 638 WebSphere Studio Application Developer Version 5 Programming Guide Figure 19-3 build.xml file We will now walk you through the different sections of this file, explaining each of them. Project definition The project tag in the build.xml file defines the project name and the default target. The project name is an arbitrary name, it is not related to any project name in your Application Developer workspace. <?xml version="1.0" encoding="UTF-8"?> <project name="HelloAnt" default="dist" basedir="."> <! set global properties for this build > <property name="build.compiler" value="org.eclipse.jdt.core.JDTCompilerAdapter"/> <property name="source" value="."/> <property name="build" value="build"/> <property name="disributet" value="dist"/> <property name="outFile" value="helloant"/> <target name="init"> <! Create the time stamp > <tstamp/> <! Create the build directory structure used by compile > <mkdir dir="${build}"/> </target> <target name="compile" depends="init"> <! Compile the java code from ${source} into ${build} > <javac srcdir="${source}" destdir="${build}"/> </target> <target name="dist" depends="compile"> <! Create the distribution directory > <mkdir dir="${distribute}/lib"/> <! Put everything in ${build} into the output JAR file > <! Add a timestamp to the output filename as well > <jar jarfile="${distribute}/lib/${outFile}-${DSTAMP}.jar" basedir="${build}"/> </target> <target name="clean"> <! Delete the ${build} and ${distribute} directory trees > <delete dir="${build}"/> <delete dir="${distribute}"/> </target> </project> Chapter 19. Building applications with Ant 639 The project tag also sets the working directory for the Ant script. All references to directories throughout the script file are based on this directory. A dot (".") means to use the current directory which, in Application Developer, is the directory where the build.xml file resides. Global properties Properties that will be referenced throughout the whole script file can be placed at the beginning of the Ant script. Here we define the property build.compiler that tells the javac command what compiler to use. We will tell it to use the Eclipse compiler. We also define the names for the source directory, the build directory, and the distribute directory. The source directory is where the Java source files reside. The build directory is where the class files end up, and the distribute directory is where the resulting JAR file is placed:  We define the source property as ".", which means it is the same directory as the base directory specified in the project definition above.  The build and distribute directories will be created as build and dist directories. Properties can be set as shown below, but Ant can also read properties from standard Java properties files or use parameters passed as arguments on the command line: <! set global properties for this build > <property name="build.compiler" value="org.eclipse.jdt.core.JDTCompilerAdapter"/> <property name="source" value="."/> <property name="build" value="build"/> <property name="distribute" value="dist"/> <property name="outFile" value="helloant"/> Build targets The build file contains four build targets: init, compile, dist and clean. Initialization target The first target we describe is the init target. All other targets (except clean) in the build file depend upon this target. In the init target we execute the tstamp task to set up properties that include timestamp information. These properties are then available throughout the whole build. We also create a build directory defined by the build property. 640 WebSphere Studio Application Developer Version 5 Programming Guide <target name="init"> <! Create the time stamp > <tstamp/> <! Create the build directory structure used by compile > <mkdir dir="${build}"/> </target> Compilation target The compile target compiles the Java source files in the source directory and places the resulting class files in the build directory. <target name="compile" depends="init"> <! Compile the java code from ${source} into ${build} > <javac srcdir="${source}" destdir="${build}"/> </target> With these parameters, if the compiled code in the build directory is up-to-date (each class file has a timestamp later than the corresponding Java file in the source directory), the source will not be recompiled. Distribution target The distribution target creates a JAR file that contains the compiled class files from the build directory and places it in the lib directory under the dist directory. Because the distribution target depends on the compile target, the compile target must have executed successfully before the distribution target is run. <target name="dist" depends="compile"> <! Create the distribution directory > <mkdir dir="${distribute}/lib"/> <! Put everything in ${build} into the output JAR file > <! We add a time stamp to the filename as well > <jar jarfile="${distribute}/lib/${outFile}-${DSTAMP}.jar" basedir="${build}"/> </target> Cleanup target The last of our standard targets is the cleanup target. This target removes the build and distribute directories which means that a full recompile is always performed if this target has been executed. <target name="clean"> <! Delete the ${build} and ${distribute} directory trees > <delete dir="${build}"/> <delete dir="${distribute}"/> </target> Note that our build.xml file does not call for this target to be executed. It has to be specified when running Ant. Chapter 19. Building applications with Ant 641 Running Ant Ant is a built-in function in Application Developer. You can launch it from the context menu of any XML file although it will run successfully only on valid Ant XML build script files. When launching an Ant script, you are given the option to select which targets to run and if you want to view the output in a special Log Console window. To run our build script, we select the build.xml file, open its context menu and select Run Ant as shown in Figure 19-4. Figure 19-4 Launching Ant Application Developer displays the Run Ant dialog (Figure 19-5), which allows you to select the targets to run. The default target specified in the build file is already selected as one target to run. You can check, in sequence, which ones are to be executed, and the execution sequence is shown next to each target. Note that because dist depends on compile, even if you only select dist, the compile target is executed as well. 642 WebSphere Studio Application Developer Version 5 Programming Guide Figure 19-5 Selecting Ant targets to run In the Arguments field, you can supply additional parameters to Ant, but we leave that empty for now. If Show execution log in console is selected, messages from Ant are displayed in the Log Console. If this is not selected, you will not see any output from Ant, so make sure it is checked for now. Then click Finish to run Ant. When Ant is running, you see the output in the Log Console (Figure 19-6). Figure 19-6 Log Console The Log Console view opens automatically when running Ant, but if you want to open it manually, select Window -> Show view -> Log Console . The Log Console shows that Ant has created the build directory, compiled the source files, created the dist\lib directory, and generated a JAR file. Chapter 19. Building applications with Ant 643 Where is the output? The Package Explorer view does not show any of the generated files. Application Developer does not know automatically that Ant generated files in the project. Select the ItsoProGuideAnt project and Refresh (context). Now you can see the JAR files in the Package Explorer view. To see the class files you have to open the Navigator view (Figure 19-7). Figure 19-7 Ant generated files Rerunning Ant If you launch Ant again with the same target selected, you will see the following in the Log Console. Figure 19-8 Log Console on second run As you can see, Ant did not do anything at all, because the build and dist\lib directories were already created and the class files in the build directory were already up-to-date. . select dist, the compile target is executed as well. 642 WebSphere Studio Application Developer Version 5 Programming Guide Figure 19 -5 Selecting Ant targets to run In the Arguments field, you. may use a path reference to determine the classpath to use. 636 WebSphere Studio Application Developer Version 5 Programming Guide Ant tasks A comprehensive set of built-in tasks are supplied. Figure 19-3 into the file. depends on clean init dist compile 638 WebSphere Studio Application Developer Version 5 Programming Guide Figure 19-3 build.xml file We will now walk you through the